IdentityManagerBase

Class: esri/identity/IdentityManagerBase
Subclasses: IdentityManager
Since: ArcGIS API for JavaScript 4.0

This class provides the framework and helper methods required to implement a solution for managing user credentials.

The supported resources are:

  • ArcGIS Server resources secured using token-based authentication. Note that only ArcGIS Server versions 10 SP 1 and greater are supported.
  • Secured ArcGIS.com or ArcGIS Enterprise portal resources (i.e., web maps).

This class is not typically used by itself and does not include a user interface to obtain user input. The IdentityManager class provides a complete out-of-the-box implementation.

See also:

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
Number

The suggested lifetime of the token in minutes.

more details
more detailsIdentityManagerBase
Boolean

If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page.

more details
more detailsIdentityManagerBase

Property Details

tokenValidityNumber

The suggested lifetime of the token in minutes.

Default Value:60
useSignInPageBoolean

If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. For instance, let's say an application accesses secure resources from ArcGIS.com or one of its subdomains. Once the application attempts to access this resource, the IdentityManager redirects the user to the ArcGIS.com sign-in page. Once a user successfully logs in, they are redirected back to the application. The same holds true if the application accesses secure resources from ArcGIS Enterprise as the IdentityManager will redirect the user to its sign-in page. If you do not wish for the application to automatically redirect, set this property to false. (Please note that this is not a common scenario. For most, using the OAuth sign-in behavior should handle most of their authentication needs.)

Default Value:true

Method Overview

NameReturn TypeSummaryClass
Promise<Credential>

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

more details
more detailsIdentityManagerBase

Destroys all credentials.

more details
more detailsIdentityManagerBase

Emits an event on the instance.

more details
more detailsIdentityManagerBase
Credential

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

more details
more detailsIdentityManagerBase
OAuthInfo

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

more details
more detailsIdentityManagerBase
ServerInfo

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

more details
more detailsIdentityManagerBase
Promise<Object>

Returns an object containing a token and its expiration time.

more details
more detailsIdentityManagerBase
Promise<Object>

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

more details
more detailsIdentityManagerBase
Boolean

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

more details
more detailsIdentityManagerBase

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

more details
more detailsIdentityManagerBase
Boolean

Indicates if the IdentityManager is busy accepting user input.

more details
more detailsIdentityManagerBase
Promise<Object>

Subclasses must implement this method if OAuth support is required.

more details
more detailsIdentityManagerBase
Object

Registers an event handler on the instance.

more details
more detailsIdentityManagerBase

Registers OAuth 2.0 configurations.

more details
more detailsIdentityManagerBase

Register secure servers and the token endpoints.

more details
more detailsIdentityManagerBase

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

more details
more detailsIdentityManagerBase

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

more details
more detailsIdentityManagerBase

If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page.

more details
more detailsIdentityManagerBase
Promise<Object>

Subclasses must implement this method to create and manage the user interface used to obtain a username and password from the end user.

more details
more detailsIdentityManagerBase
Object

Return properties of this object in JSON format.

more details
more detailsIdentityManagerBase

Method Details

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:
TypeDescription
Promise<Credential>Resolves to the returned credential of the signed-in user.
destroyCredentials()

Destroys all credentials.

emit(type, event)
Since: ArcGIS API for JavaScript 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

The event payload.

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:
TypeDescription
CredentialThe credential for the resource identified by the specified URL.
findOAuthInfo(url){OAuthInfo}

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

Parameter:
url String

The URL to a Portal.

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

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

Parameter:
url String

The URL to the server

Returns:
TypeDescription
ServerInfoThe ServerInfo configuration for the passed in server URL.
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:
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.

Indicates if the server requires SSL.

Returns:
TypeDescription
Promise<Object>Resolves to an object containing a token and expiration time.
getCredential(url, options){Promise<Object>}

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

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

retry Boolean
optional

Determines if the method should make additional attempts to get the credentials after a failure.

token String
optional

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

