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
andArcGISIdentityManager.completeOAuth2
for oAuth 2.0 in browser-only environment.ArcGISIdentityManager.authorize
andArcGISIdentityManager.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 anArcGISIdentityManager
instance.ArcGISIdentityManager.fromCredential
for creating anArcGISIdentityManager
instance from aCredentials
object in the ArcGIS JS APIIdentityManager
ArcGISIdentityManager.signIn
for authenticating directly with a users 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 ofArcGISIdentityManager
ArcGISIdentityManager.deserialize
will create a newArcGISIdentityManager
from a JSON object created withArcGISIdentityManager.serialize
ArcGISIdentityManager.destroy
orArcGISIdentityManager.signOut
will invalidate any tokens in use by theArcGISIdentityManager
.
Implements
Constructors
new ArcGISIdentityManager(options: IArcGISIdentityManagerOptions): ArcGISIdentityManager
Parameters
Parameter | Type |
---|---|
options | IArcGISIdentityManagerOptions |
Returns
ArcGISIdentityManager
Properties
Property | Type | Notes |
---|---|---|
string | Client ID being used for authentication if provided in the | |
string | The currently authenticated user's password if provided in the | |
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 | |
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
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.
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
Accessor | Returns | Notes |
---|---|---|
| boolean | Returns |
| string | The current token to ArcGIS Online or ArcGIS Enterprise. |
| Date | The expiration time of the current |
| string | The current ArcGIS Online or ArcGIS Enterprise |
| Date | The expiration time of the current |
| 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
Method | Returns | Notes |
---|---|---|
| void | For a "Host" app that has embedded other platform apps via iframes, when the host needs
to transition routes, it should call |
| 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. |
| Promise<ArcGISIdentityManager> | Exchanges an unexpired |
| RequestCredentials | Returns the proper |
| 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. |
| Promise<string> | Gets an appropriate token for the given URL. If |
| 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. |
| Promise<ArcGISIdentityManager> | Manually refreshes the current |
| string | |
| Promise<IRevokeTokenResponse> | Convenience method for |
| Returns authentication in a format useable in the | |
| ||
| Update the stored | |
| Promise<IAppAccess> | Get application access information for the current user
see |
| 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. |
| Promise<ArcGISIdentityManager> | Begins a new browser-based OAuth 2.0 sign in. If |
| Promise<ArcGISIdentityManager> | Completes a browser-based OAuth 2.0 sign in. If |
| ||
| Promise<IRevokeTokenResponse> | Revokes all active tokens for a provided |
| Promise<ArcGISIdentityManager> | Completes the server-based OAuth 2.0 sign in process by exchanging the |
| Translates authentication from the format used in the | |
| Promise<any> | Request credentials information from the parent application |
| Promise<ArcGISIdentityManager> | Create a |
| Promise<ArcGISIdentityManager> | Initialize a |
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
Parameter | Type |
---|---|
win | any |
Returns
void
enablePostMessageAuth
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 |
---|---|---|
valid | 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
Parameter | Type |
---|---|
request | ITokenRequestOptions |
Returns
Promise<ArcGISIdentityManager>
getDomainCredentials
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
getPortal(requestOptions?: IRequestOptions): Promise<any>
Returns information about the currently logged in user's portal. Subsequent calls will not result in additional web traffic.
Parameters
Parameter | Type | Notes |
---|---|---|
request | IRequestOptions | Options for the request. NOTE: |
Returns
Promise<any>
A Promise that will resolve with the data from the response.
getServerRootUrl
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
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 |
request | 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.
Parameters
Parameter | Type | Notes |
---|---|---|
request | IRequestOptions | Options for the request. NOTE: |
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.
Returns
Promise<string>
refreshCredentials
refreshCredentials(requestOptions?: ITokenRequestOptions): Promise<ArcGISIdentityManager>
Manually refreshes the current token
and tokenExpires
.
Parameters
Parameter | Type |
---|---|
request | 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.
Returns
ICredential
ICredential
updateToken
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 |
---|---|---|
new | string | The new token to use for this instance of |
new | Date | The new expiration date of the token. |
Returns
ArcGISIdentityManager
validateAppAccess
validateAppAccess(clientId: string): Promise<IAppAccess>
Get application access information for the current user
see validateAppAccess
function for details
Parameters
Parameter | Type | Notes |
---|---|---|
client | string | application client id |
Returns
Promise<IAppAccess>
authorize static
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 static
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 static
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
deserialize(str: string): ArcGISIdentityManager
Parameters
Parameter | Type |
---|---|
str | string |
Returns
ArcGISIdentityManager
destroy static
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 static
exchangeAuthorizationCode(options: IOAuth2Options, authorizationCode: string): Promise<ArcGISIdentityManager>
Completes the server-based OAuth 2.0 sign in process by exchanging the authorizationCode
for a access_token
.
Parameters
Parameter | Type |
---|---|
options | IOAuth2Options |
authorization | string |
Returns
Promise<ArcGISIdentityManager>
fromCredential static
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.
Parameters
Parameter | Type |
---|---|
credential | ICredential |
server | IServerInfo |
Returns
ArcGISIdentityManager
ArcGISIdentityManager
fromParent static
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 |
---|---|---|
parent | string | origin of the parent frame. Passed into the embedded application as |
win | any |
Returns
Promise<any>
fromToken static
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>
signIn static
signIn(options: ISignInOptions): 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
Parameter | Type |
---|---|
options | ISignInOptions |
Returns
Promise<ArcGISIdentityManager>
clientId: string
Client ID being used for authentication if provided in the
constructor
.