Server-based Named User Login | ArcGIS for Developers

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.

Server Side App Login

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.
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.
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

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

Configure a redirect URI

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

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

3. Add a redirect URI that matches the handler you configured for your application in step 1. For example `https://my-arcgis-app.com/oauth-callback`. This is where the authorization code will be sent when the user has authorized it.

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

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` of 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 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

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,
    "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