Serverless native and mobile app workflow

This OAuth2.0 authentication method is ideal for applications built using ArcGIS Maps SDKs for Native Apps 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 the ArcGIS Maps SDK for Native Apps 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 Native SDK:

   • ArcGIS Maps SDK for Java
   • ArcGIS Maps SDK for .NET
   • ArcGIS Maps SDK for Qt
   • ArcGIS Maps SDK for Kotlin
   • ArcGIS Maps SDK for Swift

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.

Overview

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.

   Use dark colors for code blocksCopy

   1
   https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&redirect_uri=<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.

   Use dark colors for code blocksCopy

   1
   <REDIRECT_URI>?code=<AUTH_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 = AUTH_CODE
   • The same redirect_uri from step 1
   • The authorization code from the response
   • Notice that client_secret is not used in this flow
   Use dark colors for code blocksCopy

   1
   https://www.arcgis.com/sharing/rest/oauth2/token?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&grant_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

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.

   

2. Follow the steps in the Add a redirect URI tutorial.

   More info

   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.

Authorization endpoints

Authorization parameters

Authorization example

1
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<APP_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

Request parameters

All request parameters should be form encoded.

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.

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
}