Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/support
esri/workers
Object: IdentityManager

dojo.require("esri.IdentityManager");

Description

(Added at v2.5)
This module returns a singleton class that is automatically instantiated into esri.id when the module containing this class is imported into the application. This module provides the framework and helper methods required to implement a solution for managing user credentials for the following resources:
  • ArcGIS Server resources secured using token-based authentication. Note that only ArcGIS Server versions 10 SP 1 and greater are supported.
  • Secured ArcGIS.com resources (i.e. web maps).
If your application accesses services from different domains then it's a cross-domain request and so 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.

Internet Explorer (7-9) do not support CORS so the token request has to go through a proxy hosted on the same-origin as the application (identical protocol, hostname and port). 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 'Using a proxy' and 'CORS' sections in the Inside esri/request help topic for more details.

You can access the dialog box used by the IdentityManager using this code:
require([
  "dijit/registry", "dojo/query", ...
], function(registry, query, ... ) {
  var dialog = registry.byNode(query(".esriSignInDialog")[0]);
});

Samples

Search for samples that use this class.

Class hierarchy

esri.IdentityManagerBase
|_esri.IdentityManager

CSS

NameDescription
esriSignInDialogCSS class name for the dialog assigned to the IdentityManager. Use this CSS class when defining CSS style rules to customize the look and feel of the dialog box.

Properties

NameTypeSummary
dialogDialogDialog box widget used to challenge the user for their credentials when the application attempts to access a secure resource.
tokenValidityNumberThe suggested lifetime of the token in minutes.

Methods

NameReturn typeSummary
checkAppAccess(resUrl, appId)DeferredReturns 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.
checkSignInStatus(resUrl)DeferredReturns the credential (via Deferred) if the user has already signed in to access the given resource.
destroyCredentials()NoneDestroys all credentials.
disablePostMessageAuth()NoneDisables the use of window.postMessage to serve authentication requests that was enabled by enablePostMessageAuth. This should be called to prevent memory leaks in SPA routing apps when they need to transition routes.
enablePostMessageAuth(resUrl?)NoneEnables the IdentityManager to serve authentication requests for the given resource from apps running in child iframes.
findCredential(url, userId?)CredentialReturns the credential for the resource identified by the specified url.
findOAuthInfo(url)OAuthInfoReturns the OAuth configuration for the passed in Portal server URL.
findServerInfo(url)ServerInfoReturns information about the server that is hosting the specified url.
generateToken(serverInfo, userInfo, options?)DeferredReturns an object containing a token and its expiration time.
getCredential(url, options?)DeferredReturns a Credential object that can be used to access the secured resource identified by the input url.
initialize(json)NoneCall this method (during your application initialization) with JSON previously obtained from toJson method to re-hydrate the state of identity manager.
isBusy()BooleanReturns true if the identity manager is busy accepting user input, i.e., the user has invoked signIn and is waiting for a response.
oAuthSignIn(resUrl, serverInfo, OAuthInfo, options?)DeferredSub-classes must implement this method if OAuth support is required.
registerOAuthInfos(oAuthInfos)NoneRegisters OAuth configurations.
registerServers(serverInfos)NoneRegister secure servers and the token endpoints.
registerToken(properties)NoneRegisters the given OAuth2 access token with the identity manager.
setOAuthRedirectionHandler(handlerFunction)NoneWhen accessing secure resources via OAuth2 from ArcGIS.com or one of its sub-domains the IdentityManager redirects the user to the ArcGIS.com or Portal for ArcGIS sign-in page.
setOAuthResponseHash(hash)NoneUse this method in the popup callback page to pass the token and other values back to the IdentityManager.
setProtocolErrorHandler(handlerFunction)NoneWhen accessing secured resources, identity manager may prompt for username and password and send them to the server using a secure connection.
signIn(url, serverInfo, options?)DeferredThis method is called by the base identity manager implementation.
toJson()ObjectReturn properties of this object in JSON.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
credential-create
{
  credential: <Credential>
}
Fired when a credential is created.
credentials-destroyFired when all credentials are destroyed.
dialog-cancel
{
  info: <Object>
}
Fired when the user clicks the cancel button on the dialog box widget.
dialog-createFired when the dialog box widget, used to prompt users for their credentials, is created.
Property Details

