Serverless web app workflow

This workflow is ideal for serverless web applications and applications that run entirely in a browser using the OAuth 2.0 implicit grant type.

Overview

Browser-based authentication

  1. Direct your users to the authorization endpoint in a browser (pop-up or a new tab) with your client_id, response_type=token, a redirect_uri, and an optional expiration.

  2. The user successfully provides their username + password.

  3. The pop-up or tab is redirected back to your application's redirect_uri from step 1 and the access_token and expiration are appended to the URL as a hash:

    http://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600.

    Your application parses the URL for the user's token.

  4. Include this access_token in all future requests that require a token.

Process details

Configure the redirect URI

  1. Sign into your dashboard and click the OAuth 2.0 tab.

    Dashboard

  2. Follow the steps in the Add a redirect URI tutorial.

    You can also configure a redirect URI in ArcGIS Online or ArcGIS Enterprise

Get an access token

  1. Direct your user to an authorization endpoint (either a pop-up or a new tab) to sign in with their username + password. Ensure that you include the authorization parameters.

    A sample authorization URL for ArcGIS Online might look like this.

     
    1
    https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<APP_CLIENT_ID>&response_type=token&expiration=20160&redirect_uri=<REDIRECT_URI>

    You could also construct an <a> tag:

     
    1
    <a href="https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<APP_CLIENT_ID>&response_type=token&expiration=20160&redirect_uri=<REDIRECT_URI>">Sign In With ArcGIS Online</a>

    Or open the authorization page in a popup window:

           
    1
    2
    3
    4
    5
    6
    7
    const clientId = 'APP_CLIENT_ID';
    const redirectUri = 'REDIRECT_URI';
    const 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')
    });
    

    Authorization screen

  2. The user provides their credentials.

  3. The pop-up or tab redirects the user to your application's redirect_url with an access_token and expiration appended to the URL as a hash:

    http://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600.

Authorization endpoints

ArcGIS OnlineArcGIS Enterprise

https://www.arcgis.com/sharing/rest/oauth2/authorize/

https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize

Authorization parameters

ParameterRequiredFormatDescription
client_idstringYour application's client_id.
redirect_uristringThe redirect_uri configured previously. The user is redirected to this endpoint with the authorization code.
grant_type .tokenYou must include this OAuth 2.0 grant type.
expirationnumberOptional experation after which the token will expire. Defined in minutes with a maximum of two weeks (20160 minutes).

Parse the token from the URL

The redirect_url is a callback page on your web application, typically something like http://example.com/oauth-callback.html, to which the user is sent after successfully entering their sign-in credentials.

The user's access_token and its expiration (expires_in) are appended to the URL:

 
1
http://example.com/oauth-callback.html#access_token=mpd9uhQPuHBOkQPCqkT7vhAMk8P2YNA-dEMhwYt5Gp535k92BshScRcZ8dEIuAxvFALxOn6M0RTonme9DzQ9PdwT3vr17yoOdxON5vnlpXUQcOWOu3u8EBT-xSR_zWRpna7Y2-avCVtND55HNX5Egg..&expires_in=3600

Your page needs to parse the access_token from window.location.hash and either pass it to the parent page (if a pop-up) or redirect the user to another page after it stores the token in a cookie or other persisted storage.

Parse the token from a pop-up

Here is an example of parsing the access_token if the window opens as a pop-up:

               
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!DOCTYPE html>
  <head></head>
  <body>
    <script>
      // try to match an access token in window.location.hash
      const 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]) {
        const 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, the user must sign in again. If your app requires longer sessions or if you need to refresh the user's token, use the server-enabled workflow.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.