IdentityManagerBase | References | ArcGIS Maps SDK for JavaScript

import { IdentityManagerBase } from "@arcgis/core/identity/IdentityManagerBase.js";

Since: ArcGIS Maps SDK for JavaScript 5.0

The IdentityManagerBase class provides the framework and helper methods used in managing user credentials. It is the type for the IdentityManager and is not intended to be used directly.

Properties

Property	Type	Class
`dialog`	`Widget \| null`
`tokenValidity`	`number \| null`

dialog

Property

Type: Widget | null

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

Type: number | null

The suggested lifetime of the token in minutes.

Default value: 60

Methods

Method	Signature	Class
`checkAppAccess`	`checkAppAccess(resUrl: string, appId: string): Promise<object>`
`checkSignInStatus`	`checkSignInStatus(resUrl: string): Promise<Credential>`
`destroyCredentials`	`destroyCredentials(): void`
`disablePostMessageAuth`	`disablePostMessageAuth(): void`
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`enablePostMessageAuth`	`enablePostMessageAuth(resUrl?: string): void`
`findCredential`	`findCredential(url: string \| null \| undefined, userId?: string): Credential \| undefined`
`findOAuthInfo`	`findOAuthInfo(portalUrl: string): OAuthInfo \| undefined`
`findServerInfo`	`findServerInfo(url: string): ServerInfo \| undefined`
`generateToken`	`generateToken(serverInfo: ServerInfo, userInfo: any, options?: IdentityManagerGenerateTokenOptions): Promise<{ expires: number; ssl?: boolean; token: string; validity: number; }>`
`getCredential`	`getCredential(url: string, options?: GetCredentialOptions): Promise<Credential>`
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`initialize`	`initialize(json: any): void`
`isBusy`	`isBusy(): boolean`
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin
`registerOAuthInfos`	`registerOAuthInfos(oAuthInfos: OAuthInfo[]): void`
`registerServers`	`registerServers(serverInfos: ServerInfo[]): void`
`registerToken`	`registerToken(properties: IdentityManagerRegisterTokenProperties): void`
`setOAuthRedirectionHandler`	`setOAuthRedirectionHandler(handlerFunction: OAuthRedirectHandler): void`
`setOAuthResponseHash`	`setOAuthResponseHash(hash: string): void`
`setProtocolErrorHandler`	`setProtocolErrorHandler(handlerFunction: ProtocolHandler): void`
`toJSON`	`toJSON(): object`

checkAppAccess

Method

Signature: checkAppAccess (resUrl: string, appId: string): 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. 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

Parameter	Type	Description	Required
resUrl	`string`	The resource URL.
appId	`string`	The registered OAuth application id.

Returns

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

Signature: checkSignInStatus (resUrl: string): 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.

Parameters

Parameter	Type	Description	Required
resUrl	`string`	The resource URL.

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

destroyCredentials

Method

Signature: destroyCredentials (): void

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.

Returns: void

disablePostMessageAuth

Method

Signature: disablePostMessageAuth (): void

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.

See also

Returns: void

emit

inherited Method

Signature: emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Since: ArcGIS Maps SDK for JavaScript 4.5

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

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

enablePostMessageAuth

Method

Signature: enablePostMessageAuth (resUrl?: string): void

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.

See also

Parameters

Parameter	Type	Description	Required
resUrl	`string`	The resource URL. Default value is `https://www.arcgis.com/sharing/rest`.

Returns: void

findCredential

Method

Signature: findCredential (url: string | null | undefined, userId?: string): Credential | undefined

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

Parameter	Type	Description	Required
url	`string \| null \| undefined`	The URL to a server.
userId	`string`	The userId for which you want to obtain credentials.

Returns: Credential | undefined
The credential for the resource identified by the specified URL.

findOAuthInfo

Method

Signature: findOAuthInfo (portalUrl: string): OAuthInfo | undefined

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

Parameters

Parameter	Type	Description	Required
portalUrl	`string`	The URL to a Portal.

Returns: OAuthInfo | undefined
The OAuthInfo configuration for the passed in Portal server URL.

Example

const identityManager = await $arcgis.import("@arcgis/core/identity/IdentityManager.js");
let portalURL = "https://host.arcgis.com";
findOAuthInfo = function (){
  let oAuthInfo = identityManager.findOAuthInfo(portalURL)
  console.log(oAuthInfo.toJSON())
}

findServerInfo

Method

Signature: findServerInfo (url: string): ServerInfo | undefined

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

Parameters

Parameter	Type	Description	Required
url	`string`	The URL to the server

Returns: ServerInfo | undefined
The ServerInfo configuration for the passed in server URL.

generateToken

Method

Signature: generateToken (serverInfo: ServerInfo, userInfo: any, options?: IdentityManagerGenerateTokenOptions): Promise<{ expires: number; ssl?: boolean; token: string; validity: number; }>

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

Parameter	Type	Description
serverInfo	`ServerInfo`	A ServerInfo object that contains a token service URL.
userInfo	`any`	A user info object containing a user name and password.
options	`IdentityManagerGenerateTokenOptions`	The options for generating a token.

Returns: Promise<{ expires: number; ssl?: boolean; token: string; validity: number; }>
Resolves to an object containing a token and expiration time.

getCredential

Method

Signature: getCredential (url: string, options?: GetCredentialOptions): Promise<Credential>

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

Parameters

Parameter	Type	Description	Required
url	`string`	The URL for the secure resource
options	`GetCredentialOptions`	The options for getting the credential.

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

hasEventListener

inherited Method

Signature: hasEventListener <Type extends EventNames<this>>(type: Type): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

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

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

initialize

Method

