IdentityManager

AMD: require(["esri/identity/IdentityManager"], (esriId) => { /* code goes here */ });
ESM: import esriId from "@arcgis/core/identity/IdentityManager.js";
Class: esri/identity/IdentityManager
Since: ArcGIS Maps SDK for JavaScript 4.0

This object provides the framework and helper methods used in managing user credentials for the following resources:

  • Secured ArcGIS.com or ArcGIS Enterprise portal resources (e.g. web maps).

  • ArcGIS Server resources secured using token-based authentication. Note that only ArcGIS Server versions 10 SP 1 and greater are supported. If your application accesses services from different domains, it is deemed a cross-domain request and you need to setup a proxy or use CORS (if supported by browser). If CORS is supported, the Identity Manager knows to make a request to the token service over https.

Authentication requests over http are prevented because sensitive data sent via GET can be viewed in server logs. To prevent this, the Identity Manager requires that you use POST over https to ensure your credentials are secure. View the proxy pages and CORS help topic for more details.

The IdentityManager module is slightly different than other modules in the API. Instead of returning a class constructor, it returns a singleton instance that has already been created by this module.

See also

Property Overview

Name Type Summary Class
Widget

Dialog box widget used to challenge the user for their credentials when the application attempts to access a secure resource.

IdentityManager
Number

The suggested lifetime of the token in minutes.

IdentityManager

Property Details

dialog

Property
dialog Widget

Dialog box widget used to challenge the user for their credentials when the application attempts to access a secure resource. This property is available after the dialog-create event has fired.

tokenValidity

Property
tokenValidity Number

The suggested lifetime of the token in minutes.

Default Value:60

Method Overview

Name Return Type Summary Class
Promise<object>

Returns a credential if the user has already signed in to access the given resource and is allowed to do so when using the given application id.

IdentityManager
Promise<Credential>

Returns the Credential if the user has already signed in to access the given resource.

IdentityManager

Destroys all credentials.

IdentityManager

Disables the use of window.postMessage to serve authentication requests that were enabled by enablePostMessageAuth.

IdentityManager
Boolean

Emits an event on the instance.

IdentityManager

Enables the IdentityManager to serve authentication requests for the given resource from apps running in child iframes.

IdentityManager
Credential

Returns the Credential for the resource identified by the specified url.

IdentityManager
OAuthInfo

Returns the OAuthInfo configuration for the passed in Portal server URL.

IdentityManager
ServerInfo

Returns information about the server that is hosting the specified URL.

IdentityManager
Promise<object>

Returns an object containing a token and its expiration time.

IdentityManager
Promise<Credential>

Returns a Credential object that can be used to access the secured resource identified by the input URL.

IdentityManager
Boolean

Indicates whether there is an event listener on the instance that matches the provided event name.

IdentityManager

Call this method during application initialization with the JSON previously obtained from the toJSON() method used to re-hydrate the state of IdentityManager.

IdentityManager
Boolean

Indicates if the IdentityManager is busy accepting user input.

IdentityManager
Object

Registers an event handler on the instance.

IdentityManager

Registers OAuth 2.0 configurations.

IdentityManager

Register secure servers and the token endpoints.

IdentityManager

Registers the given OAuth 2.0 access token or ArcGIS Server token with the IdentityManager.

IdentityManager

Once a user successfully logs in, they are redirected back to the application.

IdentityManager

Use this method in the popup callback page to pass the token and other values back to the IdentityManager.

IdentityManager

When accessing secured resources, the IdentityManager may prompt for username and password and send them to the server using a secure connection.

IdentityManager
Object

Return properties of this object in JSON format.

IdentityManager

Method Details

checkAppAccess

Method
checkAppAccess(resUrl, appId){Promise<object>}
Since: ArcGIS Maps SDK for JavaScript 4.10 IdentityManager since 4.0, checkAppAccess added at 4.10.

Returns a credential if the user has already signed in to access the given resource and is allowed to do so when using the given application id. In addition, it also returns a boolean, viewOnly, property that indicates whether the app is only viewable. The default is false. If the user has not signed in or does not have access, then the promise will be rejected and its error callback will be called.

This scenario is generally not common unless you are building a licensed app. Also, please note that this method should only be used if your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server and is only applicable to applications registered as items in the Esri organization.

