To build applications with the JavaScript Maps SDK that access secure ArcGIS resources, you must implement API key authentication
Authentication allows you to:
- Build applications that provide secure access to data and resources.
- Access secure ArcGIS Location Platform, ArcGIS Online, and ArcGIS Enterprise services.
- Access secure ArcGIS Location Services
ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. . - Access secure content and data in your portal.
- Access subscriber content in Living Atlas.
- Track the usage of your ArcGIS items.
- Monitor service usage by your application or by members of your organization.
The type of authentication you use depends on the product you have and the type of application you are building.
| Typical use case | Authentication type |
|---|---|
| Public applications that do not require users to sign in | API key authentication or App authentication |
| Private applications for members of an organization that require sign in | User authentication |
| Personal applications for your use only | API key authentication, User authentication, App authentication |
| Typical use case | Authentication type |
|---|---|
| Public applications that do not require users to sign in | API key authentication or App authentication |
| Private applications for members of an organization that require sign in | User authentication |
| Personal applications for your use only | API key authentication, User authentication, App authentication |
| Typical use case | Authentication type |
|---|---|
| Public applications that do not require users to sign in | API key authentication or App authentication |
| Personal applications for your use only | API key authentication or App authentication |
API key authentication
If you have ArcGIS Location Platform, ArcGIS Online, or ArcGIS Enterprise >11.4, you can use API key authentication to create a long-lived access token that authorizes secure service requests without requiring users to sign in. This method requires creating an API key credential
API keys can be configured to access specific ArcGIS services and functionality, including location services, hosted data layers
API key authentication is well-suited for building public-facing applications
Using API keys with the SDK
With the JavaScript Maps SDK, there are two ways to use API keys in your application:
- Setting a global API key: This uses the
esriConfigglobal variable orconfigmodule for all secure services and resources. - Setting an API key for a class or component: This uses the
apiKeyproperty available on specific classes and components that require an access token to access secure resources. This pattern is useful when you want to set different API keys for different services or resources in your application.
The order in which global and class-based API keys are resolved:
- API keys set for specific classes (e.g.,
FeatureLayer.apiKey). - Global API keys configured in
config.apiKeys.scopes. The first match found will be used first, so the order in which the scopes are defined matters. - Global API key set for basemap styles in
config.apiKeys.basemapStyles. - Global API key configured on
config.apiKey.
Steps
- Create an API key credential item in your portal.
- Assign privileges to define accessible services and data.
- Set the access token globally with
esriConfig.apiKeyor on a specific class.
Examples
Set an API key for global use
This example shows how to set an API key access token in your application at a global level. Implement this pattern when you want to use the same token for all secure services and resources in your application.
The access token associated with the API key credential needs to have the necessary privileges configured for all services and data that are used in the application. The esriConfig global variable must be defined first before adding other libraries.
Use the apiKey property to set an access token for all services and resources in your application.
<script>var esriConfig = { apiKey: "YOUR_ACCESS_TOKEN",};</script>Use the apiKeys property to set multiple global access tokens with different scopes and URLs. The token will only be sent in requests to the specified URLs.
<script>var esriConfig = { apiKeys: { scopes: [ { token: "YOUR_ACCESS_TOKEN", // An array of URLs that the API key applies to. // Specify the URLs of the services that will be accessed with this token. // The access token will only be sent in requests to these URLs. urls: ["https://myHostName.esri.com/portal/", "https://myHostName.esri.com/server/"], }, ], },};</script>Use the apiKey property to set an access token for all services and resources in your application.
<script>var esriConfig = { apiKey: "YOUR_ACCESS_TOKEN",};</script>Set an API key for a specific class
This example shows how to set an access token for the BasemapStyle class. Implement this pattern when you want to set an access token for a specific class that requires it. The access token associated with the API key credential needs to have the necessary privileges configured for the specific service or resource that the class will access.
const [Basemap, BasemapStyle] = await $arcgis.import([ "@arcgis/core/Basemap.js", "@arcgis/core/support/BasemapStyle.js",]);const basemap = new Basemap({ style: new BasemapStyle({ apiKey: "YOUR_ACCESS_TOKEN", id: "arcgis/human-geography", language: "es", }),});Set API keys for global use and for a specific class
API key access tokens can be set globally and for specific classes in the same application. The following example shows how one access token can be set on the FeatureLayer class to access a private feature layer item, while another token can be set globally to access the Basemap Styles service.
<head> <script> // API key set globally used for requests to the Basemap Styles service. var esriConfig = { apiKey: "YOUR_ACCESS_TOKEN", }; </script> <script type="module" src="https://js.arcgis.com/5.0/"></script></head><body> <arcgis-map basemap="arcgis/human-geography"></arcgis-map> <script type="module"> const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js"); // API key set for a specific class to access a secure feature layer item. // This API key will take precedence over the global API key for requests made by the FeatureLayer. const featureLayer = new FeatureLayer({ portalItem: { id: "LAYER_ITEM_ID", // The access token must have privileges to access this item. apiKey: "YOUR_ACCESS_TOKEN", }, }); </script></body>User authentication
If you have ArcGIS Online or ArcGIS Enterprise, you can also build applications that can authenticate users via their ArcGIS account. This process involves creating an OAuth 2.0 credential, which is used to generate a unique access token tied to the user’s privileges
User authentication is well-suited for building private applications
Steps
- Create an OAuth 2.0 credential in your portal to obtain a client ID, client secret, and redirect URL.
- Use these credentials in your application to initiate the OAuth 2.0 flow and request an access token with the
IdentityManager. - Use the access token to access services on behalf of the signed-in user.
Example
Implement user authentication
This example shows how to use the IdentityManager to handle user authentication using the OAuth 2.0 flow. The IdentityManager class provides methods to register OAuth 2.0 credentials, trigger the sign-in process, and manage user sessions. When a user successfully signs in, the IdentityManager generates an access token that can be used to authenticate requests to secure ArcGIS services and resources on behalf of the user.
const [OAuthInfo, identityManager] = await $arcgis.import([ "@arcgis/core/identity/OAuthInfo.js", "@arcgis/core/identity/IdentityManager.js",]);var oAuthInfo = new OAuthInfo({ appId: "YOUR-CLIENT-ID",});identityManager.registerOAuthInfos([oAuthInfo]);App authentication
If you have ArcGIS Location Platform, ArcGIS Online, or ArcGIS Enterprise, you can build applications using app authentication to generates a short-lived access token based on a set of OAuth 2.0 credentials. The access tokens are associated with your ArcGIS account, and can be used to authenticate requests to access secure ArcGIS services and items.
App authentication can be used to create public applications with a server-side component that access ArcGIS services and secure content items. It can also be used to create personal applications and scripts that perform spatial analysis and portal management operations.
To implement app authentication, OAuth 2.0 credentials (Client ID and Client Secret) are used to generate access tokens via the token endpoint of your portal service. These access tokens are then registered with the IdentityManager to authenticate requests to secure ArcGIS services and resources. App authentication is a secure way to allow applications to access protected resources without requiring user sign-in, as the access tokens can be scoped with specific privileges and have a limited lifespan.
Steps
- Create an OAuth 2.0 credential in your portal to obtain a client ID, client secret, and redirect URL.
- Include the
client_idandclient_secretfrom OAuth credentialsOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a in your server script.client_id,client_secret, and redirect URIs. They are a type of developer credential. - Create an endpoint for clients to request access tokens.
- When a client requests a token, submit a request to the token endpoint
An token endpoint is an endpoint of a portal service that can be queried to request an access token. It is used to implement user authentication OAuth2.0 flows. of your portal serviceA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise. . - Deliver the resulting access token to the JavaScript Maps SDK client.
- The JavaScript Maps SDK client uses the access token to access secure resources
A secure resource is any item or service in an ArcGIS that requires an ArcGIS account and authentication to access. Examples include ArcGIS Location Services, and items and data services in an ArcGIS portal. by registering the token with the IdentityManager.
Example
Implement app authentication
This example shows how to utilize app authentication in your application. In this example, a server-side script is used to generate an access token using the OAuth 2.0 credentials and the token endpoint of the portal service. The client-side application then requests an access token from the server, receives the token, and registers it with the IdentityManager to authenticate requests to secure resources.
const identityManager = await $arcgis.import("@arcgis/core/identity/IdentityManager.js");
// URL of the server endpoint that generates app authentication access tokens using OAuth credentials.const appTokenURL = "http://localhost:3080/auth";const tokenData = { nonce: 1234 };
// Send a request to the token server to exchange the app credentials for an access token.const tokenRequest = await fetch(appTokenURL, { method: "POST", body: JSON.stringify(tokenData), headers: { "Content-Type": "application/json", },});
// Get the token response from the server and register it with the IdentityManager.const tokenResponse = await tokenRequest.json();
// This method should be called again before the token expires.identityManager.registerToken({ expires: tokenResponse.expires_in, server: tokenResponse.appTokenBaseURL, ssl: true, token: tokenResponse.access_token, userId: tokenResponse.arcgisUserId,});