UNPKG

@auth0/nextjs-auth0

Version:
276 lines (275 loc) 13.4 kB
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; };