Parameters
resUrl String

The resource URL.

appId String

The registered OAuth application id.

Returns
Type Description
Promise<object> Resolves to an object which contains the following properties:
Property Type Description
credential Credential The credential of the user.
viewOnly boolean Indicates whether the app is only viewable. Default is false.

checkSignInStatus

Method
checkSignInStatus(resUrl){Promise<Credential>}

Returns the Credential if the user has already signed in to access the given resource. If the user has not signed in, then the promise will be rejected and its error callback will be called.

Parameter
resUrl String

The resource URL.

Returns
Type Description
Promise<Credential> Resolves to the returned credential of the signed-in user.

destroyCredentials

Method
destroyCredentials()

Destroys all credentials. It is good practice to call this method if working with an application that contains sign-out functionality as any tokens generated via OAuth will automatically be revoked.

disablePostMessageAuth

Method
disablePostMessageAuth()
Since: ArcGIS Maps SDK for JavaScript 4.19 IdentityManager since 4.0, disablePostMessageAuth added at 4.19.

Disables the use of window.postMessage to serve authentication requests that were enabled by enablePostMessageAuth. This should be called to prevent memory leaks in SPA routing apps when they need to transition routes. Setting this this helps clean up and remove any windows's message event listeners that enablePostMessageAuth added.

Please refer to the topic, Passing authentication to IFramed apps for additional information. The main differences are:

  • The ArcGIS REST JS API's enablePostMessageAuth method's signature is different than what is provided in the ArcGIS Maps SDK for JavaScript as explained here.
  • Step three, i.e. Embed App boots and Requests Auth, does not apply when using the ArcGIS Maps SDK for JavaScript.

emit

Method
emit(type, event){Boolean}
Since: ArcGIS Maps SDK for JavaScript 4.5 IdentityManager since 4.0, emit added at 4.5.

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters
type String

The name of the event.

event Object
optional

The event payload.

Returns
Type Description
Boolean true if a listener was notified

enablePostMessageAuth

Method
enablePostMessageAuth(resUrl)
Since: ArcGIS Maps SDK for JavaScript 4.19 IdentityManager since 4.0, enablePostMessageAuth added at 4.19.

Enables the IdentityManager to serve authentication requests for the given resource from apps running in child iframes. The only apps that will be allowed to request the credential are ones that are either running at *.arcgis.com, or are running at the same origin as the host app. Requests from other apps will be ignored.

Only one resource may be authenticated in this manner at any one time. The URL of the resource should be used as the value of a parameter named arcgis-auth-portal that is included in the iframe's src URL. The iframe's src URL should also include another parameter named arcgis-auth-origin with a value of window.location.origin. Both of these parameter values should be URL-encoded using encodeURIComponent. These parameters are used by the IdentityManager, or the UserSession running in the iframe app when it needs the user's authentication to access a given resource.

Please refer to the topic, Passing authentication to IFramed apps for additional information. The main differences are:

  • The ArcGIS REST JS API's enablePostMessageAuth method's signature is different than what is provided in the ArcGIS Maps SDK for JavaScript as explained here.
  • Step three, i.e. Embed App boots and Requests Auth, does not apply when using the ArcGIS Maps SDK for JavaScript.
Parameter
resUrl String
optional

The resource URL. Default value is https://www.arcgis.com/sharing/rest.

findCredential

Method
findCredential(url, userId){Credential}

Returns the Credential for the resource identified by the specified url. Optionally, you can provide a userId to find credentials for a specific user.

Parameters
url String

The URL to a server.

userId String
optional

The userId for which you want to obtain credentials.

Returns
Type Description
Credential The credential for the resource identified by the specified URL.

findOAuthInfo

Method
findOAuthInfo(url){OAuthInfo}

Returns the OAuthInfo configuration for the passed in Portal server URL.

Parameter
url String

The URL to a Portal.

Returns
Type Description
OAuthInfo The OAuthInfo configuration for the passed in Portal server URL.
Example
require(["esri/identity/IdentityManager"], function(esriId) {
  let portalURL = "https://host.arcgis.com";
  findOAuthInfo = function (){
    let oAuthInfo = esriId.findOAuthInfo(portalURL)
    console.log(oAuthInfo.toJSON())
  }
});

findServerInfo

