Authenticate with the REST API

This workflow is ideal for serverless native and mobile applications using the OAuth 2.0 authorization code grant. Your users are registered on ArcGIS Online.

Native Application User Authentication

  1. Direct your users to the authorization endpoint https://www.arcgis.com/sharing/rest/oauth2/authorize in a browser with your client_id, response_type=code, a redirect_uri and optional expiration indicating how long the authorization code should be valid for. Note the redirect_uri must be one that was previously registered with the app or one of the known uris such as urn:ietf:wg:oauth:2.0:oob. The user is presented a login form.
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id={your-app-client-id}&redirect_uri={your-app-redirect-uri}&response_type=code
  1. If the user successfully responds with their user name and password they will then be redirected back to your application (assuming you use a custom redirect URI like myapp://oauth.callback) or to the hosted redirect page on ArcGIS Online (using the urn:ietf:wg:oauth:2.0:oob redirect URI). The location you are redirected to will have an authorization code in the query string. Use this code to request an access token.
{your-app-redirect-uri}?code={authorization_code}
  1. Your application exchanges the authorization code for an access token from the token endpoint https://www.arcgis.com/sharing/rest/oauth2/token. This requires the following:
  • The same application client_id from step 1
  • A response_type of authorization_code
  • The same redirect_uri from step 1
  • The authorization code from the previous response
  • (Note that the client_secret is not used in this flow)
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}
  1. The token endpoint replies with a JSON object containing attributes of the authorization or an error. Once you have the access token, include it in requests to ArcGIS Online that require a token.

Valid response:

{
  "access_token":"{token}",
  "expires_in":1800,
  "username":"{user-name}",
  "refresh_token":"{refresh-token}"
}

Error response:

{
  "error":{
    "code":400,
    "error":"invalid_request",
    "error_description":"code expired",
    "message":"code expired",
    "details":[]
  }
}

Error codes generally range 400-499 as standard HTTP status codes and the message indicates details of the failure. Common failures are due to an expired or invalid authorization code. In this case generate a new authorization code and try your request again.

Choosing the best approach

When implementing named user login in a native application the following approach is recommended:

  1. Use the AuthenticationManager, OAuthConfiguration and CredentialCache objects in the ArcGIS Runtime SDKs to obtain and manage credentials. This involves minimal knowledge of OAuth and these components take care of the bulk of the process.
  2. Register a custom URI handler for your application, like myapp://auth, which is redirected to upon completion of the OAuth process.

With an ArcGIS Runtime SDK

Add the Hosted Redirect Page

  1. Go to the "Authentication" tab for your application on ArcGIS for Developers.

    Application Overview
  2. Add a new redirect URI to the list at the bottom of the page. These redirect URIs represent the valid places that a user can be redirected to after a successful sign in.

    Application Overview

Note: You can also configure a redirect URI on ArcGIS Online or in your own on-premise portal

3. Add urn:ietf:wg:oauth:2.0:oob to the redirect URIs. This is a special value used internally by the ArcGIS Runtime SDKs.

Use AuthenticationManager

This is the easiest solution as the ArcGIS Runtime SDKs handle OAuth, user credentials, and token management for you.

With a custom redirect URI

In order to redirect the user back to your application after they authorize your application you need to setup a custom protocol handler. This will vary from platform to platform.

When the user authorized your application the browser will be redirected to this URI (my-arcgis-app://auth for example) with the authorization code. In this example you make sure your platform understands that my-arcgis-app is your application. There are many resources available for this on different platforms.

Configure a redirect URI

  1. Go to the "Authentication" tab for your application on ArcGIS for Developers.

    Application Overview
  2. Add a new redirect URI to the list at the bottom of the page. These redirect URIs represent the valid places that a user can be redirected to after a successful sign in.

    Application Overview

Note: You can also configure a redirect URI on ArcGIS Online or in your own on-premise portal

  1. Add a redirect URI that matches the handler you configured for your application in step 1. For example my-arcgis-app://auth. This is where the authorization code will be sent when the user has authorized it. Your application will need to handle this URI and parse the authorization code from it.

Send the user to the authorization screen

Now you need to open the authorization screen in a browser for the user to sign into. A browser is used for several reasons.

  1. The browser will verify the identity of the authorization page. A user can check the SSL status on the browser to confirm that the arcgis.com that is hosting the authorization page is the real arcgis.com.
  2. The user can see arcgis.com in the URL bar. This way they know they are giving their username and password to only arcgis.com and not to your application or a third party.

Authorization endpoint

ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/authorize/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize

Authorization parameters

Parameter Required Description
client_id The client_id of your application.
redirect_uri The redirect_uri that you configured above. The user will be redirected to this endpoint with the authorization code.
response_type code The OAuth 2.0 grant type of code is required.
expiration Requested duration (in seconds) the refresh_token you will receive. You can specify -1 for a refresh_token that will last forever. ArcGIS Online organizations can override this with a shorter duration.

Authorization example

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 authorization code for an access token

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

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

You can now exchange the code for a user's access_token.

Token endpoint

ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/token/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token

A token can be generated using only the POST method and only over HTTPS.

Request parameters

Parameter Required Description
client_id The client_id of your application.
code The authorization code.
redirect_uri The redirect_uri that was used with this authorization code in the previous step.
grant_type authorization_code The OAuth 2.0 grant type of authorization_code is required.

All request parameters should be form encoded.

Response object

In the response you will receive an access_token, for the user as well as the number of seconds that access token will expire in. The expires_in key in the response is always the number of seconds the access_token will expire in not the refresh token. You will also recive the logged in users username which is guaranteed to be unique across the entire platform.

{
    "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": 'bobgis'
}

Refreshing the token

The authorization code grant type recommends short lived access tokens and long lived refresh tokens. When a token expires you will receive the following response:

{
    "error": {
        "code": 498,
        "message": "Invalid Token",
        "details": []
    }
}

Note: The error.code property may also be 499.

When this occurs it usually 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.

Token endpoint

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

A token can be generated using only the POST method and only over HTTPS.

Request parameters

Parameter Required Description
client_id The client_id of your application.
refresh_token The refresh token for this user.
grant_type refresh_token The OAuth 2.0 grant type of refresh_token is required.

All request parameters should be form encoded.

Response object

In the response you will receive an access_token for the user. You do not receive a new refresh token. If your refresh token expires you must perform the sign in process again.

{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800
}