ArcGISIdentityManager

Class

Used to authenticate both ArcGIS Online and ArcGIS Enterprise users. ArcGISIdentityManager includes helper methods for OAuth 2.0 in both browser and server applications.

It is not recommended to construct ArcGISIdentityManager directly. Instead there are several static methods used for specific workflows. The 2 primary workflows relate to oAuth 2.0:

ArcGISIdentityManager.beginOAuth2 and ArcGISIdentityManager.completeOAuth2() for oAuth 2.0 in browser-only environment.
ArcGISIdentityManager.authorize and ArcGISIdentityManager.exchangeAuthorizationCode for oAuth 2.0 for server-enabled application.

Other more specialized helpers for less common workflows also exist:

ArcGISIdentityManager.fromToken for when you have an existing token from another source and would like create an ArcGISIdentityManager instance.
ArcGISIdentityManager.fromCredential for creating an ArcGISIdentityManager instance from a Credentials object in the ArcGIS JS API IdentityManager
ArcGISIdentityManager.signIn for authenticating directly with a user's username and password for environments with a user interface for oAuth 2.0.

Once a manager is created there are additional utilities:

ArcGISIdentityManager.serialize can be used to create a JSON object representing an instance of ArcGISIdentityManager
ArcGISIdentityManager.deserialize will create a new ArcGISIdentityManager from a JSON object created with ArcGISIdentityManager.serialize
ArcGISIdentityManager.destroy or ArcGISIdentityManager.signOut will invalidate any tokens in use by the ArcGISIdentityManager.

Implements

IAuthenticationManager

Constructors

constructor

Class Constructor

new ArcGISIdentityManager(options: IArcGISIdentityManagerOptions): ArcGISIdentityManager

Parameters

Parameter	Type
`options`	IArcGISIdentityManagerOptions

Returns

ArcGISIdentityManager

Properties

Property	Type	Notes
`clientId`	`string`	Client ID being used for authentication if provided in the `constructor`.
`password`	`string`	The currently authenticated user's password if provided in the `constructor`.
`portal`	`string`	The current portal the user is authenticated with.
`provider`	`AuthenticationProvider`	The authentication provider to use.
`redirectUri`	`string`	A valid redirect URI for this application if provided in the `constructor`.
`referer`	`string`	The referer to use when getting the token with `.signIn()`
`server`	`string`	An unfederated ArcGIS Server instance known to recognize credentials supplied manually.
`ssl`	`boolean`	This value is set to true automatically if the ArcGIS Organization requires that requests be made over https.
`tokenDuration`	`number`	Determines how long new tokens requested are valid.

clientId

Class Property

clientId: string

Client ID being used for authentication if provided in the constructor.

password

Class Property

password: string

The currently authenticated user's password if provided in the constructor.

portal

Class Property

portal: string

The current portal the user is authenticated with.

provider

Class Property

provider: AuthenticationProvider

The authentication provider to use.

redirectUri

Class Property

redirectUri: string

A valid redirect URI for this application if provided in the constructor.

referer

Class Property

referer: string

The referer to use when getting the token with .signIn()

server

Class Property

server: string

An unfederated ArcGIS Server instance known to recognize credentials supplied manually.

Use dark colors for code blocksCopy
{
  server: "https://sampleserver6.arcgisonline.com/arcgis",
  token: "SOSlV3v..",
  tokenExpires: new Date(1545415669763)
}

ssl

Class Property

ssl: boolean

This value is set to true automatically if the ArcGIS Organization requires that requests be made over https.

tokenDuration

Class Property

tokenDuration: number

Determines how long new tokens requested are valid.

Accessors

Accessor	Returns	Notes
`get canRefresh()`	`boolean`	Returns `true` if these credentials can be refreshed and `false` if it cannot.
`get refreshToken()`	`string`	The current token to ArcGIS Online or ArcGIS Enterprise.
`get refreshTokenExpires()`	`Date`	The expiration time of the current `refreshToken`.
`get token()`	`string`	The current ArcGIS Online or ArcGIS Enterprise `token`.
`get tokenExpires()`	`Date`	The expiration time of the current `token`.
`get username()`	`string`	The currently authenticated user.

canRefresh

