Server-enabled workflow

In this server-enabled OAuth 2.0 workflow, ArcGIS Online and ArcGIS Enterprise users sign in with their user name and password. Their credentials authorize your app to access any content and services authorized through the platform to that user, and the user is billed for any content and services they use. This process uses the OAuth 2.0 authorization_code grant type.

Overview

This is possibly the most flexible and secure method for using ArcGIS identity, where the access_token and client_secret provide a two step authentication process. The initial access_token expires in 30 minutes, but can be refreshed for a period defined by the user's organization (forever by default).

Server Side App Login

  1. Direct your user to the authorization endpoint in a browser with the client_id, response_type=code, a redirect_uri, and an optional expiration.
  2. When the user successfully presents their username + password, they are redirected to your application with an appended authorization code, for example: https://app.example.com/cb?code=Splx123456.
  3. Your application exchanges the authorization code for an access_token from the token endpoint. This requires the following:
    • Your application's client_id and client_secret
    • A grant_type = authorization_code
    • The redirect_uri from step 1
    • The authorization code provided in the previous step
  4. Once you receive the access_token, it must be included in all subsequent 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. This is where the authorization code is sent after the user has provided credentials.

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

Get an authorization code

Direct your user to an authorization endpoint in a browser to sign in with their username + password, using the correct authorization parameters.

Authorization endpoints

ArcGIS OnlineOn-premise ArcGIS Portal

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 in step 2. The user will be redirected to this endpoint with the authorization code.
grant_typecodeYou must include this OAuth 2.0 grant type.
expirationnumberRequested duration (in seconds) of the refresh_token. -1 = a refresh_token that will last forever. ArcGIS Online organizations can override this with a shorter duration.

Authorization example

 
1
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&expiration=<N_SECONDS>&redirect_uri=<REDIRECT_URI>

Exchange the code for a token

Once the user authorizes your application, the browser will redirect them to the configured redirect URL with the appended authorization code, in this example:

 
1
my-arcgis-app://auth?code=KYv4VCRymwC3UeD4-U9jkwGPHIoGqZ9SpDTBHwcE_pUmZquQRusn99YiXvUjlAmUJi42Wrh1hnlcy9RtZdfC_dnLrqu3PLWETQsyy-YVYuhLHSWKYiRKozx0eng5r0t70W_S-rlljdc0j8f-V5FI4vOkpKp0hMVgDG8pGsBZG8DYXnWdpYvDQCjIacIzFqz-vTt8FlXJZESmUC2wz2p_hQ..

You can now exchange this code with the token endpoint for a user's access_token.

Token endpoints

ArcGIS OnlineOn-premise ArcGIS Portal

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

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

Request parameters

All request parameters should be form encoded.

ParameterRequiredFormatDescription
client_idstringYour application's client_id.
codestringThe authorization code.
redirect_uristringThe redirect_uri used with this authorization code in the previous step.
grant_typeauthorization_codeYou must include this OAuth 2.0 grant type.

Response object

The response object will contain an access_token, expires_in (number of seconds until the access_token expires), and the universally unique username.

      
1
2
3
4
5
6
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800,
    "refresh_token": "gbY49hl4mGXJrw3kEf7P_nIkIK8X3zyiZJxvo8uawXGkSx3BuP5DlefcQSiNQKbZFu9RQb1GV2WpxH1GCvz0wbp0fv3RYkCran-UD6cS8nzIaUbA9PqzYrgPTsMSmhDbH-1eJPRaM_MspSVVCFbpBoaf-xHYoamU9rW76NSc2uJIeqClskbjzy-1NUiTXwM6blTGtdn4tw7ew8451ZHs8FRijLR0bNPGf_2XOm1aeJLi_MsXP7WGOy-5dDvDS2Y_GHEeUa3eN030_KghXbz98k6QcJXd0q83mPVkoIrcBtEapsImMgpc-b5mUQoNgYaV",
    "username": 'sampleuser'
}

Refresh the token

The authorization code grant type recommends short-lived access tokens and long-lived refresh tokens.

Error example

When a token expires, you receive the following response. This typically means that your token has expired or is invalid. If you have a refresh token from the previous step, you can get a new access_token and try your request again.

       
1
2
3
4
5
6
7
{
    "error": {
        "code": 498,
        "message": "Invalid Token",
        "details": []
    }
}

Refresh request parameters

All request parameters should be form encoded.

ParameterRequiredFormatDescription
client_idstringYour application's client_id.
refresh_tokenstringYour user's refresh token.
grant_typerefresh_tokenYou must include this OAuth 2.0 grant type.

Response object

The response will contain an access_token for the user; it will not contain a new refresh token. If your user's refresh token expires, they must sign in again.

     
1
2
3
4
5
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800,
    "username": "username"
}

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