Authentication

Client APIs

You can build web, mobile, and desktop based client applications that work with ArcGIS Online and ArcGIS Enterprise.

Each client application platform has its own SDK that includes an object model for working a portal through REST.

The client SDKs include the following:

Web—JavaScript
Device/Runtime—iOS, Android, Windows Phone
Desktop—Desktop SDKs

All client SDKs will expose the ability to connect to and access content in ArcGIS Online on behalf of end users. Application developers can use the REST API to augment the client SDKs with additional functionality that may not be exposed in the client API.

Types of applications and logins

As a developer using the ArcGIS platform, you can build the following two types of applications (apps):

Applications that target end users of the ArcGIS platform. These applications need to allow users to log in to the platform via the application. These types of logins are known as user logins.
Applications that target end users who are unknown to the ArcGIS platform. These applications need to log in to the platform on behalf of the application. These types of logins are known as app logins.

You can build these apps using JavaScript, iOS, and Android. The platform in this context means ArcGIS Online, which is available at arcgis.com, or an ArcGIS Enterprise portal available at a portal-specific URL along with all associated services.

The March 2013 release of ArcGIS Online introduced OAuth 2-based ArcGIS APIs for managing both user and app logins. New applications against ArcGIS Online should be developed using these OAuth 2-based APIs. Existing applications that implement these concepts using the existing APIs will continue to work and be supported, but the identity of the application making the requests will remain unknown to the platform, limiting what the application can do and participate in.

Note:

Support for OAuth 2.0 was added to ArcGIS Server and Portal for ArcGIS at version 10.3. It is not available if using Portal for ArcGIS version 10.2 and earlier.

OAuth 2-based applications

All apps that use OAuth 2 must be registered with the platform and have a platform assigned AppID. You can register your applications by logging in to the platform using your developer or organizational account and using the Add Item functionality in MyContents to add and register your app. Registering assigns the application an AppID and an optional App Secret.

User logins

Apps that support user logins use OAuth 2 to allow users to log in to the ArcGIS platform via the app. User logins using the OAuth 2-based ArcGIS APIs are based on the application guiding the user to log in to the platform via a login page hosted on the ArcGIS platform. This is common to all types of apps: browser-based web apps, server-based web apps, device and tablet-based apps, and desktop apps. Device, tablet, and desktop-based apps use client side browser controls to integrate this login experience into the app. The guiding application receives a user access token in return that it can use to access the platform on behalf of the user.

The access token needs to be sent to the platform on all requests. Apps working with the ArcGIS client SDKs can set the access token into the Identity Manager of the SDK. The Identity Manager takes care of using the token in all requests made by the object model. Apps working directly with the ArcGIS REST APIs are responsible for including the token in each REST request.

The details are slightly different for each type of application and are presented below.

User logins via JavaScript apps

Browser-based applications must register one or more redirect URIs at the time of registration. This is the URI of the app and the URI to which the user access token will be returned.

User login is performed in a single step that requires the app to direct the browser to the OAuth 2 authorization URL for the portal:

https://www.arcgis.com/sharing/rest/oauth2/authorize?
client_id=APPID&
response_type=token&
redirect_uri=<redirect_uri>

This single step flow is referred to as an OAuth 2 implicit grant. The actual redirect_uri passed in by the app in this request must be a superstring of a registered redirect_uri for the app.

If the end user successfully presents credentials (for example, username and password) to the platform (for example, arcgis.com) and if the user accepts the registered identity of the application corresponding to the APPID, the server returns an access token by redirecting the browser to the specified redirect_uri. The access token is returned as part of the URL fragment appended to the redirect_uri. The fragment is accessible to JavaScript code that is part of the page specified by the redirect_uri. For example, the server may redirect the browser to the following URL:

https://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600

The default expiry time for an access token returned by this flow is two hours. You can request an access token via this method that is valid for a longer period by providing an expiration (in minutes) parameter. The token that is returned may be valid for a shorter period based on the maximum expiry time set by the user's organization or the platform.

The application should set the obtained access token into the Identity Manager of the client API. The Identity Manager takes care of using the token as appropriate in all requests made by the client API against the portal as well as against any federated servers. If the access token expires and the Identity Manager receives a token expired failure, the Identity Manager will call back to a registered handler for a new token.

Applications that do not use the ArcGIS API for JavaScript and instead directly program with the ArcGIS REST API need to include the access token in all REST requests against the portal. The application is also responsible for obtaining server-specific access tokens for REST requests against federated servers that provide helper services such as geocoding and directions. A server-specific access token can be obtained from the portal using the generatetoken api passing in the portal access token acquired through the above flow along with the serverURL. All requests that use the token should be made over HTTPS if the portal or organization being accessed requires it or is marked as allSSL. Non HTTPS calls against such organizations will be rejected.

