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

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

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

clientId: string

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

password

password: string

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

portal

portal: string

The current portal the user is authenticated with.

provider

provider: AuthenticationProvider

The authentication provider to use.

redirectUri

redirectUri: string

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

server

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

ssl: boolean

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

tokenDuration

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

get canRefresh(): boolean

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

Returns 
boolean

refreshToken

get refreshToken(): string

The current token to ArcGIS Online or ArcGIS Enterprise.

Returns 
string

refreshTokenExpires

get refreshTokenExpires(): Date

The expiration time of the current refreshToken.

Returns 
Date

token

get token(): string

The current ArcGIS Online or ArcGIS Enterprise token.

Returns 
string

tokenExpires

get tokenExpires(): Date

The expiration time of the current token.

Returns 
Date

username

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

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

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)
 static 
destroy(manager)
 static 

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

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

fromCredential(credential, serverInfo)
 static 

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

fromParent(parentOrigin, win?)
 static 
Promise<any>

Request credentials information from the parent application

fromToken(options)
 static 

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

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

disablePostMessageAuth

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

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

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

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

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

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

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

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

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

refreshCredentials(requestOptions?ITokenRequestOptions): Promise<ArcGISIdentityManager>

Manually refreshes the current token and tokenExpires.

Parameters
ParameterType
requestOptions
ITokenRequestOptions
Returns 
Promise<ArcGISIdentityManager>

serialize

serialize(): string
Returns 
string

signOut

signOut(): Promise<IRevokeTokenResponse>

Convenience method for ArcGISIdentityManager.destroy for this instance of ArcGISIdentityManager

Returns 
Promise<IRevokeTokenResponse>

toCredential

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

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

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 static

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 static

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 static

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

deserialize(strstring): ArcGISIdentityManager
Parameters
ParameterType
str
string
Returns 
ArcGISIdentityManager

destroy static

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 static

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

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 static

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

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

signIn(optionsISignInOptions): Promise<ArcGISIdentityManager>

Initialize a ArcGISIdentityManager with a users 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.