Serverless native and mobile app workflow

This OAuth 2.0 workflow is ideal for applications built using ArcGIS Runtime APIs or using a custom URI handler, and for all serverless native and mobile applications using an OAuth 2.0 authorization_code grant type. Your users can be registered on ArcGIS Online or ArcGIS Enterprise.

There are 2 available methods for developers implementing this workflow in a native application:

  1. Recommended: Use ArcGIS Runtime AuthenticationManager, OAuthConfiguration, and CredentialCache objects to obtain and manage credentials. This requires minimal knowledge of OAuth 2.0 and these components handle the bulk of the process.

    If you choose this method, use the sample for AuthenticationManager from your ArcGIS Runtime API:

  2. Register a custom URI handler for your application, such as myapp://auth, to which your users are redirected upon completion of the OAuth 2.0 validation process.

This workflow demonstrates how to implement a custom URI handler.

Overview

Native Application User Authentication

  1. Direct your users to the authorization endpoint in a browser on the device with your client_id, response_type=code, a redirect_uri, and an optional expiration indicating the length of the authorization code's validity. The redirect URI must have been previously registered with the app or be a known URI. The user is presented a login form.

     
    1
    https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id={your-app-client-id}&redirect_uri={your-app-redirect-uri}&response_type=code
  2. When the user successfully provides their username + password, they are redirected to the configured redirect URI (either your application with a custom redirect URI such as myapp://oauth.callback, or a known, hosted redirect page urn:ietf:wg:oauth:2.0:oob). The redirect URI string is appended with an authorization code. Use this code to request an access token.

     
    1
    {your-app-redirect-uri}?code={authorization_code}
  3. Your application exchanges the authorization code for an access token from the token endpoint. This requires the following:

    • The same application client_id from step 1
    • A response_type = authorization_code
    • The same redirect_uri from step 1
    • The authorization code from the response
    • Notice that client_secret is not used in this flow
     
    1
    https://www.arcgis.com/sharing/rest/oauth2/token?client_id={your-app-client-id}&redirect_uri={your-app-redirect-uri}&response_type=authorization_code&code={code}
  4. The token endpoint replies with a JSON object containing either the authorization attributes or an error. Once you receive the access token, include it in all subsequent requests that require a token.

Responses
Valid responseError response
      
1
2
3
4
5
6
  {
    "access_token":"{token}",
    "expires_in":1800,
    "username":"{user-name}",
    "refresh_token":"{refresh-token}"
  }
         
1
2
3
4
5
6
7
8
9
  {
    "error":{
      "code":400,
      "error":"invalid_request",
      "error_description":"code expired",
      "message":"code expired",
      "details":[]
    }
  }

Error codes are generally standard HTTP status codes ranging 400-499, and the message indicates the failure source / details. The most common failure cause is an expired or invalid authorization code. In this event, generate a new authorization code and attempt the request again.

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.

  3. Ensure that your redirect URI matches the handler you configured for your application in step 2. For example my-arcgis-app://auth. This is where the authorization code is sent once the user has provided credentials. Your application will need to read this URI and parse the authorization code from it.

With a custom redirect URI

In order to redirect the user back to your application after they authenticate, you will need to set up a custom protocol handler. This varies from platform to platform.

When the user authorizes your application, the browser is redirected to this URI (for example, my-arcgis-app://auth) with their authorization code. Using this example, you must ensure that your platform understands that my-arcgis-app is your application. There are resources available to assist you with the various platforms.

Get an authorization code

Open an authorization browser window for the user, using the correct endpoint and parameters.

A browser provides added security measure:

  • It displays the identity of the arcgis.com authorization page in the URL status bar.
  • Users can verify the browser's SSL status to confirm that arcgis.com is a valid host for the authorization page.
  • It confirms that username + password is given only to arcgis.com and not to an unknown entity, an unverified application, or to a third party.

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 above. The user is 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=YOUR_APPLICATIONS_CLIENT_ID&response_type=code&expiration=SECONDS&redirect_uri=REDIRECT_URI_CONFIGURED_ABOVE

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 OnlineArcGIS Enterprise

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.

Token error messages

When a token expires, you will 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

In the response you will receive an access_token for the user; you will not receive a new refresh token. If their refresh token expires, the user must instead go through the full sign in process.

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

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