User logins via iOS, Android, and WPF apps

The recommended workflow for iOS, Android, and other device-based apps is a two-step workflow, referred to as an authorization code grant. This is similar to the two step workflow for working with servers.

Registration

As part of the registration process, the app registers a redirect_uri. The redirect_uri can be either a special value of urn:ietf:wg:oauth:2.0:oob or an application-specific custom URI that is handled on the device. The platform resolves the special URI to a URL hosted on the platform (that is, either on arcgis.com or on the target portal) that can be used by the installed application to obtain the authorization code at the end of the first step of user authentication and application authorization as described herein.

iOS and Android applications can also register a custom redirect_uri that the browser resolves back to an app handler running on the device. An example of such a redirect_uri is x-com.mycorp.myapp://oauth.callback. In this case, the browser directly calls the application's handler at the end of the user login.

User login is performed in two steps—the first returns an authorization code and the second returns the access token.

Authorization code

The first step of user authentication is for the app to obtain an authorization code on behalf of the user. This requires the app to open a browser window and direct the user to the following URL:

https://www.arcgis.com/sharing/rest/oauth2/authorize?
client_id=APPID&
response_type=code&
redirect_uri=<redirect_uri>

The redirect_uri passed in is either the special string (urn:ietf:wg:oauth:2.0:oob) for the ArcGIS-hosted redirect_uri or the custom URI registered by the app on the device.

If the user successfully presents credentials (for example, username and password) to the authorization server (arcgis.com or a portal) and if the user accepts the registered identity of the application corresponding to the client_id, the server returns an authorization code by redirecting the browser to the specified redirect_uri with the authorization code added as a query parameter.

If the value passed in for the redirect_uri is urn:ietf:wg:oauth:2.0:oob, the authorization server (arcgis.com or a portal) redirects the browser to https://www.arcgis.com/sharing/rest/oauth2/approval or the portal analog with the authorization code available to the application in the title of the page. For example, the server may redirect the browser to the following URL:

https://www.arcgis.com/sharing/rest/oauth2/approval?code=SplxlOBeZQQYbYS6WxSbIA

This special URL returns HTML content, the title of which will be of the following form:

<title>SUCCESS code=Sp1x1OBeZQQYbYS6WxSbIA</title>

It's up to the application hosting the web browser to extract the authorization code from the title and dismiss the browser window if the code is not to be displayed to the end user.

If the value passed in for the redirect_uri is a custom URI registered on the device and handled by the application, the application handler is responsible for receiving the redirect_uri from the browser and for extracting the authorization code from the query string component of the URL. For example, the server may redirect the browser to the following URL:

x-com.mycorp.myapp://oauth.callback?code=SplxlOBeZQQYbYS6WxSbIA

Access token

Once the authorization code has been obtained, the app needs to exchange it for an access token.

The actual request is a POST request to the token endpoint:

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

and all the parameters (in the following example) must be sent in the request body and not as part of the query component of the URI:

client_id=APPID&
client_secret=APPSECRET&
grant_type=authorization_code&
code=CODE_OBTAINED_IN_THE_PREVIOUS_STEP

The response is returned as a JSON object and includes an access_token field. The app must use this token when making subsequent requests to the server. An example JSON response is as follows:

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "expires_in": 3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"     
}

The use of the APPSECRET (oauth2 client_secret) in this request is optional for the case of user logins. Authentication of the app by the platform during the user login is based on the acceptance of the displayed identity of the app corresponding to the APPID by the user.

Access tokens are short-lived. The app can get a new access_token by using the refresh_token previously obtained. The lifetime of the refresh token that's returned by this call is controllable by the app. The default expiry time for the refresh token returned by this flow is two weeks. Using this flow, you can request a refresh token that is valid for a longer period. The refresh token that's returned may be valid for a shorter period than requested based on the maximum expiry time set by the user's organization or the platform.

You can exchange a valid refresh_token for an access_token using the same /token endpoint:

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

The required parameters in this case are the refresh_token previously obtained and a grant_type of refresh_token:

client_id=APPID&
grant_type=refresh_token&
refresh_token=refresh_token_OBTAINED_IN_THE_PREVIOUS_STEP

It yields the same response, returning a fresh access_token and refresh_token that can be subsequently used. If the refresh_token has expired, it will result in an error response and the app will be required to prompt the user to log in again.

