This workflow is ideal for serverless web applications and applications that run entirely in a browser using the OAuth 2.0 implicit grant.
Note: If you are using the ArcGIS API for JavaScript you can skip to learning how this work-flow is implemented in the ArcGIS API for JavaScript as part of IdentityManager
.
- Direct your users to the authorization endpoint
https://www.arcgis.com/sharing/rest/oauth2/authorize
in a browser with yourclient_id
,response_type=token
, aredirect_uri
and optionalexpiration
. - If the user successfully presents their username and password they will be redirected back to your application at the
redirect_uri
from step 1. Theaccess_token
and additional information will be added to the end of the URL as a hashhttp://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600
. Your application can parse the URL for the user's token. - Now that you have the access token, include it in requests to ArcGIS Online which require a
token
.
Configuring a redirect URI
- Go to the "Authentication" tab for your application on ArcGIS for Developers.
- Add a new redirect URI to the list at the bottom of the page. These redirect URIs represent the valid places that a user can be redirected to after a successful sign in.
Note: You can also configure a redirect URI on ArcGIS Online or in your own on-premise portal
You cannot use redirect URIs that begin with file://
. For browser based applications you should always use redirect URIs starting with https://
. URIs starting with http://
can be used in development where no SSH is available.
Send the user to the authorization URL
ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/authorize/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize
A sample authorization URL for ArcGIS Online might look like this.
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=YOUR_APPLICATIONS_CLIENT_ID&response_type=token&expiration=20160&redirect_uri=A_REDIRECT_URI_FOR_YOUR_APPLICATION
You could also construct an <a>
tag like so
<a href="https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=YOUR_APPLICATIONS_CLIENT_ID&response_type=token&expiration=20160&redirect_uri=A_REDIRECT_URI_FOR_YOUR_APPLICATION">Sign In With ArcGIS Online</a>
Or open the authorization page in a popup window.
var clientId = 'YOUR_APPLICATIONS_CLIENT_ID';
var redirectUri = 'A_REDIRECT_URI_FOR_YOUR_APPLICATION';
var signInButton = document.getElementById('sign-in');
// do this on a button click to avoid popup blockers
document.addEventListener('click', function(){
window.open('https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id='+clientId+'&response_type=token&expiration=20160&redirect_uri=' + window.encodeURIComponent(redirectUri), 'oauth-window', 'height=400,width=600,menubar=no,location=yes,resizable=yes,scrollbars=yes,status=yes')
});
This URL contains the following pieces of information:
client_id
- The client id of your application. See registering your application to find your client_idredirect_uri
- A redirect URI for your application. See configuring the redirect URIresponse_type
- theresponse_type
should always betoken
expiration
- optional expiration after which the token will expire. Defined in minutes with a maximum of 2 weeks (20160 minutes).
Once your send the user to the authorization screen they will sign in with their username and password. This is what a sample authorization screen will look like:
Once a user has authorized your application they will be redirect to the redirect_url
that you specified when you directed the user to the authorization screen.
Parse the token from the URL
After the user signs in, they will be redirected to a page on your web application. Usually this page will be something like http://example.com/oauth-callback.html
. The user's access token will be a part of the URL:
http://example.com/oauth-callback.html#access_token=mpd9uhQPuHBOkQPCqkT7vhAMk8P2YNA-dEMhwYt5Gp535k92BshScRcZ8dEIuAxvFALxOn6M0RTonme9DzQ9PdwT3vr17yoOdxON5vnlpXUQcOWOu3u8EBT-xSR_zWRpna7Y2-avCVtND55HNX5Egg..&expires_in=3600
Your page will need to parse out the access_token
out of window.location.hash
and either pass it to the parent page (if opened in a pop-up) or direct the user to another page after setting the token in a cookie or other persisted storage.
Here is an example of parsing the access token when the window was opened as a pop-up:
<!DOCTYPE html>
<head></head>
<body>
<script>
// try to match an access token in window.location.hash
var match = (window.location.hash) ? window.location.hash.match(/#access_token=([^&]+)/) : false;
// if we found an access token in the URL pass the token up to a global function in
if(match[1]) {
var parentWindow = (window.opener && window.opener.parent) ? window.opener.parent : window
parentWindow.oauthCallback(match[1]);
}
window.close();
</script>
</body>
</html>
You can also use a regular expression to extract the user's username
from window.location.hash
. User names are guaranteed to be unique across the entire platform.
Token expiration
Tokens obtained through this workflow will always expire and cannot be refreshed. If a token expires, you have to sign the user in again.
If you need the ability to have longer sessions or refresh a user's token, you should use the server-based workflow.
Using the ArcGIS API for JavaScript
The ArcGIS API for JavaScript implements the above workflow as a part of the IdentityManager
class. If you are using the ArcGIS API for JavaScript you should refer to these examples that implement named user login:
Using the ArcGIS API for JavaScript IdentityManager
will automatically manage the user's credentials including storing and persisting them across browsing sessions and automatically adding them to requests when necessary.
More Samples
More examples of implementing named user login can be found for these APIs: