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.
- Direct your users to the authorization endpoint
https://www.arcgis.com/sharing/rest/oauth2/authorize
in a browser with yourclient_id
,response_type=code
, aredirect_uri
and optionalexpiration
. - 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
andclient_secret
- A
grant_type
ofauthorization_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
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
Ruby
- Omniauth for Sinatra and Ruby On Rails or any Rack based server. There is also an Omniauth Strategy for ArcGIS