UserSession

Class

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

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
_pendingTokenRequests Private

Internal object to keep track of pending token requests. Used to prevent duplicate token requests.

_refreshToken Private string
_refreshTokenExpires Private Date
_token Private string
_tokenExpires Private Date
_user Private IUser

Hydrated by a call to getUser().

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.

server string

An unfederated ArcGIS Server instance that recognizes the supplied credentials.

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.

trustedServers Private

Internal list of trusted 3rd party servers (federated servers) that have been validated with generateToken.

username string

The currently authenticated user if provided in the constructor.

Accessors

Accessor Type Notes
refreshToken

The current token to ArcGIS Online or ArcGIS Enterprise.

refreshTokenExpires

The expiration time of the current refreshToken.

token

The current ArcGIS Online or ArcGIS Enterprise token.

tokenExpires

The expiration time of the current token.

Methods

Method Returns Notes
Promise<string>

Returns an unexpired token for the current portal.

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<string>

Validates that a given URL is properly federated with our current portal. Attempts to use the internal trustedServers cache first.

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

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

Promise<UserSession>

Manually refreshes the current token and tokenExpires.

Promise<>

Refreshes the current token and tokenExpires with refreshToken.

Promise<>

Refreshes the current token and tokenExpires with username and password.

string
ICredential

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

esriId.registerToken(session.toCredential());
IUserSessionOptions
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>

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.

UserSession

Completes a browser-based OAuth 2.0 sign if options.popup is true the user will be returned to the previous window. Otherwise a new UserSession will be returned.

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"
});

getFreshToken

Private Private Class Method

Returns an unexpired token for the current portal.

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<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>

getTokenForServer

Private Private Class Method

Validates that a given URL is properly federated with our current portal. Attempts to use the internal trustedServers cache first.

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

Promise<IUser> - A Promise that will resolve with the data from the response.


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

refreshRefreshToken

Private Private Class Method

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

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<>

refreshSession

Class Method

Manually refreshes the current token and tokenExpires.

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<UserSession>

refreshWithRefreshToken

Private Private Class Method

Refreshes the current token and tokenExpires with refreshToken.

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<>

refreshWithUsernameAndPassword

Private Private Class Method

Refreshes the current token and tokenExpires with username and password.

Parameters

Parameter Type Default Notes
requestOptions Optional ITokenRequestOptions

Returns

Promise<>

serialize

Class Method

  • serialize() : string

Returns

string

toCredential

Class Method

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

Returns

ICredential - ICredential


esriId.registerToken(session.toCredential());

toJSON

Class Method

Returns

IUserSessionOptions

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 otherwise the user will be redirected to the authorization page in their current tab.

Parameters

Parameter Type Default Notes
options Required IOauth2Options
win Optional any window

Returns

Promise<UserSession>

completeOAuth2

Static Static Class Method

Completes a browser-based OAuth 2.0 sign if options.popup is true the user will be returned to the previous window. Otherwise a new UserSession will be returned.

Parameters

Parameter Type Default Notes
options Required IOauth2Options
win Optional any window

Returns

UserSession

deserialize

Static Static Class Method

Parameters

Parameter Type Default Notes
str Required string

Returns

UserSession

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


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

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