|
| 1 | +# OpenID Connect (OIDC) with ruby-oauth/oauth2 |
| 2 | + |
| 3 | +This document complements the OAuth 2.1 notes already present in the repository by focusing on OpenID Connect (OIDC) 1.0 usage patterns when using this gem as an OAuth 2.0 client library. |
| 4 | + |
| 5 | +Scope of this document |
| 6 | +- Audience: Developers building an OAuth 2.0/OIDC Relying Party (RP, aka client) in Ruby. |
| 7 | +- Non-goals: This gem does not implement an OIDC Provider (OP, aka Authorization Server); for OP/server see other projects (e.g., doorkeeper + oidc extensions). |
| 8 | +- Status: Informational documentation with links to normative specs. The gem intentionally remains protocol-agnostic beyond OAuth 2.0; OIDC specifics (like ID Token validation) must be handled by your application. |
| 9 | + |
| 10 | +Key concepts refresher |
| 11 | +- OAuth 2.0 delegates authorization; it does not define authentication of the end-user. |
| 12 | +- OIDC layers an identity layer on top of OAuth 2.0, introducing: |
| 13 | + - ID Token: a JWT carrying claims about the authenticated end-user and the authentication event. |
| 14 | + - Standardized scopes: openid (mandatory), profile, email, address, phone, offline_access, and others. |
| 15 | + - UserInfo endpoint: a protected resource for retrieving user profile claims. |
| 16 | + - Discovery and Dynamic Client Registration (optional for providers/clients that support them). |
| 17 | + |
| 18 | +What this gem provides for OIDC |
| 19 | +- All OAuth 2.0 client capabilities required for OIDC flows: building authorization requests, exchanging authorization codes, refreshing tokens, and making authenticated resource requests. |
| 20 | +- Transport and parsing conveniences (snaky hash, Faraday integration, error handling, etc.). |
| 21 | +- Optional client authentication schemes useful with OIDC deployments: |
| 22 | + - basic_auth (default) |
| 23 | + - request_body (legacy) |
| 24 | + - tls_client_auth (MTLS) |
| 25 | + - private_key_jwt (OIDC-compliant when configured per OP requirements) |
| 26 | + |
| 27 | +What you must add in your app for OIDC |
| 28 | +- ID Token validation: This gem surfaces id_token values but does not verify them. Your app should: |
| 29 | + 1) Parse the JWT (header, payload, signature) |
| 30 | + 2) Fetch the OP JSON Web Key Set (JWKS) from discovery (or configure statically) |
| 31 | + 3) Select the correct key by kid (when present) and verify the signature and algorithm |
| 32 | + 4) Validate standard claims (iss, aud, exp, iat, nbf, azp, nonce when used, at_hash/c_hash when applicable) |
| 33 | + 5) Enforce expected client_id, issuer, and clock skew policies |
| 34 | +- Nonce handling for Authorization Code flow with OIDC: generate a cryptographically-random nonce, bind it to the user session before redirect, include it in authorize request, and verify it in the ID Token on return. |
| 35 | +- PKCE is best practice and often required by OPs: generate/verifier, send challenge in authorize, send verifier in token request. |
| 36 | +- Session/state management: continue to validate state to mitigate CSRF; use exact redirect_uri matching. |
| 37 | + |
| 38 | +Minimal OIDC Authorization Code example |
| 39 | + |
| 40 | +```ruby |
| 41 | +require "oauth2" |
| 42 | +require "jwt" # jwt/ruby-jwt |
| 43 | +require "net/http" |
| 44 | +require "json" |
| 45 | + |
| 46 | +client = OAuth2::Client.new( |
| 47 | + ENV.fetch("OIDC_CLIENT_ID"), |
| 48 | + ENV.fetch("OIDC_CLIENT_SECRET"), |
| 49 | + site: ENV.fetch("OIDC_ISSUER"), # e.g. https://accounts.example.com |
| 50 | + authorize_url: "/authorize", # or discovered |
| 51 | + token_url: "/token", # or discovered |
| 52 | +) |
| 53 | + |
| 54 | +# Step 1: Redirect to OP for consent/auth |
| 55 | +state = SecureRandom.hex(16) |
| 56 | +nonce = SecureRandom.hex(16) |
| 57 | +pkce_verifier = SecureRandom.urlsafe_base64(64) |
| 58 | +pkce_challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(pkce_verifier)).delete("=") |
| 59 | + |
| 60 | +authz_url = client.auth_code.authorize_url( |
| 61 | + scope: "openid profile email", |
| 62 | + state: state, |
| 63 | + nonce: nonce, |
| 64 | + code_challenge: pkce_challenge, |
| 65 | + code_challenge_method: "S256", |
| 66 | + redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"), |
| 67 | +) |
| 68 | +# redirect_to authz_url |
| 69 | + |
| 70 | +# Step 2: Handle callback |
| 71 | +# params[:code], params[:state] |
| 72 | +raise "state mismatch" unless params[:state] == state |
| 73 | + |
| 74 | +token = client.auth_code.get_token( |
| 75 | + params[:code], |
| 76 | + redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"), |
| 77 | + code_verifier: pkce_verifier, |
| 78 | +) |
| 79 | + |
| 80 | +# The token may include: access_token, id_token, refresh_token, etc. |
| 81 | +id_token = token.params["id_token"] || token.params[:id_token] |
| 82 | + |
| 83 | +# Step 3: Validate the ID Token (simplified – add your own checks!) |
| 84 | +# Discover keys (example using .well-known) |
| 85 | +issuer = ENV.fetch("OIDC_ISSUER") |
| 86 | +jwks_uri = JSON.parse(Net::HTTP.get(URI.join(issuer, "/.well-known/openid-configuration"))). |
| 87 | + fetch("jwks_uri") |
| 88 | +jwks = JSON.parse(Net::HTTP.get(URI(jwks_uri))) |
| 89 | +keys = jwks.fetch("keys") |
| 90 | + |
| 91 | +# Use ruby-jwt JWK loader |
| 92 | +jwk_set = JWT::JWK::Set.new(keys.map { |k| JWT::JWK.import(k) }) |
| 93 | + |
| 94 | +decoded, headers = JWT.decode( |
| 95 | + id_token, |
| 96 | + nil, |
| 97 | + true, |
| 98 | + algorithms: ["RS256", "ES256", "PS256"], |
| 99 | + jwks: jwk_set, |
| 100 | + verify_iss: true, |
| 101 | + iss: issuer, |
| 102 | + verify_aud: true, |
| 103 | + aud: ENV.fetch("OIDC_CLIENT_ID"), |
| 104 | +) |
| 105 | + |
| 106 | +# Verify nonce |
| 107 | +raise "nonce mismatch" unless decoded["nonce"] == nonce |
| 108 | + |
| 109 | +# Optionally: call UserInfo |
| 110 | +userinfo = token.get("/userinfo").parsed |
| 111 | +``` |
| 112 | + |
| 113 | +Notes on discovery and registration |
| 114 | +- Discovery: Most OPs publish configuration at {issuer}/.well-known/openid-configuration (OIDC Discovery 1.0). From there, resolve authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint, etc. |
| 115 | +- Dynamic Client Registration: Some OPs allow registering clients programmatically (OIDC Dynamic Client Registration 1.0). This gem does not implement registration; use a plain HTTP client or Faraday and store credentials securely. |
| 116 | + |
| 117 | +Common pitfalls and tips |
| 118 | +- Always request the openid scope when you expect an ID Token. Without it, the OP may behave as vanilla OAuth 2.0. |
| 119 | +- Validate ID Token signature and claims before trusting any identity data. Do not rely solely on the presence of an id_token field. |
| 120 | +- Prefer Authorization Code + PKCE. Avoid Implicit; it is discouraged in modern guidance and may be disabled by providers. |
| 121 | +- Use exact redirect_uri matching, and keep your allow-list short. |
| 122 | +- For public clients that use refresh tokens, prefer sender-constrained tokens (DPoP/MTLS) or rotation with one-time-use refresh tokens, per modern best practices. |
| 123 | +- When using private_key_jwt, ensure the "aud" (or token_url) and "iss/sub" claims are set per the OP’s rules, and include kid in the JWT header when required so the OP can select the right key. |
| 124 | + |
| 125 | +Relevant specifications and references |
| 126 | +- OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html |
| 127 | +- OIDC Core (final): https://openid.net/specs/openid-connect-core-1_0-final.html |
| 128 | +- How OIDC works: https://openid.net/developers/how-connect-works/ |
| 129 | +- OpenID Connect home: https://openid.net/connect/ |
| 130 | +- OIDC Discovery 1.0: https://openid.net/specs/openid-connect-discovery-1_0.html |
| 131 | +- OIDC Dynamic Client Registration 1.0: https://openid.net/specs/openid-connect-registration-1_0.html |
| 132 | +- OIDC Session Management 1.0: https://openid.net/specs/openid-connect-session-1_0.html |
| 133 | +- OIDC RP-Initiated Logout 1.0: https://openid.net/specs/openid-connect-rpinitiated-1_0.html |
| 134 | +- OIDC Back-Channel Logout 1.0: https://openid.net/specs/openid-connect-backchannel-1_0.html |
| 135 | +- OIDC Front-Channel Logout 1.0: https://openid.net/specs/openid-connect-frontchannel-1_0.html |
| 136 | +- Auth0 OIDC overview: https://auth0.com/docs/authenticate/protocols/openid-connect-protocol |
| 137 | +- Spring Authorization Server’s list of OAuth2/OIDC specs: https://github.com/spring-projects/spring-authorization-server/wiki/OAuth2-and-OIDC-Specifications |
| 138 | + |
| 139 | +See also |
| 140 | +- README sections on OAuth 2.1 notes and OIDC notes |
| 141 | +- Strategy classes under lib/oauth2/strategy for flow helpers |
| 142 | +- Specs under spec/oauth2 for concrete usage patterns |
| 143 | + |
| 144 | +Contributions welcome |
| 145 | +- If you discover provider-specific nuances, consider contributing examples or clarifications (without embedding provider-specific hacks into the library). |
0 commit comments