ArcGIS REST JS includes a comprehensive set of classes for managing authentication. Each helper corresponds with one of the main types of authentication discussed in the Security and authentication guide.
The classes for each type of authentication are:
- API key authentication:
Api
Key Manager - User authentication:
ArcGIS
Identity Manager - App authentication:
Application
Credentials Manager
These managers handle much of the complexity of dealing with authentication including:
- Performing OAuth authentication workflows.
- Automatically refreshing credentials when they expire.
- Obtaining credentials for a specific instance of ArcGIS Server.
- Passing credentials between clients and servers.
How authentication managers work
Each authentication manager has several static methods to help construct the manager object. These static methods are the preferred way to create the manager objects and implement specific workflows and patterns.
The general workflow is:
- Create API key credentials or OAuth 2.0 credentials.
- Create the manager using the correct helper method for your authentication workflow.
- Access services with the
authentication
parameter.
API key manager
An instance of Api
can be created with the Api
method.
import { ApiKeyManager } from "@esri/arcgis-rest-request";
const accessToken = ApiKeyManager.fromKey("YOUR_ACCESS_TOKEN");
Example
Use an API key to authenticate a request
To quickly set up authentication in your application, use an API key. When using an API key, make sure that it is properly scoped to the services you are accessing.
Because of their simplicity, API keys can be passed directly to the authentication
parameter.
- Reference the library.
- Get an access token from API key credentials.
- Set the access token.
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { geocode } from "@esri/arcgis-rest-geocoding";
geocode({
address: "1600 Pennsylvania Ave",
postal: 20500,
countryCode: "USA",
authentication: ApiKeyManager.fromKey("YOUR_ACCESS_TOKEN") // API key scoped to access the geocoding service
});
ArcGIS identity manager
An instance of ArcGIS
can be created with several different methods including helper methods for OAuth 2.0 user authentication workflows.
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
ArcGISIdentityManager.beginOAuth2({
clientId: "YOUR_CLIENT_ID",
redirectUri: "YOUR_REDIRECT_URI"
}).then((manager) => {
console.log(manager);
});
Example
Implement user authentication with OAuth 2.0
When your app requires access to secure resources owned by users or if you are distributing your app through ArcGIS Marketplace, you should implement user authentication with OAuth 2.0.
The ArcGIS REST JS request package includes the ArcGIS
to authenticate users with their ArcGIS Online or ArcGIS Enterprise accounts. The ArcGIS
also includes helper methods to simplify the authentication process and manage credentials once they are obtained.
- Reference the library.
- Go to your portal.
- Create a set of OAuth 2.0 credentials.
- Configure the redirect URL for your application.
- Get the client ID and redirect URI for your application.
- Set the client ID.
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
// register your own app to create a unique clientId
const clientId = "abc123"
// send the user to the authorization page
ArcGISIdentityManager.beginOAuth2({
clientId,
redirectUri: 'https://yourapp.com/authenticate.html'
})
.then(authenticationManager => {
geocode({
address: "1600 Pennsylvania Ave",
postal: 20500,
countryCode: "USA",
authentication: authenticationManager
})
})
After the user authorizes your application they will be taken to the page specified by the redirect
which should complete the OAuth 2.0 process.
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
const clientId = "abc123"
/**
* after the user authorizes the application they will be redirected to
* the page defined in redirectUri which will need to complete the
* authentication process.
**/
ArcGISIdentityManager.completeOAuth2({
clientId,
redirectUri: 'https://yourapp.com/authenticate.html'
});
Application credential manager
This manager is used to implement app authentication. An instance of Application
can be created with the Application
method:
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";
const appManager = ApplicationCredentialsManager.fromCredentials({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
});
appManager.refreshToken().then((manager) => {
console.log(manager);
});
Example
- Reference the library.
- Go to your portal.
- Create a set of OAuth 2.0 credentials.
- Get the client ID and client secret for your application.
- Create an instance of
Application
with the client ID and client secret.Credentials Manager
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";
import { geocode } from "@esri/arcgis-rest-geocoding";
const appManager = ApplicationCredentialsManager.fromCredentials({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
});
appManager.refreshToken().then((manager) => {
geocode({
address: "1600 Pennsylvania Ave",
postal: 20500,
countryCode: "USA",
authentication: manager
})
});
Access services with authentication
The authentication
option on most methods accepts one of the three manager classes. Use the authentication
to make a request to a service.
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { solveRoute } from "@esri/arcgis-request-routing";
solveRoute({
stops: [
[-117.195677, 34.056383],
[-117.918976, 33.812092],
],
authentication: ApiKeyManager.fromKey("YOUR_ACCESS_TOKEN")
})
.then(response)
If you have an access token from another source, you can pass it directly to the authentication
option; however this is not recommended. If you directly pass an access token from user authentication or app authentication, ArcGIS REST JS will skip most of its error handling (which is a key feature), so this should be used with caution.
import { solveRoute } from "@esri/arcgis-request-routing";
solveRoute({
stops: [
[-117.195677, 34.056383],
[-117.918976, 33.812092],
],
authentication: "YOUR_ACCESS_TOKEN"
})
.then(response)
Refresh a credential
Both ArcGIS
and Application
generate short lived credentials by default. Both of these classes have a can
property that indicates if the credentials can be refreshed after they expire. Credentials can be refreshed by calling the refresh
method.
// assuming `manager` is an instance of `ArcGISIdentityManager`
// or `ApplicationCredentialsManager`.
if(manager.canRefresh) {
manager.refreshCredentials().then(()=> {
console.log("Credentials refreshed");
}).catch((error) => {
console.log("Error refreshing credentials");
})
}
Tokens are also automatically refreshed in the following cases if the can
property is true:
- If a token is used for a request 5 minutes or less before a token expires, the token will be refreshed and the new token will be used for the request.
- If a service responds with an invalid token error, the token will be refreshed and the request retried with the new token.
You can also use can
and refresh
to periodically refresh the credentials while the user is using your application.
// ideally this would run sometime after your application loads
if (manager.canRefresh) {
// refresh the credentials to ensure we have a fresh access token which will expire in 30 minutes
manager.refreshCredentials().then(()=>{
// once we have a fresh token set a timeout to refresh every 25 minutes.
setTimeout(()=>{
manager.refreshCredentials()
}, 25 * 60000)
})
}
Handle errors
When using ArcGIS
and Application
ArcGIS REST JS will throw additional errors related to managing the token and token lifecycle.
These errors provide more insight into the token lifecycle and are discussed more in the error handling topic.
Tutorials
Authenticate with an API key
Learn how to use an API key to make authenticated requests to location services.
Implement user authentication (Server)
Learn how to implement user authentication server-side using ArcGIS REST JS API
Implement user authentication (Browser)
Learn how to implement user authentication from the browser using the ArcGIS REST JS API.