React Types

AuthAppState

Application state saved before the user was redirected for a login.

Property Type Description

Property	Type	Description
`returnTo?`	`string`	The URL to return to after a successful login redirect callback.
`[key: string]`	`unknown`

returnTo?

string

The URL to return to after a successful login redirect callback.

[key: string]

unknown

AuthContextShape

extends AuthState

Property Type Description

Property	Type	Description
`changePasswordWithRedirect`	`( options?: Partial<ChangePasswordRedirectOptions> ) ⇒ void`	Redirects the browser to the change password page on the authorization server.
`registerWithRedirect`	`(options?: Partial<RegisterRedirectOptions>) ⇒ void`	Redirects the browser to the registration page on the authorization server
`checkSession`	`(options?: Partial<GetAccessTokenOptions>) ⇒ Promise<void>`	Attempts check the user’s session by silently retrieving an access token. If the user is no longer authenticated, this will clear the authentication state.
`clientId`	`string \| null`	The current client ID.
`findUserOperationsByScope`	`( scopes: Array<string> ) ⇒ Promise<UserOperationInformation>`	Find the user operations for the scopes for the user. This is useful for the client to know what operations the user is permitted to use for different scopes, e.g., can they manage account users? The object this returns will have a list of operations. Each operation will be a security scope mapped to the permitted operations such as `READ`, `UPDATE`, `DELETE`.
`getAccessToken`	`(options?: Partial<GetAccessTokenOptions>) ⇒ Promise<string>`	Retrieve an access token for the user using the silent authentication flow.
`getUserInfo`	`() ⇒ Promise<User>`	Retrieve the [User] information for the current user.
`loginWithRedirect`	`(options?: Partial<LoginRedirectOptions>) ⇒ Promise<void>`	Redirects the user to the authorization server’s login page as part of the Authorization Code Grant with PCKE flow.
`logoutWithRedirect`	`(options?: Partial<LogoutRedirectOptions>) ⇒ void`	Logs out the current user with a redirect URI back to the application.
`loginWithCredentials`	`( request: LoginWithCredentialsRequest ) ⇒ Promise<AxiosResponse<LoginWithCredentialsResponse, unknown>>`	Logs in the user with the given credentials rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable: set `broadleaf.auth.login.embedded.enabled` to `true` set `embeddedLoginEnabled` to `true` on the particular `AuthorizationServer`
`registerWithCredentials`	`( request: RegisterWithCredentialsRequest ) ⇒ Promise<AxiosResponse<User, unknown>>`	Registers the user with the given form data rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable: set `broadleaf.auth.login.embedded.enabled` to `true` set `embeddedLoginEnabled` to `true` on the particular `AuthorizationServer`
`changePasswordWithCredentials`	`( request: ChangePasswordWithCredentialsRequest ) ⇒ Promise<AxiosResponse<void, unknown>>`	Changes the user’s password with the given one rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable: set `broadleaf.auth.login.embedded.enabled` to `true` set `embeddedLoginEnabled` to `true` on the particular `AuthorizationServer`
`resetPasswordWithCredentials`	`( request: ResetPasswordWithCredentialsRequest ) ⇒ Promise<AxiosResponse<void, unknown>>`	Resets the user’s password with the given one rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable: set `broadleaf.auth.login.embedded.enabled` to `true` set `embeddedLoginEnabled` to `true` on the particular `AuthorizationServer`
`requestResetPasswordLinkWithCredentials`	`( request: RequestResetPasswordLinkRequest ) ⇒ Promise<AxiosResponse<void, unknown>>`	Submits a request to get a reset-password link in an email rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable: set `broadleaf.auth.login.embedded.enabled` to `true` set `embeddedLoginEnabled` to `true` on the particular `AuthorizationServer`
`updateAccountAndGetAccessToken`	`( accountId: string, options?: Partial<GetAccessTokenOptions> ) ⇒ Promise<string>`	Updates the account ID if the user has selected to operate in an Account context. This will also cause a new access token to be fetched.
`readAccountRoles`	`(applicationToken: string) ⇒ Promise<Array<UserRole>>`	Reads the roles available to the account (e.g., business account) users.

changePasswordWithRedirect