The iOS or Android application should set the obtained user access token into the Identity Manager in the client API. The Identity Manager takes care of using the token in all requests made by the object model. If the access token expires and the Identity Manager receives a token expired failure, it will call back to a registered handler for a new token. The application should obtain a new access token using the refresh token and set it into the Identity Manager. If the refresh token has expired, the application should direct the user to log in again.

Applications that do not use the ArcGIS SDKs and directly program against the REST API need to include the access token in all REST requests against the portal. The application is also responsible for obtaining server-specific access tokens for REST requests against federated servers that provide helper services such as geocoding and directions. A server-specific access token can be obtained from the portal using the generatetoken API passing in the portal access token acquired as herein described along with the serverURL. All requests that use the token should be made over HTTPS if the portal or organization being accessed requires it or is marked as allSSL. Non HTTPS calls against such organizations will be rejected.

User logins via PHP, JSP, ASP.NET, or other server-based web apps

A server-based web app is an app where the user interacts with the app via web pages that are displayed in a browser, but significant application logic runs "server side".

Server-based web applications must register one or more redirect URIs at registration time. This is the URI of the app and the URI to which the user access token will be returned.

User login is performed in two steps—the first returns an authorization code and the second returns the access token.

Authorization code

The first step of user authentication is for the app to obtain an authorization code on behalf of the user. This requires the app to direct the user to the OAuth 2 authorization URL for the portal (shown here for arcgis.com):

https://www.arcgis.com/sharing/rest/oauth2/authorize?
client_id=APPID&
response_type=code&
redirect_uri=<redirect_uri>

If the user successfully presents credentials (for example, username and password) to the authorization server (arcgis.com) and if the user accepts the registered identity of the application, the server returns an authorization code by directing the browser to the specified redirect_uri using an HTTP redirect response to the specified redirect_uri. The authorization code is made available as a query parameter and can be accessed by the server side application running at the redirect_uri.

For example, the server may redirect the browser to the following URL:

https://app.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA

The application running at this URL then makes a second, server side request to obtain an access token in exchange for the authorization code as described in the following section.

Access token

Once the authorization code has been obtained, the app needs to exchange it for an access token.

The actual request is a POST request to the /token endpoint for the portal, shown here for arcgis.com:

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

All the parameters (in the following example) must be sent in the request body and not as part of the query component of the URI:

client_id=APPID&
client_secret=APPSECRET&
grant_type=authorization_code&
code=CODE_OBTAINED_IN_THE_PREVIOUS_STEP

The response is returned as a JSON object and includes an access_token field. The app must use this token when making subsequent requests to access resources.

An example JSON response is as follows:

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"     
}

The refresh token can be used to obtain subsequent access tokens. Access tokens are short-lived. The app can get a new access_token by using the refresh_token previously obtained. The lifetime of the refresh token that's returned by this call is controllable by the app. The default expiry time for the refresh token returned by this flow is two weeks. Using this flow, you can request a refresh token that's valid for a longer period by passing an expiration (in minutes) parameter during authorization. The refresh token that's returned may be valid for a shorter period than requested based on the maximum expiry time set by the user's organization or the platform.

You can exchange a valid refresh_token for an access_token using the same /token endpoint:

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

The required parameters in this case are the refresh_token previously obtained and a grant_type of refresh_token:

client_id=APPID&
grant_type=refresh_token&
refresh_token=REFRESH_TOKEN_OBTAINED_IN_THE_PREVIOUS_STEP

It returns a fresh access_token and refresh_token that can be subsequently used. If the refresh_token has expired, it will result in an error response and the app will be required to prompt the user to log in again.

App logins

Applications that target end users who are unknown to the ArcGIS platform use app logins to connect to the platform. In this case, the application must use both an APPID (OAuth 2 client_id) and an APPSECRET (OAuth 2 client_secret). You are responsible for building the application in a way that keeps the APPSECRET secret, including from malicious users who download and inspect the iOS or Android application or view the source of the JavaScript application using developer tools. A malicious application that has access to the application's credentials (APPID and APPSECRET) can access billable services on ArcGIS, which will be billed to the application. For most JavaScript, iOS, and Android applications, this implies that the app must have a server side application component that keeps the application credentials secure and performs work on behalf of the app.

The server side application component that has access to the application's credentials can obtain a token using a single request. The OAuth 2 grant type is set to client_credentials. The actual POST request is made to the portal's OAuth 2 token endpoint.

For arcgis.com:

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

Parameters:

client_id=APPID&
client_secret=APPSECRET&
grant_type=client_credentials

Successful authentication directly returns a JSON response containing the access token that allows the application to work with resources that are accessible to the application (that is, have been shared with the application). Use of the client_secret as previously described is mandatory.

