324 lines
15 KiB
TypeScript
324 lines
15 KiB
TypeScript
import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions } from './global';
|
||
import { CustomTokenExchangeOptions } from './TokenExchange';
|
||
import { Dpop } from './dpop/dpop';
|
||
import { Fetcher, type FetcherConfig, type CustomFetchMinimalOutput } from './fetcher';
|
||
/**
|
||
* Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
|
||
*/
|
||
export declare class Auth0Client {
|
||
private readonly transactionManager;
|
||
private readonly cacheManager;
|
||
private readonly domainUrl;
|
||
private readonly tokenIssuer;
|
||
private readonly scope;
|
||
private readonly cookieStorage;
|
||
private readonly dpop;
|
||
private readonly sessionCheckExpiryDays;
|
||
private readonly orgHintCookieName;
|
||
private readonly isAuthenticatedCookieName;
|
||
private readonly nowProvider;
|
||
private readonly httpTimeoutMs;
|
||
private readonly options;
|
||
private readonly userCache;
|
||
private readonly myAccountApi;
|
||
private worker?;
|
||
private readonly activeLockKeys;
|
||
private readonly defaultOptions;
|
||
constructor(options: Auth0ClientOptions);
|
||
private _url;
|
||
private _authorizeUrl;
|
||
private _verifyIdToken;
|
||
private _processOrgHint;
|
||
private _prepareAuthorizeUrl;
|
||
/**
|
||
* ```js
|
||
* try {
|
||
* await auth0.loginWithPopup(options);
|
||
* } catch(e) {
|
||
* if (e instanceof PopupCancelledError) {
|
||
* // Popup was closed before login completed
|
||
* }
|
||
* }
|
||
* ```
|
||
*
|
||
* Opens a popup with the `/authorize` URL using the parameters
|
||
* provided as arguments. Random and secure `state` and `nonce`
|
||
* parameters will be auto-generated. If the response is successful,
|
||
* results will be valid according to their expiration times.
|
||
*
|
||
* IMPORTANT: This method has to be called from an event handler
|
||
* that was started by the user like a button click, for example,
|
||
* otherwise the popup will be blocked in most browsers.
|
||
*
|
||
* @param options
|
||
* @param config
|
||
*/
|
||
loginWithPopup(options?: PopupLoginOptions, config?: PopupConfigOptions): Promise<void>;
|
||
/**
|
||
* ```js
|
||
* const user = await auth0.getUser();
|
||
* ```
|
||
*
|
||
* Returns the user information if available (decoded
|
||
* from the `id_token`).
|
||
*
|
||
* @typeparam TUser The type to return, has to extend {@link User}.
|
||
*/
|
||
getUser<TUser extends User>(): Promise<TUser | undefined>;
|
||
/**
|
||
* ```js
|
||
* const claims = await auth0.getIdTokenClaims();
|
||
* ```
|
||
*
|
||
* Returns all claims from the id_token if available.
|
||
*/
|
||
getIdTokenClaims(): Promise<IdToken | undefined>;
|
||
/**
|
||
* ```js
|
||
* await auth0.loginWithRedirect(options);
|
||
* ```
|
||
*
|
||
* Performs a redirect to `/authorize` using the parameters
|
||
* provided as arguments. Random and secure `state` and `nonce`
|
||
* parameters will be auto-generated.
|
||
*
|
||
* @param options
|
||
*/
|
||
loginWithRedirect<TAppState = any>(options?: RedirectLoginOptions<TAppState>): Promise<void>;
|
||
/**
|
||
* After the browser redirects back to the callback page,
|
||
* call `handleRedirectCallback` to handle success and error
|
||
* responses from Auth0. If the response is successful, results
|
||
* will be valid according to their expiration times.
|
||
*/
|
||
handleRedirectCallback<TAppState = any>(url?: string): Promise<RedirectLoginResult<TAppState> | ConnectAccountRedirectResult<TAppState>>;
|
||
/**
|
||
* Handles the redirect callback from the login flow.
|
||
*
|
||
* @template AppState - The application state persisted from the /authorize redirect.
|
||
* @param {string} authenticationResult - The parsed authentication result from the URL.
|
||
* @param {string} transaction - The login transaction.
|
||
*
|
||
* @returns {RedirectLoginResult} Resolves with the persisted app state.
|
||
* @throws {GenericError | Error} If the transaction is missing, invalid, or the code exchange fails.
|
||
*/
|
||
private _handleLoginRedirectCallback;
|
||
/**
|
||
* Handles the redirect callback from the connect account flow.
|
||
* This works the same as the redirect from the login flow expect it verifies the `connect_code`
|
||
* with the My Account API rather than the `code` with the Authorization Server.
|
||
*
|
||
* @template AppState - The application state persisted from the connect redirect.
|
||
* @param {string} connectResult - The parsed connect accounts result from the URL.
|
||
* @param {string} transaction - The login transaction.
|
||
* @returns {Promise<ConnectAccountRedirectResult>} The result of the My Account API, including any persisted app state.
|
||
* @throws {GenericError | MyAccountApiError} If the transaction is missing, invalid, or an error is returned from the My Account API.
|
||
*/
|
||
private _handleConnectAccountRedirectCallback;
|
||
/**
|
||
* ```js
|
||
* await auth0.checkSession();
|
||
* ```
|
||
*
|
||
* Check if the user is logged in using `getTokenSilently`. The difference
|
||
* with `getTokenSilently` is that this doesn't return a token, but it will
|
||
* pre-fill the token cache.
|
||
*
|
||
* This method also heeds the `auth0.{clientId}.is.authenticated` cookie, as an optimization
|
||
* to prevent calling Auth0 unnecessarily. If the cookie is not present because
|
||
* there was no previous login (or it has expired) then tokens will not be refreshed.
|
||
*
|
||
* It should be used for silently logging in the user when you instantiate the
|
||
* `Auth0Client` constructor. You should not need this if you are using the
|
||
* `createAuth0Client` factory.
|
||
*
|
||
* **Note:** the cookie **may not** be present if running an app using a private tab, as some
|
||
* browsers clear JS cookie data and local storage when the tab or page is closed, or on page reload. This effectively
|
||
* means that `checkSession` could silently return without authenticating the user on page refresh when
|
||
* using a private tab, despite having previously logged in. As a workaround, use `getTokenSilently` instead
|
||
* and handle the possible `login_required` error [as shown in the readme](https://github.com/auth0/auth0-spa-js#creating-the-client).
|
||
*
|
||
* @param options
|
||
*/
|
||
checkSession(options?: GetTokenSilentlyOptions): Promise<void>;
|
||
/**
|
||
* Fetches a new access token and returns the response from the /oauth/token endpoint, omitting the refresh token.
|
||
*
|
||
* @param options
|
||
*/
|
||
getTokenSilently(options: GetTokenSilentlyOptions & {
|
||
detailedResponse: true;
|
||
}): Promise<GetTokenSilentlyVerboseResponse>;
|
||
/**
|
||
* Fetches a new access token and returns it.
|
||
*
|
||
* @param options
|
||
*/
|
||
getTokenSilently(options?: GetTokenSilentlyOptions): Promise<string>;
|
||
private _getTokenSilently;
|
||
/**
|
||
* ```js
|
||
* const token = await auth0.getTokenWithPopup(options);
|
||
* ```
|
||
* Opens a popup with the `/authorize` URL using the parameters
|
||
* provided as arguments. Random and secure `state` and `nonce`
|
||
* parameters will be auto-generated. If the response is successful,
|
||
* results will be valid according to their expiration times.
|
||
*
|
||
* @param options
|
||
* @param config
|
||
*/
|
||
getTokenWithPopup(options?: GetTokenWithPopupOptions, config?: PopupConfigOptions): Promise<string | undefined>;
|
||
/**
|
||
* ```js
|
||
* const isAuthenticated = await auth0.isAuthenticated();
|
||
* ```
|
||
*
|
||
* Returns `true` if there's valid information stored,
|
||
* otherwise returns `false`.
|
||
*
|
||
*/
|
||
isAuthenticated(): Promise<boolean>;
|
||
/**
|
||
* ```js
|
||
* await auth0.buildLogoutUrl(options);
|
||
* ```
|
||
*
|
||
* Builds a URL to the logout endpoint using the parameters provided as arguments.
|
||
* @param options
|
||
*/
|
||
private _buildLogoutUrl;
|
||
/**
|
||
* ```js
|
||
* await auth0.logout(options);
|
||
* ```
|
||
*
|
||
* Clears the application session and performs a redirect to `/v2/logout`, using
|
||
* the parameters provided as arguments, to clear the Auth0 session.
|
||
*
|
||
* If the `federated` option is specified it also clears the Identity Provider session.
|
||
* [Read more about how Logout works at Auth0](https://auth0.com/docs/logout).
|
||
*
|
||
* @param options
|
||
*/
|
||
logout(options?: LogoutOptions): Promise<void>;
|
||
private _getTokenFromIFrame;
|
||
private _getTokenUsingRefreshToken;
|
||
private _saveEntryInCache;
|
||
private _getIdTokenFromCache;
|
||
private _getEntryFromCache;
|
||
/**
|
||
* Releases any locks acquired by the current page that are not released yet
|
||
*
|
||
* Get's called on the `pagehide` event.
|
||
* https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
|
||
*/
|
||
private _releaseLockOnPageHide;
|
||
private _requestToken;
|
||
/**
|
||
* Exchanges an external subject token for an Auth0 token via a token exchange request.
|
||
*
|
||
* @param {CustomTokenExchangeOptions} options - The options required to perform the token exchange.
|
||
*
|
||
* @returns {Promise<TokenEndpointResponse>} A promise that resolves to the token endpoint response,
|
||
* which contains the issued Auth0 tokens.
|
||
*
|
||
* This method implements the token exchange grant as specified in RFC 8693 by first validating
|
||
* the provided subject token type and then constructing a token request to the /oauth/token endpoint.
|
||
* The request includes the following parameters:
|
||
*
|
||
* - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange".
|
||
* - `subject_token`: The external token provided via the options.
|
||
* - `subject_token_type`: The type of the external token (validated by this function).
|
||
* - `scope`: A unique set of scopes, generated by merging the scopes supplied in the options
|
||
* with the SDK’s default scopes.
|
||
* - `audience`: The target audience from the options, with fallback to the SDK's authorization configuration.
|
||
*
|
||
* **Example Usage:**
|
||
*
|
||
* ```
|
||
* // Define the token exchange options
|
||
* const options: CustomTokenExchangeOptions = {
|
||
* subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
|
||
* subject_token_type: 'urn:acme:legacy-system-token',
|
||
* scope: "openid profile"
|
||
* };
|
||
*
|
||
* // Exchange the external token for Auth0 tokens
|
||
* try {
|
||
* const tokenResponse = await instance.exchangeToken(options);
|
||
* // Use tokenResponse.access_token, tokenResponse.id_token, etc.
|
||
* } catch (error) {
|
||
* // Handle token exchange error
|
||
* }
|
||
* ```
|
||
*/
|
||
exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>;
|
||
protected _assertDpop(dpop: Dpop | undefined): asserts dpop is Dpop;
|
||
/**
|
||
* Returns the current DPoP nonce used for making requests to Auth0.
|
||
*
|
||
* It can return `undefined` because when starting fresh it will not
|
||
* be populated until after the first response from the server.
|
||
*
|
||
* It requires enabling the {@link Auth0ClientOptions.useDpop} option.
|
||
*
|
||
* @param nonce The nonce value.
|
||
* @param id The identifier of a nonce: if absent, it will get the nonce
|
||
* used for requests to Auth0. Otherwise, it will be used to
|
||
* select a specific non-Auth0 nonce.
|
||
*/
|
||
getDpopNonce(id?: string): Promise<string | undefined>;
|
||
/**
|
||
* Sets the current DPoP nonce used for making requests to Auth0.
|
||
*
|
||
* It requires enabling the {@link Auth0ClientOptions.useDpop} option.
|
||
*
|
||
* @param nonce The nonce value.
|
||
* @param id The identifier of a nonce: if absent, it will set the nonce
|
||
* used for requests to Auth0. Otherwise, it will be used to
|
||
* select a specific non-Auth0 nonce.
|
||
*/
|
||
setDpopNonce(nonce: string, id?: string): Promise<void>;
|
||
/**
|
||
* Returns a string to be used to demonstrate possession of the private
|
||
* key used to cryptographically bind access tokens with DPoP.
|
||
*
|
||
* It requires enabling the {@link Auth0ClientOptions.useDpop} option.
|
||
*/
|
||
generateDpopProof(params: {
|
||
url: string;
|
||
method: string;
|
||
nonce?: string;
|
||
accessToken: string;
|
||
}): Promise<string>;
|
||
/**
|
||
* Returns a new `Fetcher` class that will contain a `fetchWithAuth()` method.
|
||
* This is a drop-in replacement for the Fetch API's `fetch()` method, but will
|
||
* handle certain authentication logic for you, like building the proper auth
|
||
* headers or managing DPoP nonces and retries automatically.
|
||
*
|
||
* Check the `EXAMPLES.md` file for a deeper look into this method.
|
||
*/
|
||
createFetcher<TOutput extends CustomFetchMinimalOutput = Response>(config?: FetcherConfig<TOutput>): Fetcher<TOutput>;
|
||
/**
|
||
* Initiates a redirect to connect the user's account with a specified connection.
|
||
* This method generates PKCE parameters, creates a transaction, and redirects to the /connect endpoint.
|
||
*
|
||
* You must enable `Offline Access` from the Connection Permissions settings to be able to use the connection with Connected Accounts.
|
||
*
|
||
* @template TAppState - The application state to persist through the transaction.
|
||
* @param {RedirectConnectAccountOptions<TAppState>} options - Options for the connect account redirect flow.
|
||
* @param {string} options.connection - The name of the connection to link (e.g. 'google-oauth2').
|
||
* @param {string[]} [options.scopes] - Array of scopes to request from the Identity Provider during the connect account flow.
|
||
* @param {AuthorizationParams} [options.authorization_params] - Additional authorization parameters for the request to the upstream IdP.
|
||
* @param {string} [options.redirectUri] - The URI to redirect back to after connecting the account.
|
||
* @param {TAppState} [options.appState] - Application state to persist through the transaction.
|
||
* @param {(url: string) => Promise<void>} [options.openUrl] - Custom function to open the URL.
|
||
*
|
||
* @returns {Promise<void>} Resolves when the redirect is initiated.
|
||
* @throws {MyAccountApiError} If the connect request to the My Account API fails.
|
||
*/
|
||
connectAccountWithRedirect<TAppState = any>(options: RedirectConnectAccountOptions<TAppState>): Promise<void>;
|
||
}
|