( options?: Partial<ChangePasswordRedirectOptions> ) ⇒ void

Redirects the browser to the change password page on the authorization server.

registerWithRedirect

(options?: Partial<RegisterRedirectOptions>) ⇒ void

Redirects the browser to the registration page on the authorization server

checkSession

(options?: Partial<GetAccessTokenOptions>) ⇒ Promise<void>

Attempts check the user’s session by silently retrieving an access token. If the user is no longer authenticated, this will clear the authentication state.

clientId

string | null

The current client ID.

findUserOperationsByScope

( scopes: Array<string> ) ⇒ Promise<UserOperationInformation>

Find the user operations for the scopes for the user. This is useful for the client to know what operations the user is permitted to use for different scopes, e.g., can they manage account users?

The object this returns will have a list of operations. Each operation will be a security scope mapped to the permitted operations such as READ, UPDATE, DELETE.

getAccessToken

(options?: Partial<GetAccessTokenOptions>) ⇒ Promise<string>

Retrieve an access token for the user using the silent authentication flow.

getUserInfo

() ⇒ Promise<User>

Retrieve the [User] information for the current user.

loginWithRedirect

(options?: Partial<LoginRedirectOptions>) ⇒ Promise<void>

Redirects the user to the authorization server’s login page as part of the Authorization Code Grant with PCKE flow.

logoutWithRedirect

(options?: Partial<LogoutRedirectOptions>) ⇒ void

Logs out the current user with a redirect URI back to the application.

loginWithCredentials

( request: LoginWithCredentialsRequest ) ⇒ Promise<AxiosResponse<LoginWithCredentialsResponse, unknown>>

Logs in the user with the given credentials rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable:

set broadleaf.auth.login.embedded.enabled to true
set embeddedLoginEnabled to true on the particular AuthorizationServer

registerWithCredentials

( request: RegisterWithCredentialsRequest ) ⇒ Promise<AxiosResponse<User, unknown>>

Registers the user with the given form data rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable:

set broadleaf.auth.login.embedded.enabled to true
set embeddedLoginEnabled to true on the particular AuthorizationServer

changePasswordWithCredentials

( request: ChangePasswordWithCredentialsRequest ) ⇒ Promise<AxiosResponse<void, unknown>>

Changes the user’s password with the given one rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable:

set broadleaf.auth.login.embedded.enabled to true
set embeddedLoginEnabled to true on the particular AuthorizationServer

resetPasswordWithCredentials

( request: ResetPasswordWithCredentialsRequest ) ⇒ Promise<AxiosResponse<void, unknown>>

Resets the user’s password with the given one rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable:

set broadleaf.auth.login.embedded.enabled to true
set embeddedLoginEnabled to true on the particular AuthorizationServer

requestResetPasswordLinkWithCredentials

( request: RequestResetPasswordLinkRequest ) ⇒ Promise<AxiosResponse<void, unknown>>

Submits a request to get a reset-password link in an email rather than redirecting to the Auth Service hosted form. Requires additional configuration on the backend to enable:

set broadleaf.auth.login.embedded.enabled to true
set embeddedLoginEnabled to true on the particular AuthorizationServer

updateAccountAndGetAccessToken

( accountId: string, options?: Partial<GetAccessTokenOptions> ) ⇒ Promise<string>

Updates the account ID if the user has selected to operate in an Account context. This will also cause a new access token to be fetched.

readAccountRoles

(applicationToken: string) ⇒ Promise<Array<UserRole>>

Reads the roles available to the account (e.g., business account) users.

AuthProviderProps

Props for the AuthProvider.

Property Type Description

