Skip to main content
theAuth can act as a full OpenID Connect identity provider. External apps register as clients and authenticate their users through theAuth using the standard authorization code flow with PKCE, ID tokens, refresh tokens, discovery, and JWKS. This is distinct from using OAuth providers with theAuth. Here, theAuth is the provider.
A client app redirects a user to theAuth, receives an ID token and userinfo, and a second app is notified by back-channel logout.

theAuth as the identity provider for your other apps.

Setup

1

Generate a signing key

Store the private key securely. The corresponding public key is exposed at the JWKS endpoint so clients can verify tokens.
2

Create the module

lib/theauth.ts
The third argument is a GetUserClaimsFn callback. theAuth calls it to build ID tokens and userinfo responses. You control what data is returned per scope.
3

Register a client

The clientSecret is only returned on registration. It is stored hashed. If you lose it, delete and re-register the client.

Configuration options

Authorization code flow

createOidcProviderModule returns a module of methods. It does not register any HTTP routes, so you mount the endpoints in your own server and call the matching method from each handler.
  1. Client redirects the user to your authorization route (the discovery document advertises {issuer}/authorize) with response_type=code, client_id, redirect_uri, scope, and optionally code_challenge + code_challenge_method=S256.
  2. Your app authenticates the user, then calls oidc.authorize({ ...params, userId }) to issue a code.
  3. Client exchanges the code at your token route ({issuer}/token), which calls oidc.exchangeToken(...) and returns access_token, id_token, and refresh_token.
  4. Client can refresh tokens using grant_type=refresh_token. Refresh tokens rotate on each use.
PKCE with S256 is supported. If the authorization request includes a code_challenge, the token request must include the matching code_verifier. Authorization codes are single-use and expire after 10 minutes by default.

Endpoints

The module does not serve these routes. The discovery document returned by getDiscoveryDocument() advertises the following URLs under issuer, and the table shows the module method each route should call: Other module methods: getClient, deleteClient, and validateAccessToken.

OIDC provider logout

end_session_endpoint and back-channel logout.

OAuth overview

Using theAuth as an OAuth client to sign in via other providers.

SSO

Enterprise SSO via SAML 2.0 and OIDC connections.

MCP

OAuth 2.1 authorization server for MCP tool connections.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 13, 2026