Dynamic client registration

Dynamic client registration (RFC 7591) lets an OAuth client register itself with the OAuth/OIDC provider over HTTP and receive a client_id, instead of an administrator calling registerClient and copying the ID into the app. Use it when clients cannot be registered ahead of time: AI assistants and IDEs that connect to your MCP server (see Dynamic registration and MCP), desktop apps that each install their own client, or partner integrations you onboard with a one-time token.

Registration is off unless you configure registration on createOAuthProvider. When it is on, every registration lands in exactly one tenant, chosen by you, never by the request, and the registered client can never be more powerful than the limits you set.

How it works

The registration endpoint, {issuer}/reg, admits a request in one of two ways:

Anything else answers 401 with error: invalid_token. After registration, the client runs the normal authorization code flow with PKCE; the person sees the registered client_name on your consent screen.

Setup

import { createOAuthProvider } from 'better-iam/oauth';
import { iam } from './iam';
import { tenantForHost } from './tenants';

const keys = JSON.parse(process.env.OIDC_KEYS!); // { jwks, cookieKeys, encryptionKey }

export const issuer = createOAuthProvider({
  ...iam.protocolHost,
  issuer: 'https://identity.example/oidc',
  jwks: keys.jwks,
  cookieKeys: keys.cookieKeys,
  encryptionKey: keys.encryptionKey,
  trustedOrigins: ['https://identity.example'],
  interactionUrl: (uid) => `https://identity.example/interactions/${uid}`,
  renderDevicePage: ({ form }) => `<main>${form}</main>`,
  renderLogoutPage: ({ form }) => `<main>${form}</main>`,
  resourceServers: { 'https://mcp.example.com/mcp': { scopes: ['mcp:tools'] } },
  registration: {
    // Optional. Return a policy to accept a tokenless registration, or undefined to decline it.
    anonymous: ({ headers }) => {
      const tenantId = tenantForHost(String(headers.host ?? ''));
      return tenantId
        ? {
            tenantId,
            scopes: ['openid', 'offline_access', 'mcp:tools'],
            resources: ['https://mcp.example.com/mcp'],
            maxClients: 500,
          }
        : undefined;
    },
  },
});
iam.useProtocol(issuer);

import { issuer } from '../oauth';

const { token, id, expiresAt } = await issuer.createRegistrationToken(adminCredential, {
  tenantId: 'acme',
  name: 'Partner desktop app',
  scopes: ['openid', 'offline_access', 'mcp:tools'],
  resources: ['https://mcp.example.com/mcp'],
  maxClients: 1,
  expiresIn: 86_400,
});
// token is shown once; only its hash is stored. Keep id to revoke it later.

Usage

Register a client

The client posts its metadata as JSON. Public clients send token_endpoint_auth_method: "none":

POST /oidc/reg
Content-Type: application/json
Authorization: Bearer <registration token, omitted for anonymous registration>

{
  "client_name": "Acme Assistant",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none",
  "scope": "openid offline_access mcp:tools"
}

The same request from TypeScript:

export async function register(registrationEndpoint: string, registrationToken?: string) {
  const response = await fetch(registrationEndpoint, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      ...(registrationToken ? { authorization: `Bearer ${registrationToken}` } : {}),
    },
    body: JSON.stringify({
      client_name: 'Acme Assistant',
      redirect_uris: ['http://127.0.0.1:33418/callback'],
      grant_types: ['authorization_code', 'refresh_token'],
      token_endpoint_auth_method: 'none',
      scope: 'openid offline_access mcp:tools',
    }),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`Registration failed: ${body.error} ${body.error_description ?? ''}`);
  return body as { client_id: string; client_secret?: string; scope: string; redirect_uris: string[] };
}

Endpoint: POST {issuer}/reg

The response is 201 with the registered metadata and the new client_id; a confidential client (allowed only with allowConfidential) also receives client_secret once. No registration_access_token or registration_client_uri is returned: clients cannot read, change, or delete their own registration (RFC 7592 is not offered).

What a registration may contain

These limits keep a self-registered client from being more powerful than a hand-registered one:

The provider assigns the client_id. Each registration is audited as iam:oauth:RegisterClient, with the token's creator as actor (or dynamic-registration for anonymous registrations).

List and revoke registration tokens

import { issuer } from '../oauth';

const tokens = await issuer.listRegistrationTokens(adminCredential, { tenantId: 'acme' });
// [{ id, name, scopes, resources, allowConfidential, maxClients, used, createdBy, createdAt, expiresAt, revoked }]

await issuer.revokeRegistrationToken(adminCredential, { tenantId: 'acme', tokenId: tokens[0]!.id });

A token stops working when it is revoked, expires, or has registered maxClients clients. Creating and revoking tokens is audited as iam:oauth:CreateRegistrationToken and iam:oauth:RevokeRegistrationToken.

Manage registered clients

Registered clients are ordinary clients of the tenant. They appear in issuer.listClients with registeredVia set to the registration token's ID or anonymous. Change them with updateClient, retire them with revokeClient, and people disconnect them from a connected-apps page with revokeGrant, as described in Manage clients.

Endpoints

The registration path is matched the way the provider's router matches it: case-insensitively, with or without a trailing slash, and after percent-decoding.

Options

registration on createOAuthProvider:

RegistrationPolicy, returned by the hook and stored by each registration token:

createRegistrationToken also takes name (required, up to 200 characters) and expiresIn in seconds (default 604,800, which is 7 days; between 60 and one year).

Schema

The token value itself is never stored.

Errors

The registration endpoint answers with OAuth errors:

The administration methods throw Better IAM errors:

Related