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
`if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know][🖼️galtzo-discord], as I may have missed the [discord notification][🖼️galtzo-discord].
@@ -31,10 +29,10 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
31
29
## 🌻 Synopsis
32
30
33
31
OAuth 2.0 is the industry-standard protocol for authorization.
34
-
OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications,
35
-
desktop applications, mobile phones, and living room devices.
36
32
This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.
37
33
34
+
⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC)
35
+
38
36
### Quick Examples
39
37
40
38
<detailsmarkdown="1">
@@ -53,13 +51,14 @@ curl --request POST \
53
51
NOTE: In the ruby version below, certain params are passed to the `get_token` call, instead of the client creation.
54
52
55
53
```ruby
56
-
OAuth2::Client.new(
54
+
client =OAuth2::Client.new(
57
55
"REDMOND_CLIENT_ID", # client_id
58
56
"REDMOND_CLIENT_SECRET", # client_secret
59
57
auth_scheme::request_body, # Other modes are supported: :basic_auth, :tls_client_auth, :private_key_jwt
60
58
token_url:"oauth2/token", # relative path, except with leading `/`, then absolute path
The "extra tokens" problem comes from ambiguity in the spec about which token is the right token.
338
-
Some OAuth 2.0 standards legitimately have multiple tokens.
339
-
You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in.
340
-
Specify your custom class with the `access_token_class` option.
333
+
## 🔧 Basic Usage
341
334
342
-
If you only need one token, you can, as of v2.0.10,
343
-
specify the exact token name you want to extract via the `OAuth2::AccessToken` using
344
-
the `token_name` option.
335
+
### Client Initialization Options
345
336
346
-
You'll likely need to do some source diving.
347
-
This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas.
348
-
If you have time and energy, please contribute to the documentation!
337
+
`OAuth2::Client.new` accepts several options:
349
338
350
-
## 🔧 Basic Usage
339
+
-`:site`: The base URL for the OAuth 2.0 provider.
340
+
-`:authorize_url`: The authorization endpoint (default: `"oauth/authorize"`).
341
+
-`:token_url`: The token endpoint (default: `"oauth/token"`).
342
+
-`:auth_scheme`: The authentication scheme (`:basic_auth`, `:request_body`, `:tls_client_auth`, `:private_key_jwt`). Default is `:basic_auth`.
343
+
-`:connection_opts`: Options for the underlying Faraday connection (timeouts, proxy, etc.).
344
+
-`:raise_errors`: Whether to raise `OAuth2::Error` on 400+ responses (default: `true`).
345
+
346
+
<detailsmarkdown="1">
347
+
<summary><em>authorize_url</em> and <em>token_url</em></summary>
351
348
352
349
### `authorize_url` and `token_url` are on site root (Just Works!)
353
350
@@ -394,6 +391,25 @@ client.class.name
394
391
# => OAuth2::Client
395
392
```
396
393
394
+
</details>
395
+
396
+
### Advanced Initializers
397
+
398
+
```ruby
399
+
client =OAuth2::Client.new(id, secret, site: site) do |faraday|
400
+
faraday.request(:url_encoded)
401
+
faraday.adapter(:net_http_persistent)
402
+
end
403
+
```
404
+
405
+
### AccessToken Features
406
+
407
+
Instances of `OAuth2::AccessToken` handle request signing and token expiration.
408
+
409
+
-**Snake Case & Indifferent Access**: `response.parsed` returns a `SnakyHash` allowing access via string/symbol and snake_case keys even if the provider returns CamelCase.
410
+
-**Auto-Refresh**: You can manually check `token.expired?` and call `token.refresh`.
411
+
-**Serialization**: Persist tokens using `token.to_hash` and restore via `OAuth2::AccessToken.from_hash(client, hash)`.
412
+
397
413
### snake_case and indifferent access in Response#parsed
The `AccessToken` methods `#get`, `#post`, `#put` and `#delete` and the generic `#request`
549
-
will return an instance of the #OAuth2::Response class.
565
+
will return an instance of the `OAuth2::Response` class.
550
566
551
567
This instance contains a `#parsed` method that will parse the response body and
552
568
return a Hash-like [`SnakyHash::StringKeyed`](https://gitlab.com/ruby-oauth/snaky_hash/-/blob/main/lib/snaky_hash/string_keyed.rb) if the `Content-Type` is `application/x-www-form-urlencoded` or if
553
-
the body is a JSON object. It will return an Array if the body is a JSON
554
-
array. Otherwise, it will return the original body string.
569
+
the body is a JSON object. It will return an Array if the body is a JSON
570
+
array. Otherwise, it will return the original body string.
555
571
556
572
The original response body, headers, and status can be accessed via their
557
573
respective methods.
@@ -593,16 +609,22 @@ Response instance will contain the `OAuth2::Error` instance.
593
609
594
610
### Authorization Grants
595
611
596
-
Note on OAuth 2.1 (draft):
612
+
Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
613
+
authentication grant types have helper strategy classes that simplify client
614
+
use. They are available via the [`#auth_code`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/auth_code.rb),
- PKCE is required for all OAuth clients using the authorization code flow (especially public clients). Implement PKCE in your app when required by your provider. See RFC 7636 and RFC 8252.
599
-
- Redirect URIs must be compared using exact string matching by the Authorization Server.
600
-
- The Implicit grant (response_type=token) and the Resource Owner Password Credentials grant are omitted from OAuth 2.1; they remain here for OAuth 2.0 compatibility but should be avoided for new apps.
601
-
- Bearer tokens in the query string are omitted due to security risks; prefer Authorization header usage.
602
-
- Refresh tokens for public clients must either be sender-constrained (e.g., DPoP/MTLS) or one-time use.
603
-
- The definitions of public and confidential clients are simplified to refer only to whether the client has credentials.
620
+
#### OAuth 2.1 (draft) Note:
604
621
605
-
References:
622
+
-**PKCE** is required for all OAuth clients using the authorization code flow (especially public clients). Implement PKCE in your app when required by your provider. See RFC 7636 and RFC 8252.
623
+
-**Implicit grant** (response_type=token) and **Resource Owner Password Credentials grant** are omitted from OAuth 2.1; they remain here for OAuth 2.0 compatibility but should be avoided for new apps.
624
+
-**Redirect URIs** must be compared using exact string matching by the Authorization Server.
- If the token response includes an `id_token` (a JWT), this gem surfaces it but does not validate the signature. Use a JWT library and your provider's JWKs to verify it.
1069
-
- For private_key_jwt client authentication, provide `auth_scheme: :private_key_jwt` and ensure your key configuration matches the provider requirements.
1070
-
- See [OIDC.md](OIDC.md) for a more complete OIDC overview, example, and links to the relevant specifications.
1089
+
- If the token response includes an `id_token` (a JWT), this gem surfaces it in `token.params['id_token']`.
1090
+
-**Note**: This gem does **not** validate the signature of the `id_token`. You must use a JWT library (like the `jwt`[gem](https://github.com/jwt/ruby-jwt)) and your provider's JWKs to verify it.
1091
+
- For `private_key_jwt` client authentication, provide `auth_scheme: :private_key_jwt` and ensure your key configuration matches the provider requirements.
1092
+
- See [OIDC.md](OIDC.md) for a more complete OIDC overview and examples.
1071
1093
1072
1094
### Debugging
1073
1095
@@ -1239,7 +1261,7 @@ See [LICENSE.txt][📄license] for the official [Copyright Notice][📄copyright
0 commit comments