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:

Other more specialized helpers for less common workflows also exist:

Once a manager is created there are additional utilities:

Implements

Constructors

constructor

Class Constructor
new ArcGISIdentityManager(optionsIArcGISIdentityManagerOptions): ArcGISIdentityManager
Parameters
ParameterType
options
IArcGISIdentityManagerOptions
Returns 
ArcGISIdentityManager

Properties

PropertyTypeNotes
string

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

string

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

string

The current portal the user is authenticated with.

The authentication provider to use.

string

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

string

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

string

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

boolean

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

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
1
2
3
4
5
{
  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

AccessorReturnsNotes
get canRefresh()
boolean

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

string

The current token to ArcGIS Online or ArcGIS Enterprise.

Date

The expiration time of the current refreshToken.

get token()
string

The current ArcGIS Online or ArcGIS Enterprise token.

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

MethodReturnsNotes
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?)

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

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.

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.

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?)

Manually refreshes the current token and tokenExpires.

string

Convenience method for ArcGISIdentityManager.destroy for this instance of ArcGISIdentityManager

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

updateToken(newToken, newTokenExpiration)

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.

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?)

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?)

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().

destroy(manager)

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)

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

fromCredential(credential, serverInfo)

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)

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)

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
ParameterType
win
any
Returns 
void

enablePostMessageAuth

Class Method
enablePostMessageAuth(validChildOriginsstring[], 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
ParameterTypeNotes
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
ParameterType
requestOptions
ITokenRequestOptions
Returns 
Promise<ArcGISIdentityManager>

getDomainCredentials

Class Method
getDomainCredentials(urlstring): 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
ParameterTypeNotes
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
1
2
3
4
manager.getPortal()
  .then(response => {
    console.log(portal.name); // "City of ..."
  })
Parameters
ParameterTypeNotes
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(urlstring): string

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

Parameters
ParameterTypeNotes
url
string

the URl to determine the root url for.

Returns 
string

getToken

Class Method
getToken(urlstring, 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
ParameterType
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
1
2
3
4
manager.getUser()
  .then(response => {
    console.log(response.role); // "org_admin"
  })
Parameters
ParameterTypeNotes
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
1
2
3
4
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
ParameterType
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
1
2
3
require(["esri/id"], (esriId) => {
  esriId.registerToken(manager.toCredential());
})
Returns 
ICredential

ICredential

updateToken

Class Method
updateToken(newTokenstring, newTokenExpirationDate): 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
ParameterTypeNotes
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(clientIdstring): Promise<IAppAccess>

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

Parameters
ParameterTypeNotes
clientId
string

application client id

Returns 
Promise<IAppAccess>

authorize

staticnode only
Class Method
authorize(optionsIOAuth2Options, responseServerResponse): 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
ParameterType
options
IOAuth2Options
response
ServerResponse
Returns 
void

beginOAuth2

staticbrowser only
Class Method
beginOAuth2(optionsIOAuth2Options, 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
ParameterType
options
IOAuth2Options
win
any
Returns 
Promise<ArcGISIdentityManager>

completeOAuth2

staticbrowser only
Class Method
completeOAuth2(optionsIOAuth2Options, 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
ParameterType
options
IOAuth2Options
win
any
Returns 
Promise<ArcGISIdentityManager>

deserialize

static
Class Method
deserialize(strstring): ArcGISIdentityManager
Parameters
ParameterType
str
string
Returns 
ArcGISIdentityManager

destroy

static
Class Method
destroy(managerArcGISIdentityManager): 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
ParameterType
manager
ArcGISIdentityManager
Returns 
Promise<IRevokeTokenResponse>

exchangeAuthorizationCode

staticnode only
Class Method
exchangeAuthorizationCode(optionsIOAuth2Options, authorizationCodestring): Promise<ArcGISIdentityManager>

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

Parameters
ParameterType
options
IOAuth2Options
authorizationCode
string
Returns 
Promise<ArcGISIdentityManager>

fromCredential

static
Class Method
fromCredential(credentialICredential, serverInfoIServerInfo): 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
1
2
3
4
5
6
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
ParameterType
credential
ICredential
serverInfo
IServerInfo
Returns 
ArcGISIdentityManager

ArcGISIdentityManager

fromParent

staticbrowser only
Class Method
fromParent(parentOriginstring, 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
ParameterTypeNotes
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(optionsIFromTokenOptions): 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
ParameterType
options
IFromTokenOptions
Returns 
Promise<ArcGISIdentityManager>

signIn

static
Class Method
signIn(optionsISignInOptions): 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
ParameterType
options
ISignInOptions
Returns 
Promise<ArcGISIdentityManager>

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