The server side application component that makes this call can be a custom component that has its own API that wraps the ArcGIS platform API and exposes only those functions needed by the app.

The server side application component can also be a proxy that preserves the ArcGIS REST signatures while forwarding calls to the ArcGIS platform API. This is the option that needs to be implemented if the application is built using the ArcGIS client APIs that target the REST signatures.

In both cases, the calls made by the server side application component to the ArcGIS platform need to include access tokens obtained by the component in exchange for application credentials using the client_credentials grant previously described.

In both cases, the server side application component also needs to be secured so that only the application can access it.

The following are some of the possible solutions for securing the server side component to the application:

For applications that have their own authenticated users who remain unknown to the ArcGIS platform, the application can restrict access to the server side application component to authenticated application user sessions.
This assumes that app users who are developers are not malicious. If they are, and misuse the server side application component, they can be audited and tracked.
Applications whose users are anonymous even to the application can restrict access to the server side application component to human end users using CAPTCHA technology. This requires the application to incorporate CAPTCHA into its user experience.
Applications can also restrict the functionality exposed by the server side component, place IP restrictions on the server side app components, and build rate limits into the component as appropriate. Rate limits are effective in preventing misuse of the server side application component by malicious server side code.

The techniques described here apply to JavaScript, iOS, Android, and similar client devices.

Non OAuth2-based applications

Both ArcGIS Online and ArcGIS Enterprise support a generateToken REST API call that can be used with either user credentials obtained from the user who is logging in to the platform via the application or with the application's own credentials.

The call returns an access token on successful authentication that needs to be included in subsequent requests.

The generateToken call must be made over HTTPS. All subsequent requests that use the token also need to be made over HTTPS if the portal or organization being accessed requires it.

User logins

Applications implementing user logins based on the generateToken call are responsible for presenting the end user with a login dialog that elicits credentials from the user. The application is responsible for keeping the user's credentials secure and transmitting them over HTTPS.

The best practice and recommended flow for such applications is to use the appropriate client SDK object model to connect to and authenticate with ArcGIS Online rather than doing it directly via the REST API. Performing connection and authentication via the client SDKs frees you from authentication details as well as the responsibility of safely handling user credentials during the authentication process.

In the case of the JavaScript API, authentication is handled by including the IdentityManager dijit in the application. Applications can use the IdentityManager dijit to allow users to sign in to their ArcGIS Online or Portal for ArcGIS account. Once the user has signed in, any subsequent REST requests made from within that client session using the esri.Request object will automatically be part of that authenticated session.

The following are limitations of implementing user logins in this manner:

The identity of the app remains unknown to the platform.
Users cannot sign in using federated identity providers that are accessible via the platform-hosted login pages exposed via the OAuth 2 APIs.

App logins

A user representing the app needs to be provisioned with a user name (for instance, app-username) and password (for instance, app-password). Apps targeting users unknown to the platform can log in using this app-username and app-password with the generateToken API call. It's the app's responsibility to keep the app-username and app-password secure using server side code or a server side flow.

The limitations of implementing app logins in this manner are as follows:

The identity of the app is modeled via a surrogate user.
There is no clear separation of users from apps in the platform.

Working with portals

Support for OAuth 2.0 was added to Portal for ArcGIS at version 10.3. Prior to that, portal does not support OAuth 2. They support a single generateToken API call that returns an access token.

Applications should continue to use the non OAuth2-based applications authentication model for both user logins and app logins.

The most convenient way to handle user logins is to use the appropriate client SDK Identity Manager, which manages both the user login dialogs as well as credential and token management.

Once an access token for the portal has been obtained, the application can obtain an access token for any server federated with the portal by using the generateToken request with the serverURL as a parameter.

If the portal in question uses HTTP, Integrated Windows, or PKI-based security instead of token-based authentication, the response to the authentication challenge from the server needs to be handled using the native communication stack of the client platform.

Working with servers

Support for OAuth 2.0 was added to ArcGIS Server at version 10.3. Prior to that, ArcGIS servers that are not affiliated with ArcGIS Online or Portal for ArcGIS do not support OAuth 2. They support a single generateToken API call that returns a token.

Applications should continue to use the non OAuth2-based applications authentication model for both user logins and app logins.

The most convenient way to handle user logins is to use the appropriate client SDK Identity Manager, which manages both the user login dialogs as well as credential and token management.

If the server in question uses HTTP, Integrated Windows, or PKI-based security instead of token-based authentication, the response to the authentication challenge from the server needs to be handled using the native communication stack of the client platform.