Server-based Named User Login

The server-side workflow offers the best combination of flexibility and security. Tokens obtained in this way last for 30 minutes but can be refreshed for a period defined by the user's organization (forever by default) and the client_secret acts as additional verification of the application.

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.
2. If the user successfully presents their username and password they will be redirected back to your application with an authorization code https://app.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA.
3. 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:

• Your application's client_id and client_secret
• A grant_type of authorization_code
• The redirect_uri from step 1
• The authorization code from the previous step

4. Once you have the access token, include it in requests to ArcGIS Online which require a token.

Configure a redirect URI

1. Go to the "Authentication" tab for your application on ArcGIS for Developers.
   
   
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.
   
   

You can also register your applications on ArcGIS Online in your My Contents screen.

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.

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

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

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 receive the logged in user's 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

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

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,
    "username": "username"
}

OAuth 2.0 helpers and libraries

Because OAuth 2.0 is a widely accepted web standard you can find many libraries that implement OAuth 2.0 on top of almost any common server framework. Below is a list of OAuth 2.0 implementations in common frameworks.

Node JS

• Bell for Hapi
• Passport for Express

Ruby

• Omniauth for Sinatra and Ruby On Rails or any Rack based server. There is also an Omniauth Strategy for ArcGIS