Browser-based Named User Login

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.

1. Direct your users to the authorization endpoint https://www.arcgis.com/sharing/rest/oauth2/authorize in a browser with your client_id, response_type=token, a redirect_uri and optional expiration.
2. If the user successfully presents their username and password they will be redirected back to your application at the redirect_uri from step 1. The access_token and additional information will be added to the end of the URL as a hash http://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600. Your application can parse the URL for the user's token.
3. Now that you have the access token, include it in requests to ArcGIS Online which require a token.

Configuring a redirect URI

1. Go to the "Authentication" tab for your application on ArcGIS for Developers.
   
   
2. 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.
   
   

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_id
• redirect_uri - A redirect URI for your application. See configuring the redirect URI
• response_type - the response_type should always be token
• 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:

• Basic User Login
• User Login with Popup

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:

• Esri Leaflet
• ArcGIS REST JS