Signature: initialize (json: any): void

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

Parameters

Parameter	Type	Description	Required
json	`any`	The JSON obtained from the toJSON() method.

Returns: void

isBusy

Method

Signature: isBusy (): boolean

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

Returns: boolean
Whether IdentityManager is currently accepting user input.

on

inherited Method

Signature: on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

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

Parameters

Parameter	Type	Description	Required
type	`Type`	An event or an array of events to listen for.
listener	`EventedCallback<this["@eventTypes"][Type]>`	The function to call when the event fires.

Returns

ResourceHandle

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

Signature: registerOAuthInfos (oAuthInfos: OAuthInfo[]): void

Registers OAuth 2.0 configurations.

Parameters

Parameter	Type	Description	Required
oAuthInfos	`OAuthInfo[]`	An array of OAuthInfo objects that defines the OAuth configurations.

Returns: void

Example

const [OAuthInfo, identityManager] = await $arcgis.import([
  "@arcgis/core/identity/OAuthInfo.js",
  "@arcgis/core/identity/IdentityManager.js"
]);
let oAuthInfo = new OAuthInfo({
  appId: "<registered client id>"
}); // required parameter
identityManager.registerOAuthInfos([oAuthInfo]);

registerServers

Method

Signature: registerServers (serverInfos: ServerInfo[]): void

Parameters

Parameter	Type	Description	Required
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.

Returns: void

Example

const [ServerInfo, identityManager] = await $arcgis.import(["@arcgis/core/identity/ServerInfo.js", "@arcgis/core/identity/IdentityManager.js"]);
let serverInfo = new ServerInfo();
serverInfo.server = "https://sampleserver6.arcgisonline.com";
serverInfo.tokenServiceUrl = "https://sampleserver6.arcgisonline.com/arcgis/tokens/generateToken";
serverInfo.hasServer = true;
identityManager.registerServers([serverInfo]);

registerToken

Method

Signature: registerToken (properties: IdentityManagerRegisterTokenProperties): void

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

Parameter	Type	Description	Required
properties	`IdentityManagerRegisterTokenProperties`	Additional properties for registering a token.

Returns: void

setOAuthRedirectionHandler

Method

Signature: setOAuthRedirectionHandler (handlerFunction: OAuthRedirectHandler): void

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.

Parameters

Parameter	Type	Description	Required
handlerFunction	`OAuthRedirectHandler`	When called, the callback passed to `setOAuthRedirectionHandler` receives an object containing the redirection properties.

Returns: void

Example

const identityManager = await $arcgis.import("@arcgis/core/identity/IdentityManager.js");
identityManager.setOAuthRedirectionHandler(function(info)
 {
   // Execute custom logic then perform redirect
   window.location = info.authorizeUrl + "?" + new URLSearchParams(info.authorizeParams).toString();
});

setOAuthResponseHash

Method

Signature: setOAuthResponseHash (hash: string): void

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

Parameters

Parameter	Type	Description	Required
hash	`string`	The token information in addition to any other values needed to be passed back to the IdentityManager.

Returns: void

setProtocolErrorHandler

Method

Signature: setProtocolErrorHandler (handlerFunction: ProtocolHandler): void

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

Parameter	Type	Description	Required
handlerFunction	`ProtocolHandler`	The function to call when the protocol is mismatched.

Returns: void

toJSON

Method

Signature: 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: object
The JSON object representing the IdentityManager instance calling this method.

Events

Name	Type
`credential-create`	CustomEvent<IdentityManagerCredentialCreateEvent>
`dialog-create`	CustomEvent<void>

credential-create

Event

credential-create: CustomEvent<IdentityManagerCredentialCreateEvent>

Fires when a credential is created.

dialog-create

Event

dialog-create: CustomEvent<void>

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

Type definitions

GetCredentialOptions

Type definition

Supertypes: AbortOptions

error

Property

Type: Error | undefined

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

oAuthPopupConfirmation

Property

Type: boolean | undefined

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

Default value: true

token

Property

Type: string | undefined

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

ProtocolHandler

Type definition

Parameters

Parameter	Type	Description	Required
params	`ProtocolHandlerParameters`	The parameters to pass to the protocol handler.

Returns: boolean

ProtocolHandlerParameters

Type definition

resourceUrl

Property

Type: string

The secure resource URL.

serverInfo

Property

Type: ServerInfo

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

AuthorizeParameters

Type definition

response_type

Property

Type: string

The type of response returned.

expiration

Property

Type: number

The expiration time in minutes.

state

Property

Type: string

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

redirect_uri

Property

Type: string

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

locale

Property

Type: string

The locale being used.

client_id

Property

Type: string

The application ID of the registered application.

OAuthRedirectHandler

Type definition

The callback to execute when setOAuthRedirectionHandler() is called.

Parameters

Parameter	Type	Description	Required
info	`OAuthRedirectHandlerInfo`	An object containing parameter values for the `handlerCallback`.

Returns: void

OAuthRedirectHandlerInfo

Type definition

authorizeParams

Property

Type: AuthorizeParameters

Object containing authorization parameters used to access the secure service.

authorizeUrl

Property

Type: string

The OAuth 2.0 authorization URL for the portal.

resourceUrl

Property

Type: string

The URL to the accessed resource.

serverInfo

Property

Type: ServerInfo

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

oAuthInfo

Property

Type: OAuthInfo

A reference to the OAuthInfo object.

IdentityManagerCredentialCreateEvent

Type definition

credential

Property

Type: Credential

The returned credential.

IdentityManagerRegisterTokenProperties

Type definition

expires

Property

Type: number | undefined

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

UTC.

server

Property

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

Property

Type: boolean | undefined

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.