OIDC troubleshooting

View as Markdown

Identify the failed endpoint before changing client configuration. Save the HTTP status, protocol error, time, and request correlation information when available. Do not log authorization codes, JWTs, client secrets, IATs, RATs, or callback bodies.

Authorization errors

After the provider validates the callback, authorization errors return to it with error, error_description, state when supplied, and iss. Before acting on that response, validate state and compare iss with the issuer saved for the request. Errors before callback validation return directly as JSON.

Error	Check	Recovery
`invalid_client`	Correct `client_id`; application is active and OIDC is configured.	Correct the registration or enable the application through its authorized OWNER.
`invalid_request`	Exact registered `redirect_uri`, required fields, duplicate parameters, nonce, PKCE, and supported `prompt` combinations.	Correct the request and start a new authorization.
`unsupported_response_type`	The issuer does not support the requested response type.	Select a type listed in discovery and permitted by the client.
`access_denied`	Authorization or current account admission did not succeed.	Review the reported reason and application admission rules. Do not retry silently in a loop.
`unauthorized_client`	Response type and its required grants are enabled for this client.	Have the OWNER review the OIDC ReturnRule.
`invalid_scope`	Requested scopes are supported and permitted for the client.	Reduce scope or update the approved client configuration.
`login_required`	`prompt=none` has no eligible remembered login.	Start interactive authorization when the user is ready.
`consent_required`	Silent authorization needs user consent.	Start interactive authorization to collect consent.
`interaction_required`	Required account data needs browser interaction.	Let the user complete the interactive flow.
`invalid_request_object`	RS256 preference, selected public keys, JWT fields, signature, and time claims.	Correct the signed object and create a fresh request.
`invalid_request_uri`	Registered reference allowance, exact URI, HTTPS access, and document availability.	Correct the reference or use an inline signed object.
`server_error`	Temporary provider failure.	Let the user retry; do not cache the error response.

For form_post, confirm that the callback accepts a cross-site form POST. If your correlation cookie is missing, check SameSite=None; Secure. Reject the callback if you cannot verify its transaction state.

Token exchange and refresh

Send /token requests as application/x-www-form-urlencoded. Use one client authentication method. Preserve the exact callback URI and PKCE verifier from the authorization transaction.

Error	Common causes	Recovery
`invalid_request`	Wrong content type, duplicate fields, or missing form values.	Correct the form; do not repeat credential fields across methods.
`invalid_client`	Wrong secret; mismatched assertion `iss`/`sub`/`aud`; expired or reused assertion; missing or unmatched RP `kid`.	Check the selected authentication and key source. Create a fresh assertion with a fresh `jti`.
`unauthorized_client`	The requested grant is disabled.	Have the OWNER review allowed grants.
`unsupported_grant_type`	The endpoint does not support the supplied grant.	Use `authorization_code` or `refresh_token` as appropriate.
`invalid_grant`	Expired, consumed, or mismatched code; wrong verifier; revoked refresh session; conflicting refresh scopes.	Start a fresh authorization. Do not keep replaying the same code or old refresh token.
`invalid_scope`	Refresh tries to restore a scope removed from the session.	Use a subset of the current granted scopes, or start a new authorization for broader consent.

An authenticated code replay can revoke the corresponding session. Serialize refresh requests and store each returned replacement refresh token. A missing refresh_token after narrowing away offline_access is expected. A missing id_token after narrowing away openid is expected.

Refresh OIDC tokens at /token, not Session /refresh. See refresh rules.

UserInfo and claim state

Send the access token through the Bearer header or the supported form field, using one transport. Query-string tokens and duplicate transports are rejected.

If the endpoint returns invalid_token, check expiry, issuer, client/session authority, and whether the token belongs to this OIDC flow. If an expected claim is absent, check its scope, application policy, and current user grant. An openid-only claim-state request returns an empty claims object.

An ID Token is not an access token for UserInfo. Access tokens use the application’s Session JWKS; ID Tokens and signed UserInfo use the provider JWKS. See token verification.

Registration errors

Result	Check	Recovery
HTTP 400 `invalid_client_metadata`	Metadata types, supported algorithms, scopes/grants, RP public keys, and naming policy.	Correct the JSON; keep it within the IAT’s allowance.
HTTP 400 `invalid_redirect_uri`	URI syntax, application type, approved host placement, and sector document.	Correct the redirects and host approval.
HTTP 401 `invalid_token`	IAT/RAT expiry, revocation, quota, and current organization authority.	Ask the OWNER to review or replace the appropriate credential.
HTTP 403 on registration read/delete	RAT belongs to a different client.	Use that client’s RAT and returned `registration_client_uri`.

If POST /register has an unknown network result, review created clients in With before repeating it. A new request can consume another quota unit.

Ask for support

Include the endpoint, time with timezone, HTTP status, protocol error, and a request identifier if supplied. State the response type, authentication method, and step that failed. Redact secrets and personal data. Use Sudomimus support.