Class Accessor

get canRefresh(): boolean

Returns true if these credentials can be refreshed and false if it cannot.

Returns

boolean

refreshToken

Class Accessor

get refreshToken(): string

The current token to ArcGIS Online or ArcGIS Enterprise.

Returns

string

refreshTokenExpires

Class Accessor

get refreshTokenExpires(): Date

The expiration time of the current refreshToken.

Returns

Date

token

Class Accessor

get token(): string

The current ArcGIS Online or ArcGIS Enterprise token.

Returns

string

tokenExpires

Class Accessor

get tokenExpires(): Date

The expiration time of the current token.

Returns

Date

username

Class Accessor

get username(): string

The currently authenticated user.

Returns

string

Methods

Method	Returns	Notes
`disablePostMessageAuth(win?)`	`void`	For a "Host" app that has embedded other platform apps via iframes, when the host needs to transition routes, it should call `ArcGISIdentityManager.disablePostMessageAuth()` to remove the event listener and prevent memory leaks
`enablePostMessageAuth(validChildOrigins, win?)`	`any`	For a "Host" app that embeds other platform apps via iframes, after authenticating the user and creating a ArcGISIdentityManager, the app can then enable "post message" style authentication by calling this method.
`exchangeRefreshToken(requestOptions?)`	`Promise<ArcGISIdentityManager>`	Exchanges an unexpired `refreshToken` for a new one, also updates `token` and`tokenExpires`.
`getDomainCredentials(url)`	`RequestCredentials`	Returns the proper `credentials` option for `fetch` for a given domain. See trusted server. Used internally by underlying request methods to add support for specific security considerations.
`getPortal(requestOptions?)`	`Promise<any>`	Returns information about the currently logged in user's portal. Subsequent calls will not result in additional web traffic.
`getServerRootUrl(url)`	`string`	Determines the root of the ArcGIS Server or Portal for a given URL.
`getToken(url, requestOptions?)`	`Promise<string>`	Gets an appropriate token for the given URL. If `portal` is ArcGIS Online and the request is to an ArcGIS Online domain `token` will be used. If the request is to the current `portal` the current `token` will also be used. However if the request is to an unknown server we will validate the server with a request to our current `portal`.
`getUser(requestOptions?)`	`Promise<IUser>`	Returns information about the currently logged in user. Subsequent calls will not result in additional web traffic.
`getUsername()`	`Promise<string>`	Returns the username for the currently logged in user. Subsequent calls will not result in additional web traffic. This is also used internally when a username is required for some requests but is not present in the options.
`refreshCredentials(requestOptions?)`	`Promise<ArcGISIdentityManager>`	Manually refreshes the current `token` and `tokenExpires`.
`serialize()`	`string`
`signOut()`	`Promise<IRevokeTokenResponse>`	Convenience method for `ArcGISIdentityManager.destroy` for this instance of `ArcGISIdentityManager`
`toCredential()`	`ICredential`	Returns authentication in a format useable in the `IdentityManager.registerToken()` method in the ArcGIS API for JavaScript.
`toJSON()`	`IArcGISIdentityManagerOptions`
`updateToken(newToken, newTokenExpiration)`	`ArcGISIdentityManager`	Update the stored `ArcGISIdentityManager.token` and `ArcGISIdentityManager.tokenExpires` properties. This method is used internally when refreshing tokens. You may need to call this if you want update the token with a new token from an external source.
`validateAppAccess(clientId)`	`Promise<IAppAccess>`	Get application access information for the current user see `validateAppAccess` function for details
`authorize(options, response)`	`void`	Begins a new server-based OAuth 2.0 sign in. This will redirect the user to the ArcGIS Online or ArcGIS Enterprise authorization page.
`beginOAuth2(options, win?)`	`Promise<ArcGISIdentityManager>`	Begins a new browser-based OAuth 2.0 sign in. If `options.popup` is `true` the authentication window will open in a new tab/window. Otherwise, the user will be redirected to the authorization page in their current tab/window and the function will return `undefined`.
`completeOAuth2(options, win?)`	`Promise<ArcGISIdentityManager>`	Completes a browser-based OAuth 2.0 sign in. If `options.popup` is `true` the user will be returned to the previous window and the popup will close. Otherwise a new `ArcGISIdentityManager` will be returned. You must pass the same values for `clientId`, `popup`, `portal`, and `pkce` as you used in `beginOAuth2()`.
`deserialize(str)`	`ArcGISIdentityManager`
`destroy(manager)`	`Promise<IRevokeTokenResponse>`	Revokes all active tokens for a provided `ArcGISIdentityManager`. The can be considered the equivalent to signing the user out of your application.
`exchangeAuthorizationCode(options, authorizationCode)`	`Promise<ArcGISIdentityManager>`	Completes the server-based OAuth 2.0 sign in process by exchanging the `authorizationCode`for a `access_token`.
`fromCredential(credential, serverInfo)`	`ArcGISIdentityManager`	Translates authentication from the format used in the `IdentityManager` class in the ArcGIS API for JavaScript.
`fromParent(parentOrigin, win?)`	`Promise<any>`	Request credentials information from the parent application
`fromToken(options)`	`Promise<ArcGISIdentityManager>`	Create a `ArcGISIdentityManager` from an existing token. Useful for when you have a users token from a different authentication system and want to get a `ArcGISIdentityManager`.
`signIn(options)`	`Promise<ArcGISIdentityManager>`	Initialize a `ArcGISIdentityManager` with a user's `username` and `password`. This method is intended ONLY for applications without a user interface such as CLI tools..

