Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

invalid_client

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

Client authentication failed at an endpoint that authenticates the client (RFC 6749 §5.2).

Meaning

Sent with 401 and a WWW-Authenticate: Basic challenge by /token, /introspect, /revoke, /par and /device_authorization. The causes are an unknown client_id, a missing or wrong secret, a credential of another method than the one registered, a secret for a client that has none, and a private_key_jwt assertion that fails a check (its algorithm, kid, signature, iss/sub, aud, exp or lifetime, a reused jti, or a key set that cannot be fetched or holds a private key, whether it is published at a jwks_uri or registered by value as jwks). A public client calling /introspect, and an /introspect or /revoke request with no body, get it too. The answer and its description are the same for every cause, so it never says whether the client exists.

Impact

Every request the client makes with that credential fails. Users can still sign in at the server, but the application cannot redeem the code, so they end on the application's own error after signing in. Usually a misconfiguration: a mistyped or rotated secret, the wrong authentication method, or a key set the server cannot read.

Diagnosis

  1. The response does not say which rule refused the credential; the audit record does. Find oauth.client_authentication.attempted by the request's X-Request-ID on the dashboard's Troubleshooting page, or filter the Audit log by client.
  2. Its cause names the rule: client_unknown, secret_missing, secret_mismatch, secret_not_registered, auth_method_mismatch, auth_method_unsupported, confidential_client_required, jwks_fetch_failed, jwks_private_key_published, or one of the assertion_* causes.
  3. Compare token_endpoint_auth_method in the client's registration (the dashboard's client page, or spec.tokenEndpointAuthMethod on its OIDCClient).

Mitigation

  • As a client developer: authenticate with the registered method and only that one. For private_key_jwt, set iss and sub to the client id, use a fresh jti and a short exp for each request, and sign with a key your jwks_uri publishes or your registered jwks holds.
  • As an operator: if the secret was lost, issue a new one (for an OIDCClient, delete its Secret and the operator rotates it). A jwks_private_key_published cause means the client's signing key is public: treat it as compromised and have the owner replace it.
  • As a user: nothing to do on your side; tell the application's owner.

Escalation

A run of refusals for one client from unfamiliar addresses is someone guessing a secret; handle it as a security incident. If a credential that should verify is refused with a cause that does not fit, open an issue with the request id, the server version and the recorded cause. Never attach the secret or the assertion.

OAuth error runbooks · Generated from internal/runbook/oauth.yaml in nauthera-server.