1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: OIDC
— Documentation by YARD 0.9.37
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" />
<link rel="stylesheet" href="css/common.css" type="text/css" />
<script type="text/javascript">
pathId = "OIDC";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="file_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: OIDC</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h1 id="openid-connect-oidc-with-ruby-oauthoauth2">OpenID Connect (OIDC) with ruby-oauth/oauth2</h1>
<h2 id="oidc-libraries">OIDC Libraries</h2>
<p>Libraries built on top of the oauth2 gem that implement OIDC.</p>
<ul>
<li>
<a href="https://github.com/amco/gamora-rb">gamora</a> - OpenID Connect Relying Party for Rails apps</li>
<li>
<a href="https://github.com/doximity/omniauth-doximity-oauth2">omniauth-doximity-oauth2</a> - OmniAuth strategy for Doximity, supporting OIDC, and using PKCE</li>
<li>
<a href="https://github.com/sorah/himari">omniauth-himari</a> - OmniAuth strategy to act as OIDC RP and use <a href="https://github.com/sorah/himari">Himari</a> for OP</li>
<li>
<a href="https://github.com/MITLibraries/omniauth-mit-oauth2">omniauth-mit-oauth2</a> - OmniAuth strategy for MIT OIDC</li>
</ul>
<p>If any other libraries would like to be added to this list, please open an issue or pull request.</p>
<h2 id="raw-oidc-with-ruby-oauthoauth2">Raw OIDC with ruby-oauth/oauth2</h2>
<p>This document complements the inline documentation by focusing on OpenID Connect (OIDC) 1.0 usage patterns when using this gem as an OAuth 2.0 client library.</p>
<p>Scope of this document</p>
<ul>
<li>Audience: Developers building an OAuth 2.0/OIDC Relying Party (RP, aka client) in Ruby.</li>
<li>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).</li>
<li>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.</li>
</ul>
<p>Key concepts refresher</p>
<ul>
<li>OAuth 2.0 delegates authorization; it does not define authentication of the end-user.</li>
<li>OIDC layers an identity layer on top of OAuth 2.0, introducing:
<ul>
<li>ID Token: a JWT carrying claims about the authenticated end-user and the authentication event.</li>
<li>Standardized scopes: openid (mandatory), profile, email, address, phone, offline_access, and others.</li>
<li>UserInfo endpoint: a protected resource for retrieving user profile claims.</li>
<li>Discovery and Dynamic Client Registration (optional for providers/clients that support them).</li>
</ul>
</li>
</ul>
<p>What this gem provides for OIDC</p>
<ul>
<li>All OAuth 2.0 client capabilities required for OIDC flows: building authorization requests, exchanging authorization codes, refreshing tokens, and making authenticated resource requests.</li>
<li>Transport and parsing conveniences (snaky hash, Faraday integration, error handling, etc.).</li>
<li>Optional client authentication schemes useful with OIDC deployments:
<ul>
<li>basic_auth (default)</li>
<li>request_body (legacy)</li>
<li>tls_client_auth (MTLS)</li>
<li>private_key_jwt (OIDC-compliant when configured per OP requirements)</li>
</ul>
</li>
</ul>
<p>What you must add in your app for OIDC</p>
<ul>
<li>ID Token validation: This gem surfaces id_token values but does not verify them. Your app should:<br>
1) Parse the JWT (header, payload, signature)<br>
2) Fetch the OP JSON Web Key Set (JWKS) from discovery (or configure statically)<br>
3) Select the correct key by kid (when present) and verify the signature and algorithm<br>
4) Validate standard claims (iss, aud, exp, iat, nbf, azp, nonce when used, at_hash/c_hash when applicable)<br>
5) Enforce expected client_id, issuer, and clock skew policies</li>
<li>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.</li>
<li>PKCE is best practice and often required by OPs: generate/verifier, send challenge in authorize, send verifier in token request.</li>
<li>Session/state management: continue to validate state to mitigate CSRF; use exact redirect_uri matching.</li>
</ul>
<p>Minimal OIDC Authorization Code example</p>
<pre class="code language-ruby"><code class="language-ruby">require "oauth2"
require "jwt" # jwt/ruby-jwt
require "net/http"
require "json"
client = OAuth2::Client.new(
ENV.fetch("OIDC_CLIENT_ID"),
ENV.fetch("OIDC_CLIENT_SECRET"),
site: ENV.fetch("OIDC_ISSUER"), # e.g. https://accounts.example.com
authorize_url: "/authorize", # or discovered
token_url: "/token", # or discovered
)
# Step 1: Redirect to OP for consent/auth
state = SecureRandom.hex(16)
nonce = SecureRandom.hex(16)
pkce_verifier = SecureRandom.urlsafe_base64(64)
pkce_challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(pkce_verifier)).delete("=")
authz_url = client.auth_code.authorize_url(
scope: "openid profile email",
state: state,
nonce: nonce,
code_challenge: pkce_challenge,
code_challenge_method: "S256",
redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"),
)
# redirect_to authz_url
# Step 2: Handle callback
# params[:code], params[:state]
raise "state mismatch" unless params[:state] == state
token = client.auth_code.get_token(
params[:code],
redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"),
code_verifier: pkce_verifier,
)
# The token may include: access_token, id_token, refresh_token, etc.
id_token = token.params["id_token"] || token.params[:id_token]
# Step 3: Validate the ID Token (simplified – add your own checks!)
# Discover keys (example using .well-known)
issuer = ENV.fetch("OIDC_ISSUER")
jwks_uri = JSON.parse(Net::HTTP.get(URI.join(issuer, "/.well-known/openid-configuration"))).
fetch("jwks_uri")
jwks = JSON.parse(Net::HTTP.get(URI(jwks_uri)))
keys = jwks.fetch("keys")
# Use ruby-jwt JWK loader
jwk_set = JWT::JWK::Set.new(keys.map { |k| JWT::JWK.import(k) })
decoded, headers = JWT.decode(
id_token,
nil,
true,
algorithms: ["RS256", "ES256", "PS256"],
jwks: jwk_set,
verify_iss: true,
iss: issuer,
verify_aud: true,
aud: ENV.fetch("OIDC_CLIENT_ID"),
)
# Verify nonce
raise "nonce mismatch" unless decoded["nonce"] == nonce
# Optionally: call UserInfo
userinfo = token.get("/userinfo").parsed
</code></pre>
<p>Notes on discovery and registration</p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
<p>Common pitfalls and tips</p>
<ul>
<li>Always request the openid scope when you expect an ID Token. Without it, the OP may behave as vanilla OAuth 2.0.</li>
<li>Validate ID Token signature and claims before trusting any identity data. Do not rely solely on the presence of an id_token field.</li>
<li>Prefer Authorization Code + PKCE. Avoid Implicit; it is discouraged in modern guidance and may be disabled by providers.</li>
<li>Use exact redirect_uri matching, and keep your allow-list short.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>Relevant specifications and references</p>
<ul>
<li>OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html</li>
<li>OIDC Core (final): https://openid.net/specs/openid-connect-core-1_0-final.html</li>
<li>How OIDC works: https://openid.net/developers/how-connect-works/</li>
<li>OpenID Connect home: https://openid.net/connect/</li>
<li>OIDC Discovery 1.0: https://openid.net/specs/openid-connect-discovery-1_0.html</li>
<li>OIDC Dynamic Client Registration 1.0: https://openid.net/specs/openid-connect-registration-1_0.html</li>
<li>OIDC Session Management 1.0: https://openid.net/specs/openid-connect-session-1_0.html</li>
<li>OIDC RP-Initiated Logout 1.0: https://openid.net/specs/openid-connect-rpinitiated-1_0.html</li>
<li>OIDC Back-Channel Logout 1.0: https://openid.net/specs/openid-connect-backchannel-1_0.html</li>
<li>OIDC Front-Channel Logout 1.0: https://openid.net/specs/openid-connect-frontchannel-1_0.html</li>
<li>Auth0 OIDC overview: https://auth0.com/docs/authenticate/protocols/openid-connect-protocol</li>
<li>Spring Authorization Server’s list of OAuth2/OIDC specs: https://github.com/spring-projects/spring-authorization-server/wiki/OAuth2-and-OIDC-Specifications</li>
</ul>
<p>See also</p>
<ul>
<li>README sections on OAuth 2.1 notes and OIDC notes</li>
<li>Strategy classes under lib/oauth2/strategy for flow helpers</li>
<li>Specs under spec/oauth2 for concrete usage patterns</li>
</ul>
<p>Contributions welcome</p>
<ul>
<li>If you discover provider-specific nuances, consider contributing examples or clarifications (without embedding provider-specific hacks into the library).</li>
</ul>
</div></div>
<div id="footer">
Generated on Mon Sep 15 21:28:40 2025 by
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.37 (ruby-3.4.5).
</div>
</div>
</body>
</html>
|