Property	Type	Description
`accountId?`	`string`	The account ID selected for the user.
`baseURL`	`string`	The base URL of the authorization server.
`children?`	`React.ReactNode`	The children components of this provider.
`clientId`	`string`	The client ID.
`credentials?`	`boolean`	Whether to send credentials for cross-site XHR requests. Defaults to `false`.
`initializeClient?`	`(options: AuthClientOptions) ⇒ AuthClient`	A customer initializer function to create a new `AuthClient`.
`onRedirectCallback?`	`(appState: AuthAppState) ⇒ void`
`enableAutoRedirectToLoginParam?`	`boolean`	Determines whether a param indicating that the app should automatically redirect the user to login is enabled. This is used in cases where auto-login from the server is not possible due to needing third-party-cookies, which are blocked in most browsers by default. This param is usually not used unless refresh-token-rotation is also used.
`redirectUri?`	`string`	The default redirect URI used for login redirect flow. Defaults to `${window.location.origin}`.
`scope?`	`string`	The default scope used for authorization requests. Defaults to `USER`. If `#useRefreshTokens` is `true`, then `OFFLINE_ACCESS` will automatically be included.
`silentRedirectUri?`	`string`	The default redirect URI used for iframe, silent-authentication flow. This is only used if `#isRefreshTokenRotation` is `false`. Defaults to `${window.location.origin}/silent-callback.html`.
`skipRedirectCallback?`	`boolean`	Whether or not to skip the redirect callback. This may be necessary in certain scenarios where you are mixing authentication providers.
`tokenCache?`	`TokenCache`	Optionally provide a custom [TokenCache] implementation for storing access tokens. The default is WebStorageTokenCache.
`transactionStorage?`	`WebStorage`	Optionally provide a custom WebStorage implementation for storing transactions. The default is SessionStorage.
`usePkce?`	`boolean`	Whether to enabled the Proof-Key-for-Code-Exchange enhancement to the OAuth Authorization Code Flow. False by default.
`useRefreshTokens?`	`boolean`	Whether to use a refresh token rotation instead of iframe silent auth. The default is `false`. <a href="https://developer.broadleafcommerce.com/services/authentication-services/authorization#refresh_token_rotation_grant_type_em_since_1_4_0_em"> See Refresh Token (Rotation) Grant Type docs</a>.
`useIFrameAsFallbackForRefreshToken?`	`boolean`	Whether to use silent authentication with iframe as a fallback when `#useRefreshTokens` is `true` but there is no cached refresh token. This can occur when the user reloads the browser window since the tokens are stored in-memory. Default is `true`. Note that this still has the same drawbacks as auth code flow with silent auth if the browser has enabled Intelligent Tracking Protection and the user may need to be redirected to login after a refreshing the page.
`useSessionStorageForTokenCache?`	`boolean`	Whether to serialize the in-memory token cache to session storage to allow persistence across page loads. This is somewhat less secure than leaving the cache in-memory but may be necessary in cross-domain auth contexts, i.e., when the client is served on a different domain from the auth server, because browsers block the cross-domain session cookie. In these cases, the additional risk should be mitigated by also enabling refresh tokens (`useRefreshTokens`) with refresh token rotation and re-use detection—both supported by Broadleaf out of box when enabled.
`useLocalStorageForTokenCache?`	`boolean`	See `useSessionStorageForTokenCache`. Note that session storage is cleared when the browser is closed while local storage is not.
`fetchUserOperationsWithAccessToken?`	`boolean`	If enabled, then user operations will be fetched using the 'resource API' user operations endpoint that accepts a bearer token. Otherwise, user operations will be fetched using the endpoint that relies on session cookie authentication. The access-token approach is useful when in a cross-domain environment that can’t pass session cookies.

accountId?

string

The account ID selected for the user.

baseURL

string

The base URL of the authorization server.

children?

React.ReactNode

The children components of this provider.

clientId

string

The client ID.

credentials?

boolean

Whether to send credentials for cross-site XHR requests. Defaults to false.

initializeClient?

(options: AuthClientOptions) ⇒ AuthClient

A customer initializer function to create a new AuthClient.

onRedirectCallback?

(appState: AuthAppState) ⇒ void

enableAutoRedirectToLoginParam?

boolean

Determines whether a param indicating that the app should automatically redirect the user to login is enabled. This is used in cases where auto-login from the server is not possible due to needing third-party-cookies, which are blocked in most browsers by default. This param is usually not used unless refresh-token-rotation is also used.

redirectUri?

string

The default redirect URI used for login redirect flow. Defaults to ${window.location.origin}.

scope?

string

The default scope used for authorization requests. Defaults to USER. If #useRefreshTokens is true, then OFFLINE_ACCESS will automatically be included.

silentRedirectUri?

string

