Access secure resources

Your application may need to access secured resources that are restricted to authorized users. For example, your organization may host private data layers or feature services that are only accessible by verified users. You may also need to take advantage of premium ArcGIS location services, such as routing, that require secured user access. ArcGIS provides many ways to secure access to your organization's content and services. The ArcGIS Maps SDK for JavaScript provides full support for access to secured ArcGIS Enterprise, Online, and Location Platform resources using various methods.

Authentication methods

OAuth 2.0 — secures delegated access to server resources.
API Keys — a unique identifier used to authenticate a user, developer, or calling program to ArcGIS.
ArcGIS Tokens — Esri's proprietary token-based authentication mechanism.
Network credentials — HTTPS secured service / Integrated Windows Authentication (IWA).

OAuth 2.0

OAuth 2.0 is a standard for handling authentication decisions among various web-enabled devices and servers. ArcGIS determines user authenticity and a token is supplied to the client application. This token is then used in subsequent requests for secured resources. This is available in both ArcGIS Online and ArcGIS Enterprise and can be used with both user and application logins.

API Keys

An API key is a unique identifier used to authenticate a user, developer, or calling program to ArcGIS location services. API keys are required to access ArcGIS services, such as basemaps, geocoding, and routing. Visit your portal at ArcGIS.com to create an API key with custom privileges and referrers for your specific needs. You can use a global API key, as well as more fine-grained API keys on specific classes. Fine-grained API keys will take precedence over the global API key. If you're using both API keys and user authentication, the API keys will take precedence.

Global API key
- esriConfig.apiKey - added in version 4.18
Fine-grained API keys
- Layers
  - BuildingSceneLayer.apiKey - added in version 4.20
  - FeatureLayer.apiKey - added in version 4.20
  - IntegratedMeshLayer.apiKey - added in version 4.20
  - OGCFeatureLayer.apiKey - added in version 4.20
  - PointCloudLayer.apiKey - added in version 4.20
  - SceneLayer.apiKey - added in version 4.20
  - TileLayer.apiKey - added in version 4.20
- Other classes
  - ClosestFacilityParameters.apiKey - added in version 4.21
  - Directions.apiKey - added in version 4.19
  - Directions/DirectionsViewModel.apiKey - added in version 4.19
  - PortalItem.apiKey - added in version 4.20
  - RouteParameters.apiKey - added in version 4.19
  - Search/LocatorSearchSource.apiKey - added in version 4.19
  - ServiceAreaParameters.apiKey - added in version 4.21

ArcGIS Tokens

Token-based authentication services require that a token be included in each request for a secured resource. Both ArcGIS Online and ArcGIS Enterprise support token-based authentication that can be used with both user and application logins. Please refer to the About ArcGIS Tokens documentation for additional information.

Network Credentials

HTTP/Windows Authentication via HTTP basic, HTTP digest, or Integrated Windows Authentication (IWA) resources are protected by username and password set on the service. Prompts are then provided by a browser popup or session cookie. When you use IWA, logins are managed through Microsoft Windows Active Directory. Users do not sign in and out of the portal website; instead, when they open the website, they are signed in using the same accounts they use to log in to Windows. For more information, refer to Integrated Windows Authentication with your portal.

User authentication

Applications that support user authentication are responsible for providing a login dialog that prompts users for their credentials. The application is responsible for keeping these credentials secure by transmitting them over HTTPS.

Both OAuth 2.0 and ArcGIS Tokens make use of user authentication. In this pattern, users authorize your application to access content and services on their behalf. In this scenario your application prompts the user for their username and password and then uses their credentials to access content.

Implementing these security methods in your application can potentially be a lot of work. For user authentication, the ArcGIS Maps SDK for JavaScript provides classes to help simplify authentication and automate the process. Two primary classes are the IdentityManager and OAuthInfo classes (the latter if using the OAuth 2.0 approach).

To use the IdentityManager simply include esri/identity/IdentityManager as part of your require statement. Once the application runs and requests a resource that is secure, the IdentityManager takes over and handles prompting the user for the appropriate credentials. Once the correct credentials are supplied, a token is generated and appended to the resource. In addition to this, it also takes care of refreshing the token as needed.

When using the OAuth approach, you will also need to add the OAuthInfo class and register it with the IdentityManager. The OAuthInfo class works with registered applications.

Use dark colors for code blocksCopy
require (["esri/identity/OAuthInfo", "esri/identity/IdentityManager"], function(OAuthInfo, esriId) {
    var oAuthInfo = new OAuthInfo({
        appId: "<enter the registered app id here>"
    });
    esriId.registerOAuthInfos([oAuthInfo]);
});

For a working example of this, please refer to the Access ArcGIS Online items using OAuth 2.0 sample.

Please visit the User authentication guide topic for additional information on how this works with OAuth 2.0.

App authentication

There may be scenarios where you have secured resources but may not want your end users to have to log in to access them. In situations like this, app authentication provides users access to content on your behalf.

ArcGIS Online & ArcGIS Enterprise

App authentication uses a set of OAuth credentials to access location services with an OAuth 2.0 client_id and client_secret.

Applications that implement app authentication can access the following services:

Public content (basemaps, layers shared publicly)
Geocoding
Routing and Directions
Demographic Data (GeoEnrichment)
Esri Premium Maps and Layers which require a subscription

For more information, see App authentication.

Standalone ArcGIS server

In this scenario, your application accesses services coming from a standalone ArcGIS Server using hard-coded credentials belonging to a user that has access to these resources.

These credentials are saved within a proxy. This allows the application to access content that the user may not have permission to access. No login prompts are needed since the credentials are already supplied via the credentials specified within the proxy.

Implementation in your app

The only requirement within your application's code is to specify what URL should be proxied and then point to the correct location of the proxy file.

First, add esri/core/urlUtils to your require statement.
Next, specify the URL for the secured resource.
Lastly, specify the location to the proxy file.

Use dark colors for code blocksCopy
require (["esri/core/urlUtils"], function(urlUtils) {
    urlUtils.addProxyRule({
        urlPrefix: "my-standalone-arcgis-server.com"
        proxyUrl: "/proxy/"
    });
});

Additional resources

The following are additional resources that provide information on the various topics discussed above.

Sample - Access ArcGIS Online items using OAuth 2.0: OAuth 2.0 user authentication approach
Sample - Directions widget: API Key
Sample - Route: API Key
Core API Reference - IdentityManager
Core API Reference - OAuthInfo
ArcGIS Organization portals