Method
findServerInfo(url){ServerInfo}

Returns information about the server that is hosting the specified URL.

Parameter
url String

The URL to the server

Returns
Type Description
ServerInfo The ServerInfo configuration for the passed in server URL.

generateToken

Method
generateToken(serverInfo, userInfo, options){Promise<object>}

Returns an object containing a token and its expiration time. It is necessary to provide the ServerInfo object that contains a token service URL and a user info object containing username and password. This is a helper method typically called by sub-classes to generate tokens.

Parameters
Specification
serverInfo ServerInfo

A ServerInfo object that contains a token service URL.

userInfo Object

A user info object containing a user name and password.

options Object
optional

See the table below for the structure of this object.

Specification
serverUrl String

The server URL.

token String

The server token.

ssl Boolean

Indicates if the server requires SSL.

Returns
Type Description
Promise<object> Resolves to an object containing a token and expiration time.

getCredential

Method
getCredential(url, options){Promise<Credential>}

Returns a Credential object that can be used to access the secured resource identified by the input URL.

Parameters
Specification
url String

The URL for the secure resource

options Object
optional

See the table below for the structure of the options object.

Specification
error Error
optional

Error object returned by the server from a previous attempt to fetch the given URL.

oAuthPopupConfirmation Boolean
optional
Default Value: true

If set to false, the user will not be shown a dialog before the OAuth popup window is opened.

token String
optional

Token used for a previous unsuccessful attempt to fetch the given URL.

Returns
Type Description
Promise<Credential> Resolves to an object containing a Credential that can be used to access the secured resource identified by the input URL.

hasEventListener

Method
hasEventListener(type){Boolean}

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameter
type String

The name of the event.

Returns
Type Description
Boolean Returns true if the class supports the input event.

initialize

Method
initialize(json)

Call this method during application initialization with the JSON previously obtained from the toJSON() method used to re-hydrate the state of IdentityManager.

Parameter
json Object

The JSON obtained from the toJSON() method.

isBusy

Method
isBusy(){Boolean}

Indicates if the IdentityManager is busy accepting user input. For example, it returns true if the user has invoked signIn and is waiting for a response.

Returns
Type Description
Boolean Whether IdentityManager is currently accepting user input.

on

Method
on(type, listener){Object}

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

An event or an array of events to listen for.

listener Function

The function to call when the event fires.

Returns
Type Description
Object Returns an event handler with a remove() method that should be called to stop listening for the event(s).
Property Type Description
remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

registerOAuthInfos

Method
registerOAuthInfos(oAuthInfos)

Registers OAuth 2.0 configurations.

Parameter
oAuthInfos OAuthInfo[]

An array of OAuthInfo objects that defines the OAuth configurations.

Example
require(["esri/identity/OAuthInfo", "esri/identity/IdentityManager"], function(OAuthInfo, esriId) {
  let oAuthInfo = new OAuthInfo({
    appId: "<registered client id>"
  }); // required parameter
  esriId.registerOAuthInfos([oAuthInfo]);
});

registerServers

Method
registerServers(serverInfos)

Register secure servers and the token endpoints.

Parameter
serverInfos ServerInfo[]

An array of ServerInfos objects that defines the secure service and token endpoint. The IdentityManager makes its best guess to determine the location of the secure server and token endpoint. Therefore, in most cases calling this method is not necessary. However, if the location of your server or token endpoint is not standard, use this method to register the location.

Example
require(["esri/identity/ServerInfo", "esri/identity/IdentityManager"], function(ServerInfo, esriId) {
  let serverInfo = new ServerInfo();
  serverInfo.server = "https://sampleserver6.arcgisonline.com";
  serverInfo.tokenServiceUrl = "https://sampleserver6.arcgisonline.com/arcgis/tokens/generateToken";
  serverInfo.hasServer = true;
  esriId.registerServers([serverInfo]);
});

registerToken

Method
registerToken(properties)

Registers the given OAuth 2.0 access token or ArcGIS Server token with the IdentityManager. See registerOAuthInfos for additional information. The registerToken method is an advanced workflow for pre-registering long-term tokens for when you don't want users to sign in.

Once a user logs in, the access token is registered with the IdentityManager. Subsequently, every request made by the application forwards this token when accessing web maps and other items stored in ArcGIS Online, or resources on your server.