disablePostMessageAuth

Class Method

disablePostMessageAuth(win?: any): void

For a "Host" app that has embedded other platform apps via iframes, when the host needs to transition routes, it should call ArcGISIdentityManager.disablePostMessageAuth() to remove the event listener and prevent memory leaks

Parameters

Parameter	Type
`win`	any

Returns

void

enablePostMessageAuth

Class Method

enablePostMessageAuth(validChildOrigins: string[], win?: any): any

For a "Host" app that embeds other platform apps via iframes, after authenticating the user and creating a ArcGISIdentityManager, the app can then enable "post message" style authentication by calling this method.

Internally this adds an event listener on window for the message event

Parameters

Parameter	Type	Notes
`validChildOrigins`	string[]	Array of origins that are allowed to request authentication from the host app
`win`	any

Returns

any

exchangeRefreshToken

Class Method

exchangeRefreshToken(requestOptions?: ITokenRequestOptions): Promise<ArcGISIdentityManager>

Exchanges an unexpired refreshToken for a new one, also updates token andtokenExpires.

Parameters

Parameter	Type
`requestOptions`	ITokenRequestOptions

Returns

Promise<ArcGISIdentityManager>

getDomainCredentials

Class Method

getDomainCredentials(url: string): RequestCredentials

Returns the proper credentials option for fetch for a given domain. See trusted server. Used internally by underlying request methods to add support for specific security considerations.

Parameters

Parameter	Type	Notes
`url`	string	The url of the request

Returns

RequestCredentials

"include" or "same-origin"

getPortal

Class Method

getPortal(requestOptions?: IRequestOptions): Promise<any>

Returns information about the currently logged in user's portal. Subsequent calls will not result in additional web traffic.

Use dark colors for code blocksCopy
manager.getPortal()
  .then(response => {
    console.log(portal.name); // "City of ..."
  })

Parameters

Parameter	Type	Notes
`requestOptions`	IRequestOptions	Options for the request. NOTE: `rawResponse` is not supported by this operation.

Returns

Promise<any>

A Promise that will resolve with the data from the response.

getServerRootUrl

Class Method

getServerRootUrl(url: string): string

Determines the root of the ArcGIS Server or Portal for a given URL.

Parameters

Parameter	Type	Notes
`url`	string	the URl to determine the root url for.

Returns

string

getToken

Class Method

getToken(url: string, requestOptions?: ITokenRequestOptions): Promise<string>

Gets an appropriate token for the given URL. If portal is ArcGIS Online and the request is to an ArcGIS Online domain token will be used. If the request is to the current portal the current token will also be used. However if the request is to an unknown server we will validate the server with a request to our current portal.

Parameters

Parameter	Type
`url`	string
`requestOptions`	ITokenRequestOptions

Returns

Promise<string>

getUser

Class Method

