OAuth Client Authentication#

Overview#

The oauth-provider plugin authenticates clients at the token endpoint (POST /oauth2/token) using one of two methods: HTTP Basic authentication (client_secret_basic) or body parameter authentication (client_secret_post). Both methods are advertised in the server metadata and supported by all three grant types. Public clients (no secret) are optionally supported and must use PKCE instead.

The token endpoint only accepts application/x-www-form-urlencoded requests, per RFC 6749 conventions.

Advertised Auth Methods#

The server's /.well-known/oauth-authorization-server (and OpenID Configuration) document advertises supported methods via authServerMetadata:

none appears in token_endpoint_auth_methods_supported only when allowUnauthenticatedClientRegistration: true is set 1.

Credential Extraction#

In every grant handler, credentials are resolved from the Authorization header first, then fall back to body parameters. The helper basicToClientCredentials handles the HTTP Basic case: it Base64-decodes the header, splits on the first : separator, and returns { client_id, client_secret }. If either value is missing or the format is invalid, it throws invalid_client.

All three grant handlers follow the same pattern 2 3 4:

if (Authorization header starts with "Basic ") → basicToClientCredentials()
else → use client_id / client_secret from body

Core Validation: validateClientCredentials#

All grant handlers delegate to validateClientCredentials after credential extraction. It runs these checks in order:

1. Client lookup — fetches from DB (or in-memory trusted-client cache via getClient); throws invalid_client if not found.
2. Disabled check — throws invalid_client if client.disabled is set 5.
3. Confidential client requires secret — if !client.public && !clientSecret, throws invalid_client 6.
4. Public client rejects secret — if a secret is sent to a public client (no clientSecret stored), throws invalid_client 7.
5. Secret verification — calls verifyStoredClientSecret using constant-time comparison 8.
6. Scope check — validates requested scopes against the client's registered scopes 9.
7. Grant type check — calls clientAllowsGrant to verify the client is registered for the requested grant 10.

Secret Storage & Verification#

Client secrets are stored according to the storeClientSecret option 11:

The default hasher uses SHA-256 with base64url encoding (no padding). All comparisons use constantTimeEqual to prevent timing attacks.

An optional prefix (opts.prefix.clientSecret) is stripped before hashing/comparison; a secret that doesn't start with the configured prefix throws invalid_client immediately 12.

PKCE vs. Secret: Authorization Code Grant#

The authorization_code grant requires either a client_secret or a code_verifier (PKCE) — never neither 13. isPKCERequired determines whether PKCE is mandatory:

• Always required for public clients (tokenEndpointAuthMethod === "none", type === "native" or "user-agent-based", or public === true) 14.
• Always required when offline_access scope is requested 15.
• Required by default for confidential clients unless requirePKCE: false is explicitly set 16.

Only S256 is supported as a PKCE challenge method 17.

When PKCE is used, the token endpoint verifies that PKCE was also used at the authorization endpoint (and vice versa), preventing downgrade attacks 18.

Per-Grant Behavior#

authorization_code#

• Accepts Basic or body credentials 2.
• If confidential: requires client_secret OR code_verifier 19.
• PKCE challenge method must be S256 20.

client_credentials#

• Requires both client_id and client_secret 21.
• OIDC scopes (openid, profile, email, offline_access) are explicitly rejected 22.

refresh_token#

• client_id is always required; client_secret is optional for public clients but required for confidential ones 23 — enforced by validateClientCredentials.
• clientId on the refresh token row must match the requesting client_id, or invalid_client is returned 24.

Key Source Files#