The default redirect URI used for iframe, silent-authentication flow. This is only used if #isRefreshTokenRotation is false. Defaults to ${window.location.origin}/silent-callback.html.

skipRedirectCallback?

boolean

Whether or not to skip the redirect callback. This may be necessary in certain scenarios where you are mixing authentication providers.

tokenCache?

TokenCache

Optionally provide a custom [TokenCache] implementation for storing access tokens. The default is WebStorageTokenCache.

transactionStorage?

WebStorage

Optionally provide a custom WebStorage implementation for storing transactions. The default is SessionStorage.

usePkce?

boolean

Whether to enabled the Proof-Key-for-Code-Exchange enhancement to the OAuth Authorization Code Flow. False by default.

useRefreshTokens?

boolean

Whether to use a refresh token rotation instead of iframe silent auth. The default is false.

<a href="https://developer.broadleafcommerce.com/services/authentication-services/authorization#refresh_token_rotation_grant_type_em_since_1_4_0_em"> See Refresh Token (Rotation) Grant Type docs</a>.

useIFrameAsFallbackForRefreshToken?

boolean

Whether to use silent authentication with iframe as a fallback when #useRefreshTokens is true but there is no cached refresh token. This can occur when the user reloads the browser window since the tokens are stored in-memory. Default is true.

Note that this still has the same drawbacks as auth code flow with silent auth if the browser has enabled Intelligent Tracking Protection and the user may need to be redirected to login after a refreshing the page.

useSessionStorageForTokenCache?

boolean

Whether to serialize the in-memory token cache to session storage to allow persistence across page loads.

This is somewhat less secure than leaving the cache in-memory but may be necessary in cross-domain auth contexts, i.e., when the client is served on a different domain from the auth server, because browsers block the cross-domain session cookie. In these cases, the additional risk should be mitigated by also enabling refresh tokens (useRefreshTokens) with refresh token rotation and re-use detection—both supported by Broadleaf out of box when enabled.

useLocalStorageForTokenCache?

boolean

See useSessionStorageForTokenCache. Note that session storage is cleared when the browser is closed while local storage is not.

fetchUserOperationsWithAccessToken?

boolean

If enabled, then user operations will be fetched using the 'resource API' user operations endpoint that accepts a bearer token. Otherwise, user operations will be fetched using the endpoint that relies on session cookie authentication. The access-token approach is useful when in a cross-domain environment that can’t pass session cookies.

AuthState

Contains information about the state of authentication such as whether the user is authenticated, the user’s details, and if there was an error during authentication.

Here’s the flow for some key properties:

Authentication check has not been performed:

{
  "isAuthenticated": false,
  "didAuthenticationCheck": false,
  "isLoading": false
}

Authentication check is in process

{
  "isAuthenticated": false,
  "didAuthenticationCheck": false,
  "isLoading": true
}

Authentication check has occurred and user is authenticated

{
  "isAuthenticated": true,
  "didAuthenticationCheck": true,
  "isLoading": false
}

Authentication check has occurred and user is not authenticated

{
  "isAuthenticated": false,
  "didAuthenticationCheck": true,
  "isLoading": false
}

Property Type Description

Property	Type	Description
`error?`	`Error`	An error that occurred during authentication.
`isAuthenticated`	`boolean`	Whether the user is to be authenticated. Will be false if the authentication request has not been received or is pending.
`didAuthenticationCheck`	`boolean`	Whether authentication has been attempted. Will be false until the check actually takes place and is completed.
`isLoading`	`boolean`	Whether the authentication check is ongoing. Will be false before authentication has been attempted.
`session?`	`SessionExpiry`	The expiry for the user’s session including the inactivity
`user?`	`IdentityClaims`	Claims for an issued access token.

error?

Error

An error that occurred during authentication.

isAuthenticated

boolean

Whether the user is to be authenticated. Will be false if the authentication request has not been received or is pending.

didAuthenticationCheck

boolean

Whether authentication has been attempted. Will be false until the check actually takes place and is completed.

isLoading

boolean

Whether the authentication check is ongoing. Will be false before authentication has been attempted.

session?

SessionExpiry

The expiry for the user’s session including the inactivity

user?

IdentityClaims

Claims for an issued access token.