<Dialog> dialog

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 onDialogCreate event has fired. (Added at v2.6)

<Number> tokenValidity

The suggested lifetime of the token in minutes. Default is 60 minutes.
Method Details

checkAppAccess(resUrl, appId)

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 application is only viewable. It defaults to false. If the user has not signed in or does not have access, then it will be rejected and its error callback will be called.

Note: 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.

Return type: Deferred
Parameters:
<String> resUrl Required The resource URL.
<String> appId Required The registered OAuth application id.

checkSignInStatus(resUrl)

Returns the credential (via Deferred) if the user has already signed in to access the given resource. If the user has not signed in, then the deferred will be rejected and its error callback will be called. (Added at v3.10)
Return type: Deferred
Parameters:
<String> resUrl Required The resource URL.

destroyCredentials()

Destroys all credentials. (Added at v3.10)

disablePostMessageAuth()

Disables the use of window.postMessage to serve authentication requests that was 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 window'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 API for JavaScript as explained here.
  • Step three, i.e. Embed App boots and Requests Auth, does not apply when using the ArcGIS API for JavaScript.
(Added at v3.36)

enablePostMessageAuth(resUrl?)

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 API for JavaScript as explained here.
  • Step three, i.e. Embed App boots and Requests Auth, does not apply when using the ArcGIS API for JavaScript.
(Added at v3.36)
Parameters:
<String> resUrl Optional The resource URL. Default value is https://www.arcgis.com/sharing/rest

findCredential(url, userId?)

Returns the credential for the resource identified by the specified url. Optionally you can provide a userId to find credentials for a specific user.
Return type: Credential
Parameters:
<String> url Required The url to a server.
<String> userId Optional The userId for which you want to obtain credentials.

findOAuthInfo(url)

Returns the OAuth configuration for the passed in Portal server URL. (Added at v3.10)
Return type: OAuthInfo
Parameters:
<String> url Required The ArcGIS for Portal URL, for example "https://www.arcgis.com" for ArcGIS Online and "https://www.example.com/portal" for your in-house portal.

findServerInfo(url)

Returns information about the server that is hosting the specified url.
Return type: ServerInfo
Parameters:
<String> url Required The url to a server.

generateToken(serverInfo, userInfo, options?)

Returns an object containing a token and its expiration time. You need to provide the ServerInfo object that contains 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.
Return type: Deferred
Parameters:
<ServerInfo> serverInfo Required A ServerInfo object that contains a token service URL.
<Object> userInfo Required A user info object containing a user name and password.
<Object> options Optional Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Boolean> isAdmin Required Indicates that the token should be generated using the token service deployed with the ArcGIS Server Admin API. The default value is false.

getCredential(url, options?)

Returns a Credential object that can be used to access the secured resource identified by the input url. If required the user will be challenged for a username and password which is used to generate a token. Note: The IdentityManager sets up a timer to update the Credential object with a new token prior to the expiration time. This method is typically called by esri.request when a request fails due to an invalid credentials error.
Return type: Deferred
Parameters:
<String> url Required The url for the secure resource.
<Object> options Optional Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Error> error Optional Error object returned by the server from a previous attempt to fetch the given url.
<Boolean> oAuthPopupConfirmation Required If set to "false", the user will not be shown a dialog before the OAuth popup window is opened. The default is "true" since otherwise the browser is likely to block the popup from opening. Added at version 3.10
<Boolean> retry Optional Determines if the method should make additional attempts to get the credentials after a failure.
<String> token Optional Token used for a previous unsuccessful attempt to fetch the given url.

initialize(json)

Call this method (during your application initialization) with JSON previously obtained from toJson method to re-hydrate the state of identity manager. (Added at v2.8)
Parameters:
<Object> json Required The JSON obtained from the toJson method.

isBusy()

Returns true if the identity manager is busy accepting user input, i.e., the user has invoked signIn and is waiting for a response.
Return type: Boolean

