Client credentials flow

Client credentials flow
The client credentials flow

ArcGIS uses a client credentials flow to implement app authentication. In this flow, a secure server uses a client_id and client_secret from a set of OAuth credentials to request an access token, then delivers the token to a client application.

The diagram above explains this flow using the following steps:

  1. OAuth credentials are registered in the portal to obtain a client_id and client_secret.

  2. The confidential client_id and client_secret are stored in a server-side component.

  3. The server gets an access token by submitting a request to your organization's portal service

  4. The server delivers the access token to the client application upon request.

  5. The client application uses the access token to authorize requests to secure resources.

This flow adheres to the client_credentials grant type defined in the OAuth 2.0 specification. The main benefit of this flow is that the server handles requesting an access token, ensuring that the confidential client_id and client_secret values are never exposed to the client application. To read more about the client credentials protocol, go to OAuth 2.0 RFC 6749 section 4.4.

Manual implementation

The remainder of this page shows how to manually implement app authentication by making direct requests to your organization's portal service. The sample is written in JavaScript, but can be implemented in any language by making HTTP requests.

Create OAuth credentials

A set of OAuth credentials are required for app authentication. These credentials are created as an item in your organization's portal.

The steps to create OAuth credentials with an ArcGIS Location Platform account are:

  1. Sign in to your ArcGIS portal.

  2. Click Content > My content > New item and select Developer credentials.

  3. In the Credential types menu, select OAuth credentials.

  4. Add a redirect URL and click Next. This URL is required during creation, but will not be used in app authentication.

  5. Set the credential privileges to determine the operations your access tokens will be authorized to perform.

  6. Set the credential item access privileges to determine the items your access tokens will be authorized to access.

  7. Review your selections and, when you are ready, click Generate credentials.

Configure authentication variables

  1. Copy the client_id and client_secret parameters from your OAuth credentials and paste them into a new application.

    server.js
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    const clientId = 'YOUR_CLIENT_ID';
    const clientSecret = 'YOUR_CLIENT_SECRET';
    

Request the token endpoint

App authentication is implemented by submitting a request to the token endpoint of your ArcGIS organization.

  1. Find the URL of the token endpoint for your ArcGIS organization. For ArcGIS Online and Location Platform users, the token endpoint is https://www.arcgis.com/sharing/rest/oauth2/token.

    server.js
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    const token_endpoint = ' https://www.arcgis.com/sharing/rest/oauth2/token';
    
    
  2. Submit an HTTP POST request to the endpoint. Include your client_id, client_secret, and a grant_type parameter set to 'client_credentials'.

    server.js
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    const token_endpoint = ' https://www.arcgis.com/sharing/rest/oauth2/token';
    
    const response = await fetch(token_endpoint, {
        method: 'POST',
        headers: {
            "Content-type":"application/x-www-form-urlencoded"
        },
        body: new URLSearchParams({
            'grant_type':'client_credentials',
            'client_id':clientId,
            'client_secret':clientSecret
        })
    })
    
    

Use the token

After obtaining the access token, you can use it to authorize requests directly from the server or alternatively deliver it to a client application. The method of implementation depends on the framework and libraries you are using.

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