@auth0/nextjs-auth0
Version:
Auth0 Next.js SDK
276 lines (275 loc) • 13.4 kB
TypeScript
import type { IncomingMessage, ServerResponse } from "node:http";
import { NextRequest, NextResponse } from "next/server.js";
import { NextApiHandler, NextApiRequest, NextApiResponse } from "next/types.js";
import { AccessTokenForConnectionOptions, AuthorizationParameters, BackchannelAuthenticationOptions, LogoutStrategy, SessionData, SessionDataStore, StartInteractiveLoginOptions } from "../types/index.js";
import { BeforeSessionSavedHook, OnCallbackHook, RoutesOptions } from "./auth-client.js";
import * as withApiAuthRequired from "./helpers/with-api-auth-required.js";
import { AppRouterPageRoute, WithPageAuthRequiredAppRouterOptions, WithPageAuthRequiredPageRouterOptions } from "./helpers/with-page-auth-required.js";
import { SessionConfiguration } from "./session/abstract-session-store.js";
import { TransactionCookieOptions } from "./transaction-store.js";
export interface Auth0ClientOptions {
/**
* The Auth0 domain for the tenant (e.g.: `example.us.auth0.com`).
*
* If it's not specified, it will be loaded from the `AUTH0_DOMAIN` environment variable.
*/
domain?: string;
/**
* The Auth0 client ID.
*
* If it's not specified, it will be loaded from the `AUTH0_CLIENT_ID` environment variable.
*/
clientId?: string;
/**
* The Auth0 client secret.
*
* If it's not specified, it will be loaded from the `AUTH0_CLIENT_SECRET` environment variable.
*/
clientSecret?: string;
/**
* Additional parameters to send to the `/authorize` endpoint.
*/
authorizationParameters?: AuthorizationParameters;
/**
* If enabled, the SDK will use the Pushed Authorization Requests (PAR) protocol when communicating with the authorization server.
*/
pushedAuthorizationRequests?: boolean;
/**
* Private key for use with `private_key_jwt` clients.
* This should be a string that is the contents of a PEM file or a CryptoKey.
*/
clientAssertionSigningKey?: string | CryptoKey;
/**
* The algorithm used to sign the client assertion JWT.
* Uses one of `token_endpoint_auth_signing_alg_values_supported` if not specified.
* If the Authorization Server discovery document does not list `token_endpoint_auth_signing_alg_values_supported`
* this property will be required.
*/
clientAssertionSigningAlg?: string;
/**
* The URL of your application (e.g.: `http://localhost:3000`).
*
* If it's not specified, it will be loaded from the `APP_BASE_URL` environment variable.
*/
appBaseUrl?: string;
/**
* A 32-byte, hex-encoded secret used for encrypting cookies.
*
* If it's not specified, it will be loaded from the `AUTH0_SECRET` environment variable.
*/
secret?: string;
/**
* The path to redirect the user to after successfully authenticating. Defaults to `/`.
*/
signInReturnToPath?: string;
/**
* Configure the session timeouts and whether to use rolling sessions or not.
*
* See [Session configuration](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#session-configuration) for additional details.
*/
session?: SessionConfiguration;
/**
* Configure the transaction cookie used to store the state of the authentication transaction.
*/
transactionCookie?: TransactionCookieOptions;
/**
* Configure the logout strategy to use.
*
* - `'auto'` (default): Attempts OIDC RP-Initiated Logout first, falls back to `/v2/logout` if not supported
* - `'oidc'`: Always uses OIDC RP-Initiated Logout (requires RP-Initiated Logout to be enabled)
* - `'v2'`: Always uses the Auth0 `/v2/logout` endpoint (supports wildcards in allowed logout URLs)
*/
logoutStrategy?: LogoutStrategy;
/**
* Configure whether to include id_token_hint in OIDC logout URLs.
*
* **Recommended (default)**: Set to `true` to include `id_token_hint` parameter.
* Auth0 recommends using `id_token_hint` for secure logout as per the
* OIDC specification.
*
* **Alternative approach**: Set to `false` if your application cannot securely
* store ID tokens. When disabled, only `logout_hint` (session ID), `client_id`,
* and `post_logout_redirect_uri` are sent.
*
*
* @see https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0#oidc-logout-endpoint-parameters
* @default true (recommended and backwards compatible)
*/
includeIdTokenHintInOIDCLogoutUrl?: boolean;
/**
* A method to manipulate the session before persisting it.
*
* See [beforeSessionSaved](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#beforesessionsaved) for additional details
*/
beforeSessionSaved?: BeforeSessionSavedHook;
/**
* A method to handle errors or manage redirects after attempting to authenticate.
*
* See [onCallback](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#oncallback) for additional details
*/
onCallback?: OnCallbackHook;
/**
* A custom session store implementation used to persist sessions to a data store.
*
* See [Database sessions](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#database-sessions) for additional details.
*/
sessionStore?: SessionDataStore;
/**
* Configure the paths for the authentication routes.
*
* See [Custom routes](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#custom-routes) for additional details.
*/
routes?: RoutesOptions;
/**
* Allow insecure requests to be made to the authorization server. This can be useful when testing
* with a mock OIDC provider that does not support TLS, locally.
* This option can only be used when NODE_ENV is not set to `production`.
*/
allowInsecureRequests?: boolean;
/**
* Integer value for the HTTP timeout in milliseconds for authentication requests.
* Defaults to `5000` ms.
*/
httpTimeout?: number;
/**
* Boolean value to opt-out of sending the library name and version to your authorization server
* via the `Auth0-Client` header. Defaults to `true`.
*/
enableTelemetry?: boolean;
/**
* Boolean value to enable the `/auth/access-token` endpoint for use in the client app.
*
* Defaults to `true`.
*
* NOTE: Set this to `false` if your client does not need to directly interact with resource servers (Token Mediating Backend). This will be false for most apps.
*
* A security best practice is to disable this to avoid exposing access tokens to the client app.
*
* See: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps#name-token-mediating-backend
*/
enableAccessTokenEndpoint?: boolean;
/**
* If true, the profile endpoint will return a 204 No Content response when the user is not authenticated
* instead of returning a 401 Unauthorized response.
*
* Defaults to `false`.
*/
noContentProfileResponseWhenUnauthenticated?: boolean;
enableParallelTransactions?: boolean;
}
export type PagesRouterRequest = IncomingMessage | NextApiRequest;
export type PagesRouterResponse = ServerResponse<IncomingMessage> | NextApiResponse;
export declare class Auth0Client {
private transactionStore;
private sessionStore;
private authClient;
private routes;
constructor(options?: Auth0ClientOptions);
/**
* middleware mounts the SDK routes to run as a middleware function.
*/
middleware(req: NextRequest): Promise<NextResponse>;
/**
* getSession returns the session data for the current request.
*
* This method can be used in Server Components, Server Actions, and Route Handlers in the **App Router**.
*/
getSession(): Promise<SessionData | null>;
/**
* getSession returns the session data for the current request.
*
* This method can be used in middleware and `getServerSideProps`, API routes in the **Pages Router**.
*/
getSession(req: PagesRouterRequest | NextRequest): Promise<SessionData | null>;
/**
* getAccessToken returns the access token.
*
* This method can be used in Server Components, Server Actions, and Route Handlers in the **App Router**.
*
* NOTE: Server Components cannot set cookies. Calling `getAccessToken()` in a Server Component will cause the access token to be refreshed, if it is expired, and the updated token set will not to be persisted.
* It is recommended to call `getAccessToken(req, res)` in the middleware if you need to retrieve the access token in a Server Component to ensure the updated token set is persisted.
*/
/**
* @param options Optional configuration for getting the access token.
* @param options.refresh Force a refresh of the access token.
*/
getAccessToken(options?: GetAccessTokenOptions): Promise<{
token: string;
expiresAt: number;
scope?: string;
}>;
/**
* getAccessToken returns the access token.
*
* This method can be used in middleware and `getServerSideProps`, API routes in the **Pages Router**.
*
* @param req The request object.
* @param res The response object.
* @param options Optional configuration for getting the access token.
* @param options.refresh Force a refresh of the access token.
*/
getAccessToken(req: PagesRouterRequest | NextRequest, res: PagesRouterResponse | NextResponse, options?: GetAccessTokenOptions): Promise<{
token: string;
expiresAt: number;
scope?: string;
}>;
/**
* Retrieves an access token for a connection.
*
* This method can be used in Server Components, Server Actions, and Route Handlers in the **App Router**.
*
* NOTE: Server Components cannot set cookies. Calling `getAccessTokenForConnection()` in a Server Component will cause the access token to be refreshed, if it is expired, and the updated token set will not to be persisted.
* It is recommended to call `getAccessTokenForConnection(req, res)` in the middleware if you need to retrieve the access token in a Server Component to ensure the updated token set is persisted.
*/
getAccessTokenForConnection(options: AccessTokenForConnectionOptions): Promise<{
token: string;
expiresAt: number;
}>;
/**
* Retrieves an access token for a connection.
*
* This method can be used in middleware and `getServerSideProps`, API routes in the **Pages Router**.
*/
getAccessTokenForConnection(options: AccessTokenForConnectionOptions, req: PagesRouterRequest | NextRequest | undefined, res: PagesRouterResponse | NextResponse | undefined): Promise<{
token: string;
expiresAt: number;
}>;
/**
* updateSession updates the session of the currently authenticated user. If the user does not have a session, an error is thrown.
*
* This method can be used in middleware and `getServerSideProps`, API routes, and middleware in the **Pages Router**.
*/
updateSession(req: PagesRouterRequest | NextRequest, res: PagesRouterResponse | NextResponse, session: SessionData): Promise<void>;
/**
* updateSession updates the session of the currently authenticated user. If the user does not have a session, an error is thrown.
*
* This method can be used in Server Actions and Route Handlers in the **App Router**.
*/
updateSession(session: SessionData): Promise<void>;
private createRequestCookies;
startInteractiveLogin(options?: StartInteractiveLoginOptions): Promise<NextResponse>;
/**
* Authenticates using Client-Initiated Backchannel Authentication and returns the token set and optionally the ID token claims and authorization details.
*
* This method will initialize the backchannel authentication process with Auth0, and poll the token endpoint until the authentication is complete.
*
* Using Client-Initiated Backchannel Authentication requires the feature to be enabled in the Auth0 dashboard.
* @see https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow
*/
getTokenByBackchannelAuth(options: BackchannelAuthenticationOptions): Promise<import("../types/index.js").BackchannelAuthenticationResponse>;
withPageAuthRequired(fnOrOpts?: WithPageAuthRequiredPageRouterOptions | AppRouterPageRoute, opts?: WithPageAuthRequiredAppRouterOptions): AppRouterPageRoute | import("./helpers/with-page-auth-required.js").PageRoute<{
[key: string]: any;
}, import("querystring").ParsedUrlQuery>;
withApiAuthRequired(apiRoute: withApiAuthRequired.AppRouteHandlerFn | NextApiHandler): (req: NextRequest | NextApiRequest, resOrParams: withApiAuthRequired.AppRouteHandlerFnContext | NextApiResponse) => unknown;
private saveToSession;
/**
* Validates and extracts required configuration options.
* @param options The client options
* @returns The validated required options
* @throws ConfigurationError if any required option is missing
*/
private validateAndExtractRequiredOptions;
}
export type GetAccessTokenOptions = {
refresh?: boolean;
};