You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: OIDC.md
+10-1Lines changed: 10 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,11 +16,13 @@ If any other libraries would like to be added to this list, please open an issue
16
16
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.
17
17
18
18
Scope of this document
19
+
19
20
- Audience: Developers building an OAuth 2.0/OIDC Relying Party (RP, aka client) in Ruby.
20
21
- 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).
21
22
- 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.
22
23
23
24
Key concepts refresher
25
+
24
26
- OAuth 2.0 delegates authorization; it does not define authentication of the end-user.
25
27
- OIDC layers an identity layer on top of OAuth 2.0, introducing:
26
28
- ID Token: a JWT carrying claims about the authenticated end-user and the authentication event.
@@ -29,6 +31,7 @@ Key concepts refresher
29
31
- Discovery and Dynamic Client Registration (optional for providers/clients that support them).
30
32
31
33
What this gem provides for OIDC
34
+
32
35
- All OAuth 2.0 client capabilities required for OIDC flows: building authorization requests, exchanging authorization codes, refreshing tokens, and making authenticated resource requests.
33
36
- Transport and parsing conveniences (snaky hash, Faraday integration, error handling, etc.).
34
37
- Optional client authentication schemes useful with OIDC deployments:
@@ -38,6 +41,7 @@ What this gem provides for OIDC
38
41
- private_key_jwt (OIDC-compliant when configured per OP requirements)
39
42
40
43
What you must add in your app for OIDC
44
+
41
45
- ID Token validation: This gem surfaces id_token values but does not verify them. Your app should:
42
46
1) Parse the JWT (header, payload, signature)
43
47
2) Fetch the OP JSON Web Key Set (JWKS) from discovery (or configure statically)
- 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.
131
+
132
+
- 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.
128
133
- 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.
129
134
130
135
Common pitfalls and tips
136
+
131
137
- Always request the openid scope when you expect an ID Token. Without it, the OP may behave as vanilla OAuth 2.0.
132
138
- Validate ID Token signature and claims before trusting any identity data. Do not rely solely on the presence of an id_token field.
133
139
- Prefer Authorization Code + PKCE. Avoid Implicit; it is discouraged in modern guidance and may be disabled by providers.
@@ -136,6 +142,7 @@ Common pitfalls and tips
136
142
- 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.
- How OIDC works: https://openid.net/developers/how-connect-works/
@@ -150,9 +157,11 @@ Relevant specifications and references
150
157
- Spring Authorization Server’s list of OAuth2/OIDC specs: https://github.com/spring-projects/spring-authorization-server/wiki/OAuth2-and-OIDC-Specifications
151
158
152
159
See also
160
+
153
161
- README sections on OAuth 2.1 notes and OIDC notes
154
162
- Strategy classes under lib/oauth2/strategy for flow helpers
155
163
- Specs under spec/oauth2 for concrete usage patterns
156
164
157
165
Contributions welcome
166
+
158
167
- If you discover provider-specific nuances, consider contributing examples or clarifications (without embedding provider-specific hacks into the library).
Copy file name to clipboardExpand all lines: README.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -843,8 +843,8 @@ me = long_lived.get("/me", params: {fields: "id,username"}).parsed
843
843
844
844
Tips:
845
845
846
-
- Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for GET.
847
-
- If you need a custom rule, you can pass a Proc for mode, e.g. mode: ->(verb) { verb == :get ? :query : :header }.
846
+
- Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for `GET` requests.
847
+
- If you need a custom rule, you can pass a `Proc` for `mode`, e.g. `mode: ->(verb) { verb == :get ? :query : :header }`.
848
848
849
849
### Refresh Tokens
850
850
@@ -991,9 +991,9 @@ client = OAuth2::Client.new(
991
991
end
992
992
```
993
993
994
-
##### Using flat query params (Faraday::FlatParamsEncoder)
994
+
##### Using flat query params (`Faraday::FlatParamsEncoder`)
995
995
996
-
Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides FlatParamsEncoder for this purpose. You can configure the oauth2 client to use it when building requests.
996
+
Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides `FlatParamsEncoder` for this purpose. You can configure the oauth2 client to use it when building requests.
0 commit comments