getUser(requestOptions?: IRequestOptions): Promise<IUser>

Returns information about the currently logged in user. Subsequent calls will not result in additional web traffic.

Use dark colors for code blocksCopy
manager.getUser()
  .then(response => {
    console.log(response.role); // "org_admin"
  })

Parameters

Parameter	Type	Notes
`requestOptions`	IRequestOptions	Options for the request. NOTE: `rawResponse` is not supported by this operation.

Returns

Promise<IUser>

A Promise that will resolve with the data from the response.

getUsername

Class Method

getUsername(): Promise<string>

Returns the username for the currently logged in user. Subsequent calls will not result in additional web traffic. This is also used internally when a username is required for some requests but is not present in the options.

Use dark colors for code blocksCopy
manager.getUsername()
  .then(response => {
    console.log(response); // "casey_jones"
  })

Returns

Promise<string>

refreshCredentials

Class Method

refreshCredentials(requestOptions?: ITokenRequestOptions): Promise<ArcGISIdentityManager>

Manually refreshes the current token and tokenExpires.

Parameters

Parameter	Type
`requestOptions`	ITokenRequestOptions

Returns

Promise<ArcGISIdentityManager>

serialize

Class Method

serialize(): string

Returns

string

signOut

Class Method

signOut(): Promise<IRevokeTokenResponse>

Convenience method for ArcGISIdentityManager.destroy for this instance of ArcGISIdentityManager

Returns

Promise<IRevokeTokenResponse>

toCredential

Class Method

toCredential(): ICredential

Returns authentication in a format useable in the IdentityManager.registerToken() method in the ArcGIS API for JavaScript.

This method can be used with ArcGISIdentityManager.fromCredential to interop with the ArcGIS API for JavaScript.

Use dark colors for code blocksCopy
require(["esri/id"], (esriId) => {
  esriId.registerToken(manager.toCredential());
})

Returns

ICredential

ICredential

toJSON

Class Method

toJSON(): IArcGISIdentityManagerOptions

Returns

IArcGISIdentityManagerOptions

updateToken

Class Method

updateToken(newToken: string, newTokenExpiration: Date): ArcGISIdentityManager

Update the stored ArcGISIdentityManager.token and ArcGISIdentityManager.tokenExpires properties. This method is used internally when refreshing tokens. You may need to call this if you want update the token with a new token from an external source.

Parameters

Parameter	Type	Notes
`newToken`	string	The new token to use for this instance of `ArcGISIdentityManager`.
`newTokenExpiration`	Date	The new expiration date of the token.

Returns

ArcGISIdentityManager

validateAppAccess

Class Method

validateAppAccess(clientId: string): Promise<IAppAccess>

Get application access information for the current user see validateAppAccess function for details

Parameters

Parameter	Type	Notes
`clientId`	string	application client id

Returns

Promise<IAppAccess>

authorize

staticnode only

Class Method

authorize(options: IOAuth2Options, response: ServerResponse): void

Begins a new server-based OAuth 2.0 sign in. This will redirect the user to the ArcGIS Online or ArcGIS Enterprise authorization page.

Parameters

Parameter	Type
`options`	IOAuth2Options
`response`	ServerResponse

Returns

void

beginOAuth2

staticbrowser only

Class Method

beginOAuth2(options: IOAuth2Options, win?: any): Promise<ArcGISIdentityManager>

Begins a new browser-based OAuth 2.0 sign in. If options.popup is true the authentication window will open in a new tab/window. Otherwise, the user will be redirected to the authorization page in their current tab/window and the function will return undefined.

If popup is true (the default) this method will return a Promise that resolves to an ArcGISIdentityManager instance and you must call ArcGISIdentityManager.completeOAuth2() on the page defined in the redirectUri. Otherwise it will return undefined and the ArcGISIdentityManager.completeOAuth2() method will return a Promise that resolves to an ArcGISIdentityManager instance.

A ArcGISAccessDeniedError error will be thrown if the user denies the request on the authorization screen.

Parameters

Parameter	Type
`options`	IOAuth2Options
`win`	any

Returns

Promise<ArcGISIdentityManager>

completeOAuth2

staticbrowser only

Class Method

