Troubleshooting

Troubleshooting

Common integration pitfalls, listed by symptom. Most of them come down to a small wiring detail in the host application rather than a bug in the gem.

The authorization endpoint crashes, or tokens belong to a nonsense "user"

Cause: resource_owner_authenticator returning a truthy non-user value. redirect_to returns its argument, so a callback that ends with redirect_to(new_user_session_url) hands that return value to Doorkeeper as if it were the authenticated user — later surfacing as NoMethodError (e.g. undefined method 'id' for a String) while building the sub claim, or as tokens tied to a bogus resource owner.

Fix: return a falsey value explicitly after redirecting, as shown in Configuration:

resource_owner_authenticator do
  if current_user
    current_user
  else
    redirect_to(new_user_session_url)
    nil
  end
end

unsupported_response_type when requesting id_token or id_token token

Cause: the implicit OIDC flows are not enabled in Doorkeeper.

Fix: add implicit_oidc to grant_flows in config/initializers/doorkeeper.rb (see Configuration). Note that this internal flow name only appears in the Doorkeeper configuration — the discovery document and Dynamic Client Registration advertise and accept the standard implicit grant type name (doorkeeper-openid_connect >= 2.0).

invalid_scope for the openid scope

Cause: the openid scope is not enabled, either globally or for the requesting application.

Fix: add it to optional_scopes (or default_scopes) in the Doorkeeper initializer, or to the application's own scopes attribute. Beware that an application defining its own scopes does not inherit the initializer's scopes — see Scopes. Relatedly, Dynamic Client Registration silently drops requested scopes the server doesn't support (v1.10.4+), so a dynamically registered client can end up without a scope you expected it to have.

The client rejects the ID Token because the nonce is missing or mismatched

Cause: custom Doorkeeper authorization views that don't forward the nonce parameter through the consent form — the parameter never reaches the grant, so the ID Token is issued without the claim, and spec-conforming client libraries reject it.

Fix: add the hidden nonce field to both the authorize and deny forms, as shown in Nonces.

The token response contains no id_token

Cause: on doorkeeper-openid_connect >= 2.0 this is intentional whenever a REQUIRED ID Token claim cannot be sourced (OIDC Core 1.0 §2): a client_credentials token carrying the openid scope has no resource owner for sub; a password-grant token issued with skip_client_authentication_for_password_grant has no application for aud; and a refreshed token whose resource owner was deleted after issuance can no longer resolve sub. Several of these cases produced 500 errors on 1.10.x instead.

Fix: nothing to fix on the server — request the openid scope from a flow that has both an authenticated end-user and a client application.

500 with Doorkeeper::OpenidConnect::Errors::InvalidConfiguration

Cause: issuer or signing_key resolving to nothing. Since v1.10.0 a blank issuer raises instead of silently advertising an empty issuer in the discovery document — the classic trigger is an issuer block relying on an argument that is nil in the discovery context (see the arity notes in Configuration).

Fix: make the issuer block return a value in every context (the arity-3 form receives request for discovery), and configure signing_key.

/.well-known/oauth-authorization-server disagrees with /.well-known/openid-configuration

Cause: on Doorkeeper 6.0+ that path is answered by Doorkeeper's own RFC 8414 metadata route, which shadows the one this gem serves and knows nothing about the OIDC fields.

Fix: doorkeeper-openid_connect >= 2.0 injects the OpenID Connect metadata into Doorkeeper's document via its custom_metadata seam, so the two agree again — see the note in Routes.

See also

• Configuration
• Prompt and Max Age
• Migration from Old Versions