Returns:
TypeDescription
Promise<Object>Resolves to an object containing a Credential that can be used to access the secured resource identified by the input URL.
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:
TypeDescription
BooleanReturns true if the class supports the input event.
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(){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:
TypeDescription
BooleanWhether IdentityManager is currently accepting user input.
oAuthSignIn(resUrl, serverInfo, oAuthInfo, options){Promise<Object>}

Subclasses must implement this method if OAuth support is required.

Parameters:
resUrl String

The resource URL.

serverInfo ServerInfo

A ServerInfo object that contains the token service URL.

oAuthInfo OAuthInfo

An OAuthInfo object that contains the authorization configuration.

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

Indicates whether the user will be shown a dialog before the OAuth popup window is opened.

token String
optional

Token used for previous unsuccessful attempts to fetch the given URL.

Returns:
TypeDescription
Promise<Object>Resolves to an object containing a token.
on(type, listener){Object}

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

Parameters:
type String

The name of event to listen for.

listener Function

The function to call when the event is fired.

Returns:
TypeDescription
ObjectReturns an event handler with a remove() method that can be called to stop listening for the event.
PropertyTypeDescription
removeFunctionWhen called, removes the listener from the event.
See also:
Example:
view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});
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) {
  var oAuthInfo = new OAuthInfo({
    appId: "<registered client id>"
  }); // required parameter
  esriId.registerOAuthInfos([oAuthInfo]);
});
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) {
  var serverInfo = new ServerInfo();
  serverInfo.server = "http://sampleserver6.arcgisonline.com";
  serverInfo.tokenServiceUrl = "http://sampleserver6.arcgisonline.com/arcgis/tokens/generateToken";
  esriId.registerServers([serverinfo]);
});
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. See also resource-proxy for another workflow to achieve this result.

Once a user logs in, the access token is registered with the IdentityManager. Subsequently, every AJAX 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:
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.

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.

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

setRedirectionHandler(handlerFunction)

If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. For instance, let's say an application accesses secure resources from ArcGIS.com or one of its subdomains. Once the application attempts to access this resource, the IdentityManager redirects the user to the ArcGIS.com sign-in page. Once a user successfully logs in, they are redirected back to the application. The same holds true if the application accesses secure resources from ArcGIS Enterprise as the IdentityManager will redirect the user to its sign-in page. Use this method if the application needs to execute custom logic before the page is redirected by creating a custom redirection handler. The IdentityManager calls the custom handler function with an object containing the redirection properties.

Parameters:
handlerFunction Function

The function passed to setRedirectionHandler receives an object containing redirection properties. These properties are listed in the table below.

Specification:
resourceUrl String

The URL of the secure resource that triggers the redirection to the ArcGIS.com sign-in page.

returnUrlParamName String

The application URL where the sign-in page redirects after a successful login. To create the return URL, append the application's URL to signInPage as a parameter. The returnUrlParamName contains the name of the parameter.

serverInfo ServerInfo

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

signInPage String

URL of the sign-in page where users will be redirected.

Example:
require(["esri/IdentityManager"], function(esriId)
{
  esriId.setRedirectionHandler(function(info)
  {
  // Execute custom logic then perform redirect
  window.location = info.signInPage "?"
  info.returnUrlParamName "=" window.location.href;
  });
});
signIn(url, serverInfo, options){Promise<Object>}

Subclasses must implement this method to create and manage the user interface used to obtain a username and password from the end user. It should perform the following tasks:

  • challenge the user for a username and password,
  • generate a token and return it to the caller.
Parameters:
url String

URL for the secured resource.

serverInfo ServerInfo

A ServerInfo object that contains the token service URL.

options Object
optional

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

Specification:
error Error

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

Returns:
TypeDescription
Promise<Object>Resolves to an object containing a token.
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:
TypeDescription
ObjectThe JSON object representing the IdentityManager instance calling this method.

Event Overview

NameTypeSummaryClass
{credential: Credential}

Fires when a credential is created.

more details
more detailsIdentityManagerBase

Fires when credentials are destroyed.

more details
more detailsIdentityManagerBase

Event Details

credential-create

Fires when a credential is created.

Property:
credential Credential

The returned credential.

credentials-destroy

Fires when credentials are destroyed.

API Reference search results

NameTypeModule
Loading...