completeOAuth2(options: IOAuth2Options, win?: any): Promise<ArcGISIdentityManager>

Completes a browser-based OAuth 2.0 sign in. If options.popup is true the user will be returned to the previous window and the popup will close. Otherwise a new ArcGISIdentityManager will be returned. You must pass the same values for clientId, popup, portal, and pkce as you used in beginOAuth2().

A ArcGISAccessDeniedError error will be thrown if the user denies the request on the authorization screen.

Parameters

Parameter	Type
`options`	IOAuth2Options
`win`	any

Returns

Promise<ArcGISIdentityManager>

deserialize

static

Class Method

deserialize(str: string): ArcGISIdentityManager

Parameters

Parameter	Type
`str`	string

Returns

ArcGISIdentityManager

destroy

static

Class Method

destroy(manager: ArcGISIdentityManager): Promise<IRevokeTokenResponse>

Revokes all active tokens for a provided ArcGISIdentityManager. The can be considered the equivalent to signing the user out of your application.

Parameters

Parameter	Type
`manager`	ArcGISIdentityManager

Returns

Promise<IRevokeTokenResponse>

exchangeAuthorizationCode

staticnode only

Class Method

exchangeAuthorizationCode(options: IOAuth2Options, authorizationCode: string): Promise<ArcGISIdentityManager>

Completes the server-based OAuth 2.0 sign in process by exchanging the authorizationCodefor a access_token.

Parameters

Parameter	Type
`options`	IOAuth2Options
`authorizationCode`	string

Returns

Promise<ArcGISIdentityManager>

fromCredential

static

Class Method

fromCredential(credential: ICredential, serverInfo: IServerInfo): ArcGISIdentityManager

Translates authentication from the format used in the IdentityManager class in the ArcGIS API for JavaScript.

You will need to call both IdentityManger.findCredential and IdentityManger.findServerInfo to obtain both parameters for this method.

This method can be used with ArcGISIdentityManager.toCredential to interop with the ArcGIS API for JavaScript.

Use dark colors for code blocksCopy
require(["esri/id"], (esriId) => {
  const credential = esriId.findCredential("https://www.arcgis.com/sharing/rest");
  const serverInfo = esriId.findServerInfo("https://www.arcgis.com/sharing/rest");

  const manager = ArcGISIdentityManager.fromCredential(credential, serverInfo);
});

Parameters

Parameter	Type
`credential`	ICredential
`serverInfo`	IServerInfo

Returns

ArcGISIdentityManager

ArcGISIdentityManager

fromParent

staticbrowser only

Class Method

fromParent(parentOrigin: string, win?: any): Promise<any>

Request credentials information from the parent application

When an application is embedded into another application via an IFrame, the embedded app can use window.postMessage to request credentials from the host application. This function wraps that behavior.

The ArcGIS API for Javascript has this built into the Identity Manager as of the 4.19 release.

Note: The parent application will not respond if the embedded app's origin is not:

the same origin as the parent or *.arcgis.com (JSAPI)
in the list of valid child origins (REST-JS)

Parameters

Parameter	Type	Notes
`parentOrigin`	string	origin of the parent frame. Passed into the embedded application as `parentOrigin` query param
`win`	any

Returns

Promise<any>

fromToken

static

Class Method

fromToken(options: IFromTokenOptions): Promise<ArcGISIdentityManager>

Create a ArcGISIdentityManager from an existing token. Useful for when you have a users token from a different authentication system and want to get a ArcGISIdentityManager.

Parameters

Parameter	Type
`options`	IFromTokenOptions

Returns

Promise<ArcGISIdentityManager>

static

Class Method

signIn(options: ISignInOptions): Promise<ArcGISIdentityManager>

Initialize a ArcGISIdentityManager with a user's username and password. This method is intended ONLY for applications without a user interface such as CLI tools..

If possible you should use ArcGISIdentityManager.beginOAuth2 to authenticate users in a browser or ArcGISIdentityManager.authorize for authenticating users with a web server.

Parameters

Parameter	Type
`options`	ISignInOptions

Returns

Promise<ArcGISIdentityManager>

ArcGIS REST JSAPI Reference

ArcGISIdentityManager

Was this page helpful?

Was this page helpful?