Parameters
Specification
properties Object

See the table below for the structure of the properties object.

Specification
expires Number
optional

Token expiration time specified as number of milliseconds since 1 January 1970 00:00:00 UTC.

server String

For ArcGIS Online or Portal, this is https://www.arcgis.com/sharing/rest or similar to https://www.example.com/portal/sharing/rest. For ArcGIS Server this is similar to https://www.example.com/arcgis/rest/services.

ssl Boolean
optional

Set this to true if the user has an ArcGIS Online organizational account and the organization is configured to allow access to resources only through SSL.

token String

The access token.

userId String
optional

The id of the user who owns the access token.

setOAuthRedirectionHandler

Method
setOAuthRedirectionHandler(handlerFunction)

Once a user successfully logs in, they are redirected back to the application. Use this method if the application needs to execute custom logic before the page is redirected. The IdentityManager calls the custom handler function with an object containing redirection properties.

Parameter
handlerFunction handlerCallback

When called, the callback passed to setOAuthRedirectionHandler receives an object containing the redirection properties.

Example
require(["esri/identity/IdentityManager"],
function(esriId)
{
 esriId.setOAuthRedirectionHandler(function(info)
  {
   // Execute custom logic then perform redirect
   window.location = info.authorizeUrl + "?" + ioquery.objectToQuery(info.authorizeParams);
  });
});

setOAuthResponseHash

Method
setOAuthResponseHash(hash)

Use this method in the popup callback page to pass the token and other values back to the IdentityManager.

Parameter
hash String

The token information in addition to any other values needed to be passed back to the IdentityManager.

setProtocolErrorHandler

Method
setProtocolErrorHandler(handlerFunction)

When accessing secured resources, the IdentityManager may prompt for username and password and send them to the server using a secure connection. Due to potential browser limitations, it may not be possible to establish a secure connection with the server if the application is being run over HTTP protocol. In such cases, the Identity Manager will abort the request to fetch the secured resource. To resolve this issue, configure your web application server with HTTPS support and run the application over HTTPS. This is the recommended solution for production environments. However, for internal development environments that don't have HTTPS support, you can define a protocol error handler that allows the Identity Manager to continue with the process over HTTP protocol.

Parameters
Specification
handlerFunction Function

The function to call when the protocol is mismatched.

Specification
resourceUrl String

The secure resource URL.

serverInfo ServerInfo

ServerInfo object describing the server where the secure resource is hosted.

toJSON

Method
toJSON(){Object}

Return properties of this object in JSON format. It can be stored in a cookie or persisted in HTML5 LocalStorage and later used to:

  • Initialize the IdentityManager the next time a user opens your application.
  • Share the state of the IdentityManager between multiple web pages of your website. This way users will not be asked to sign in repeatedly when they launch your app multiple times or when navigating between multiple web pages in your website.
Returns
Type Description
Object The JSON object representing the IdentityManager instance calling this method.

Type Definitions

handlerCallback

Type Definition
handlerCallback(authorizeParams, authorizeUrl, oAuthInfo, resourceUrl, serverInfo)

The callback to execute when setOAuthRedirectionHandler() is called.

Parameters
authorizeParams Object

Object containing authorization parameters used to access the secure service. See the table below describing the properties of this object.

Specification
client_id String

The application ID of the registered application.

response_type String

The type of response returned.

state String

The state parameter passed back as the object in the Credential's oAuthState property.

expiration Number

The expiration time in minutes.

locale String

The locale being used.

redirect_uri String

The redirect URL represents the valid places that a user can be redirected to after a successful sign in.

authorizeUrl String

The OAuth 2.0 authorization URL for the portal.

oAuthInfo OAuthInfo

A reference to the OAuthInfo object.

resourceUrl String

The URL to the accessed resource.

serverInfo ServerInfo

The ServerInfo object describing the server where the secure resource is hosted.

Event Overview

Name Type Summary Class
{credential: Credential}

Fires when a credential is created.

IdentityManager

Fires when the IdentityManager dialog is created.

IdentityManager

Event Details

credential-create

Event
credential-create

Fires when a credential is created.

Property
credential Credential

The returned credential.

dialog-create

Event
dialog-create

Fires when the IdentityManager dialog is created. This is used to prompt users for their credentials.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.