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

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.
The user successfully provides their username + password.
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.
Include this access_token in all future requests that require a token.

Process details

Configure the redirect URI

Sign into your dashboard and click the OAuth 2.0 tab.
Follow the steps in the Add a redirect URI tutorial.
You can also configure a redirect URI in ArcGIS Online or ArcGIS Enterprise
Tip
You cannot use a redirect URI that begins with file://; native applications should always use a redirect URI starting with https://. (a URI starting with http:// can be used in development where no SSH is available.)

Get an access token

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 an ArcGIS Online account might look like this:

Use dark colors for code blocksCopy
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:

Use dark colors for code blocksCopy
<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</a>

Or open the authorization page in a popup window:

Use dark colors for code blocksCopy
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

The user provides their credentials.
The pop-up or tab redirects the user to your application's redirect_uri with an access_token and expires_in appended to the URL as a hash:
http://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600.

Authorization endpoints

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

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

Authorization parameters

Parameter	Required	Format	Description
`client_id`	✓	`string`	Your application's `client_id`.
`redirect_uri`	✓	`string`	The `redirect_uri` configured previously. The user is redirected to this endpoint with the `access_token`. The URI must match a URI you define in the developer dashboard, otherwise, the authorization will be rejected.
`response_type` .	✓	`string`	You must include this OAuth 2.0 grant type. The type for implicit grant authorization is the string `token`.
`expiration`		`number`	Optional expiration 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_uri 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, expressed in seconds) are appended to the URL:

Use dark colors for code blocksCopy
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:

Use dark colors for code blocksCopy
<!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.

Mapping APIs and location services

Serverless web app workflow

Was this page helpful?

Was this page helpful?