Authentication and Authorization with ArcGIS Online OAuth 2.0

A step-by-step guide to implementing OAuth2 with ArcGIS Online

Bryan Grill

Published in

geographIT

5 min readFeb 22, 2019

OAuth 2

OAuth 2 is a framework that enables applications to obtain access to user accounts on another service such as Facebook, Google, Github, or ArcGIS Online/Portal. For details about the framework, checkout these articles here, here, and here.

The ArcGIS REST API

The ArcGIS REST API is a robust set of resource for programmatically working with ArcGIS Online users and content. We will be working with endpoints supporting authorization and user content.

Resources

An example of the below implementation is available on Github and CodeSandbox:

Registering with AGOL

First we need to register our app. This allows AGOL to know who is making the requests on behalf of the user and adds an additional level of security (see callback domains below.)

To add a new app, within the Content page click ‘Add Item’ -> ‘An Application’. Then select the ‘Application’ radio button and enter a title and tags.

Once the app is created, go to the app’s Settings page and scroll down to the App Registration section. First, we need to get the App ID.

The App ID at the bottom of the Settings page.

The App ID is included as a URL paramter when directing users to sign in with AGOL. Without the App ID, AGOL will not respond to the OAuth request.

Second, we need to add a Redirect URI. This is the URL(s) that AGOL can redirect a user to after they have authenticated. Click Update and add a redirect URI, localhost:3000 is fine for now.

The redirect URI is also included as a parameter in the URL when the user is directed to sign in with AGOL. If it’s not on the list, AGOL will respond with an error.

example.com is not in our list of redirect URIs.

Now that we’ve registered our app, we’re ready to implement the OAuth2 workflow.

Prompt for Sign in

In this basic example we are going to prompt the user to authenticate every time the app loads. With a little more work, you could save the token to local storage and only prompt for authentication when it’s expired.

Here we display the sign in button. FYI, all example are with React and Hooks, but would work with any framework or pure JS.

The SignIn component will open a hyperlink in this form:

https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=${clientID}&response_type=token&expiration=20160&redirect_uri=${redirect}

The authorize docs list all the possible request parameters, for our purposes we are concerned with few main parameters:

root: https://www.arcgis.com/sharing/rest/oauth2/authorize
client_id: App ID of our registered app
response_type: we are requesting the access token be included in the response
expiration: length in minutes access token will be valid for, default is 2 hours
redirect_uri: where user will be sent back to after successful authorization

Note, we are using the single step implicit grant workflow, as opposed to the two step authorization code grant. See the authentication docs for details.

The link will send the user to this page, where they can authenticate with AGOL:

Once the user successfully authenticates, they are redirected back to the address indicated in the above hyperlink. Remember, this address must be listed in the registered app settings!

Extracting the Access Token

AGOL will include an access token in the redirect URL parameters.

The access_token is returned as a URL param.

We need to extract this token so we can authenticate with AGOL when requesting data for the user. Using the qs parsing library we can extract the token from window.location.hash.

When the component loads, useEffect will fire and check for the hash. If we can parse the hash and extract the token and username, it’s saved to our component state and the Items component will be rendered. We pass Items the token and username as props so that it can make a request for the users items.

Listing Items

With the username and token, we are going to make a request to the User Content endpoint, we will use the response to list the users content.

For AGOL the endpoint URL is formatted as follows:

https://www.arcgis.com/sharing/rest/content/users/<username>

We’ll use axios to make a GET request to the endpoint. Note the placement of the token as a URL param rather than an Authorization Header.

This will return all content in the ‘Home’ folder and a list of subfolders.

{
  "username": ...,
  "currentFolder": {...},
  "items":[{...}, {...}],
  ...
}

To access the content in a subfolder, an additional request would need to be made to the subfolder url:

https://www.arcgis.com/sharing/rest/content/users/<username>/[<folderID>]

With this data, you could list the items, make a request to the item endpoint, update an item, or take any other action the user has permission to do within the ArcGIS REST API.