UserSession

Class
import { UserSession } from '@esri/arcgis-rest-auth';
UserSession.beginOAuth2({
  // register an app of your own to create a unique clientId
  clientId: "abc123",
  redirectUri: 'https://yourapp.com/authenticate.html'
})
  .then(session)
// or
new UserSession({
  username: "jsmith",
  password: "123456"
})
// or
UserSession.deserialize(cache)

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

Implements

Constructors

Constructor Parameters

Parameter Type Default Notes
options Required IUserSessionOptions

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.

refreshTokenTTL number

Duration of new OAuth 2.0 refresh token validity (in minutes).

server string

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

{
  server: "https://sampleserver6.arcgisonline.com/arcgis",
  token: "SOSlV3v..",
  tokenExpires: new Date(1545415669763)
}
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.

username string

The currently authenticated user if provided in the constructor.

Accessors

Accessor Type Notes
refreshToken string

The current token to ArcGIS Online or ArcGIS Enterprise.

refreshTokenExpires Date

The expiration time of the current refreshToken.

token string

The current ArcGIS Online or ArcGIS Enterprise token.

tokenExpires Date

The expiration time of the current token.

trustedServers [key: string]: {
expires:
Date
token:
string
}

Deprecated, use federatedServers instead.

Methods

Method Returns Notes
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<UserSession> | undefined

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 and the function will return Promise<UserSession>. Otherwise, the user will be redirected to the authorization page in their current tab/window and the function will return undefined.

UserSession

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

UserSession
Promise<UserSession>

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

UserSession

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

UserSession.fromCredential({
  userId: "jsmith",
  token: "secret"
});
Promise<any>

Request session 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)
void

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

any

For a "Host" app that embeds other platform apps via iframes, after authenticating the user and creating a UserSession, 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

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.

Promise<any>

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

session.getPortal()
  .then(response => {
    console.log(portal.name); // "City of ..."
  })
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 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.

Promise<IUser>

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

session.getUser()
  .then(response => {
    console.log(response.role); // "org_admin"
  })
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.

session.getUsername() .then(response => { console.log(response); // "casey_jones" })

Promise<UserSession>

Manually refreshes the current token and tokenExpires.

string
ICredential

Returns authentication in a format useable in the ArcGIS API for JavaScript.

esriId.registerToken(session.toCredential());
IUserSessionOptions
Promise<IAppAccess>

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

authorize

Static Static Class Method

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 Default Notes
options Required IOAuth2Options
response Required ServerResponse

Returns

void

beginOAuth2

Static Static Class Method

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 and the function will return Promise<UserSession>. Otherwise, the user will be redirected to the authorization page in their current tab/window and the function will return undefined.

Parameters

Parameter Type Default Notes
options Required IOAuth2Options
win Optional any window

Returns

Promise<UserSession> | undefined

completeOAuth2

Static Static Class Method

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

Parameters

Parameter Type Default Notes
options Required IOAuth2Options
win Optional any window

Returns

deserialize

Static Static Class Method

Parameters

Parameter Type Default Notes
str Required string

Returns

exchangeAuthorizationCode

Static Static Class Method

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

Parameters

Parameter Type Default Notes
options Required IOAuth2Options
authorizationCode Required string

Returns

Promise<UserSession>

fromCredential

Static Static Class Method

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

Parameters

Parameter Type Default Notes
credential Required ICredential

Returns

UserSession


UserSession.fromCredential({
  userId: "jsmith",
  token: "secret"
});

fromParent

Static Static Class Method

Request session information from the parent application

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

Parameters

Parameter Type Default Notes
parentOrigin Required string

origin of the parent frame. Passed into the embedded application as parentOrigin query param

win Optional any

Returns

Promise<any>

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)

disablePostMessageAuth

Class Method

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

  • disablePostMessageAuth(win: any) : void

Parameters

Parameter Type Default Notes
win Optional any

Returns

void

enablePostMessageAuth

Class Method

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

  • enablePostMessageAuth(validChildOrigins: string[] | string, win: any) : any

Parameters

Parameter Type Default Notes
validChildOrigins Required string[] | string

Array of origins that are allowed to request authentication from the host app

win Optional any

Returns

any

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

getDomainCredentials

Class Method

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.

  • getDomainCredentials(url: string) : RequestCredentials

Parameters

Parameter Type Default Notes
url Required string

The url of the request

Returns

"include" or "same-origin"

RequestCredentials

getPortal

Class Method

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

Parameters

Parameter Type Default Notes
requestOptions Optional IRequestOptions

Options for the request. NOTE: rawResponse is not supported by this operation.

Returns

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

Promise<any>

session.getPortal()
  .then(response => {
    console.log(portal.name); // "City of ..."
  })

getServerRootUrl

Class Method

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

  • getServerRootUrl(url: string) : string

Parameters

Parameter Type Default Notes
url Required string

the URl to determine the root url for.

Returns

string

getToken

Class Method

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 Default Notes
url Required string
requestOptions Optional ITokenRequestOptions

Returns

Promise<string>

getUser

Class Method

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

Parameters

Parameter Type Default Notes
requestOptions Optional IRequestOptions

Options for the request. NOTE: rawResponse is not supported by this operation.

Returns

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

Promise<IUser>

session.getUser()
  .then(response => {
    console.log(response.role); // "org_admin"
  })

getUsername

Class Method

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.

  • getUsername() : Promise<string>

Returns

Promise<string>

session.getUsername() .then(response => { console.log(response); // "casey_jones" })

refreshSession

Class Method

Manually refreshes the current token and tokenExpires.

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<UserSession>

serialize

Class Method

  • serialize() : string

Returns

string

toCredential

Class Method

Returns authentication in a format useable in the ArcGIS API for JavaScript.

Returns

ICredential


esriId.registerToken(session.toCredential());

toJSON

Class Method

Returns

validateAppAccess

Class Method

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

  • validateAppAccess(clientId: string) : Promise<IAppAccess>

Parameters

Parameter Type Default Notes
clientId Required string

application client id

Returns

Promise<IAppAccess>

Class defined in packages/arcgis-rest-auth/src/UserSession.ts:259