oAuthSignIn(resUrl, serverInfo, OAuthInfo, options?)

Sub-classes must implement this method if OAuth support is required. (Added at v3.10)
Return type: Deferred
Parameters:
<String> resUrl Required The resource URL.
<ServerInfo> serverInfo Required A ServerInfo object that contains the token service url.
<OAuthInfo> OAuthInfo Required A OAuthInfo object that contains the authorization configuration.
<Object> options Optional Optional parameters. See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Error> error Required Error object returned by the server from a previous attempt to fetch the given url.
<Boolean> oAuthPopupConfirmation Required If set to "false", the user will not be shown a dialog before the OAuth popup window is opened. The default is "true" since otherwise the browser is likely to block the popup from opening.
<String> token Required Token used for previous unsuccessful attempts to fetch the given url.

registerOAuthInfos(oAuthInfos)

Registers OAuth configurations. (Added at v3.10)
Parameters:
<OAuthInfo[]> oAuthInfos Required An OAuthInfos object that defines the OAuth configurations.
Sample:
require([
  "esri/arcgis/OAuthInfo", "esri/IdentityManager", ... 
], function(OAuthInfo, esriId, ... ) {
  var oAuthInfo = new OAuthInfo({
        appId: "", //required parameter
        ... //specify optional parameters if needed
  esriId.registerOAuthInfos([oAuthInfo]);
});

registerServers(serverInfos)

Register secure servers and the token endpoints.
Parameters:
<ServerInfo[]> serverInfos Required A ServerInfos object that defines the secure service and token endpoint. The Identity Manager makes its best guess to determine the location of the secure server and token endpoint so in most cases calling registerServers is not necessary. However, use this method to register the location if the location of your server or token endpoint is non-standard.
Sample:
require([
  "esri/ServerInfo", "esri/IdentityManager", ... 
], function(ServerInfo, esriId, ... ) {
  var serverInfo = new ServerInfo();
  serverInfo.server = 'http://sampleserver6.arcgisonline.com';
  serverInfo.hasServer = true;
  serverInfo.tokenServiceUrl = 'http://sampleserver6.arcgisonline.com/arcgis/tokens/generateToken';          
    
  esriId.registerServers([serverInfo]);
});

registerToken(properties)

Registers the given OAuth2 access token with the identity manager.

An access token can be obtained after the user logs in to ArcGIS Online through your application. This process is described in the Browser-based User Logins help topic and demonstrated in this sample application.

Once registered with the identity manager, the access token will be passed along with all AJAX requests made by the application (on behalf of the logged in user) to access WebMaps and other items stored in ArcGIS Online. (Added at v3.4)
Parameters:
<Object> properties Required See the object specifications table below for the structure of the properties object.
Object Specifications:
<properties>
<Number> expires Required Token expiration time specified as number of milliseconds since 1 January 1970 00:00:00 UTC.
<String> server Required For ArcGIS Online or Portal, this is https://www.arcgis.com/sharing/rest or similar to https://www.example.com/portal/sharing/rest.
<Boolean> ssl Required 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.
<String> token Required The access token.
<String> userId Required The id for the user who owns the access token.

setOAuthRedirectionHandler(handlerFunction)

When accessing secure resources via OAuth2 from ArcGIS.com or one of its sub-domains the IdentityManager redirects the user to the ArcGIS.com or Portal for ArcGIS sign-in page. Once the 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.

(Added at v3.10)
Parameters:
<Function> handlerFunction Required When called, the function passed to setOAuthRedirectionHandler receives an object containing the redirection properties. See the object specifications table below for the structure of the handlerFunction object.
Object Specifications:
<handlerFunction>
<Object> authorizeParams Required Object containing authorization parameters used to access the secure service.
{
    client_id: "", //app_id from registered application
    response_type: "token",
    //state parameter passed back as Object in Credential.oAuthState property.
    state: "{\"portalUrl\":\"https://www.arcgis.com\"}", 
    // default expiration is 60*24*14 (2 weeks)
    expiration: 20160, 
    locale: "sv",
    redirect_uri: "http://host.esri.com/apps/test.html" 
  }
<String> authorizeUrl Required The OAuth2 authorization URL for the portal.
<OAuthInfo> oAuthInfo Required A reference to the OAuthInfo object.
<String> resourceUrl Required The URL to the resource being accessed.
<ServerInfo> serverInfo Required The ServerInfo object describing the server where the secure resource is hosted.
Sample:
require([
   "esri/IdentityManager", ... 
 ], function(esriId, ... ) {
  esriId.setOAuthRedirectionHandler(function(info) {
    // Execute custom logic then perform redirect
    window.location = info.authorizeUrl + "?" + ioquery.objectToQuery(info.authorizeParams);
  });
});

setOAuthResponseHash(hash)

Use this method in the popup callback page to pass the token and other values back to the IdentityManager. (Added at v3.10)
Parameters:
<String> hash Required The token information in addition to any other values needed to be passed back to the IdentityManager.

setProtocolErrorHandler(handlerFunction)

When accessing secured resources, identity manager may prompt for username and password and send them to the server using a secure connection. Due to browser limitations under certain conditions, it may not be possible to establish a secure connection with the server if the application is being run over HTTP protocol (you can identify the protocol by looking at the URL bar in any browser). 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 environment 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 (insecure connection).

Note that identity manager will call your handler function with an object containing the following properties:

<String> resourceUrl The secure resource URL.
<ServerInfo> serverInfo Object describing the server where the secure resource is hosted.

Parameters:
<Function> handlerFunction Required The function to call when the protocol is mismatched.
Sample:
require([
   "esri/IdentityManager", ... 
 ], function(esriId, ... ) {
  //Note: This should not be used in a production enviroment
  esriId.setProtocolErrorHandler(function(){
    console.log("Protocol mismatch error");
    return window.confirm("Protocol mismatch error .... proceed anyway?");
  });
});

signIn(url, serverInfo, options?)

This method is called by the base identity manager implementation. When invoked, this method will do the following:
  • Display a modal dialog box for the application end-user to enter username and password.
  • Generate a token and creates a Credential object.
  • Return the Credential object to the caller (IdentityManagerBase) via a Deferred object.
Return type: Deferred
Parameters:
<String> url Required Url for the secure resource.
<ServerInfo> serverInfo Required A ServerInfo object that contains the token service url.
<Object> options Optional Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object.
Object Specifications:
<options>
<Error> error Required Error object returned by the server from a previous attempt to fetch the given url.
<Boolean> isAdmin Required Indicate that the token should be generated using the token service deployed with the ArcGIS Server Admin API. The default value is false.
<String> token Required Token used for previous unsuccessful attempts to fetch the given url.

toJson()

Return properties of this object in JSON. It can be stored in a Cookie or persisted in HTML5 LocalStorage and later used to:
  • Initialize the IdentityManager the next time user opens your application.
  • Share the state of identity manager between multiple web pages of your website.

This way your users won't be asked to sign in repeatedly when they launch your app multiple times or when navigating between multiple web pages in your website.

(Added at v2.8)
Return type: Object
Event Details
[ On Style Events | Connect Style Event ]

credential-create

Fired when a credential is created. (Added at v3.10)
Event Object Properties:
<Credential> credential The returned credential.
Sample:
require([IdentityManager], function(esriId) {
   esriId.on("credential-create", function(e) {
      console.log ('Credential: ', e.credential);
      });
});

credentials-destroy

Fired when all credentials are destroyed. (Added at v3.10)

dialog-cancel

Fired when the user clicks the cancel button on the dialog box widget. This event can be used to add custom logic when the user cancels the sign-in process. Should be used in favor of onDialogCancel. (Added at v3.5)
Event Object Properties:
<Object> info An object with the following properties: <String> resourceUrl URL of the secured resource for which the sign-in process was cancelled. <ServerInfo> serverInfo A ServerInfo object describing the server where the secure resource is hosted.

dialog-create

Fired when the dialog box widget, used to prompt users for their credentials, is created. Should be used in favor of onDialogCreate. (Added at v3.5)
See also: dialog
Show Modal