diff --git a/.rubocop.yml b/.rubocop.yml
index 6d11146f..ec6a3fb2 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -19,6 +19,7 @@ inherit_mode:
AllCops:
DisplayCopNames: true # Display the name of the failing cops
Exclude:
+ - 'bin/*'
- 'gemfiles/vendor/**/*'
- 'vendor/**/*'
- '**/.irbrc'
diff --git a/.rubocop_gradual.lock b/.rubocop_gradual.lock
deleted file mode 100644
index e11e08c0..00000000
--- a/.rubocop_gradual.lock
+++ /dev/null
@@ -1,27 +0,0 @@
-{
- "bin/bundle:872096170": [
- [66, 5, 20, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 2485198147]
- ],
- "lib/oauth2.rb:3283430588": [
- [57, 7, 7, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 651502127]
- ],
- "lib/oauth2/filtered_attributes.rb:3925029601": [
- [13, 5, 63, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 2901108034]
- ],
- "spec/oauth2/client_spec.rb:1785648507": [
- [207, 15, 20, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 2320605227],
- [222, 15, 20, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1276531672],
- [237, 15, 43, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1383956904],
- [252, 15, 43, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 3376202107],
- [1175, 17, 12, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 664794325]
- ],
- "spec/oauth2/error_spec.rb:1692696277": [
- [93, 11, 460, "RSpec/NoExpectationExample: No expectation found in this example.", 3630511675],
- [108, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233],
- [240, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910],
- [256, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233],
- [314, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910],
- [375, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910],
- [391, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233]
- ]
-}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01e26c92..961b1e91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,8 +20,14 @@ Please file a bug if you notice a violation of semantic versioning.
### Added
+- [gh!707][gh!707] Add `OAuth2.config[:filtered_label]` to configure the placeholder used for filtered sensitive values in inspected objects and debug logging output by @pboling
+- [gh!707][gh!707] Add `OAuth2.config[:filtered_debug_keys]` to configure which key names have their values redacted from debug logging output by @pboling
+- [gh!707][gh!707] Add `OAuth2::ThingFilter` as the shared filtering primitive used by inspect-time and debug-log filtering by @pboling
+
### Changed
+- [gh!707][gh!707] Make inspect-time and debug-log filters snapshot their configuration at initialization time rather than tracking later config changes by @pboling
+
### Deprecated
### Removed
@@ -30,6 +36,11 @@ Please file a bug if you notice a violation of semantic versioning.
### Security
+- [gh!707][gh!707] Redact sensitive values from debug logging output, including Authorization headers and common token/secret fields in headers, query strings, form bodies, and JSON payloads by @pboling
+ - NOTE: debug logging has always been, and remains, opt-in. It is turned off by defualt.
+
+[gh!707]: https://github.com/ruby-oauth/oauth2/pull/707
+
## [2.0.18] - 2025-11-08
- TAG: [v2.0.18][2.0.18t]
@@ -54,8 +65,6 @@ Please file a bug if you notice a violation of semantic versioning.
- [gh!690][gh!690], [gh!691][gh!691], [gh!692][gh!692] - Add yard-fence
- handle braces within code fences in markdown properly by @pboling
-### Security
-
[gh!683]: https://github.com/ruby-oauth/oauth2/pull/683
[gh!684]: https://github.com/ruby-oauth/oauth2/pull/684
[gh!685]: https://github.com/ruby-oauth/oauth2/pull/685
@@ -196,8 +205,6 @@ Please file a bug if you notice a violation of semantic versioning.
- [gh!660][gh!660] - Links in README (including link to HEAD documentation) by @pboling
-### Security
-
[gh!660]: https://github.com/ruby-oauth/oauth2/pull/660
[gh!657]: https://github.com/ruby-oauth/oauth2/pull/657
[gh!656]: https://github.com/ruby-oauth/oauth2/pull/656
diff --git a/README.md b/README.md
index 588a6f16..68486327 100644
--- a/README.md
+++ b/README.md
@@ -330,6 +330,19 @@ OAuth2.configure do |config|
end
```
+Filtering-related settings:
+
+```ruby
+OAuth2.configure do |config|
+ config.filtered_label = "[REDACTED]" # default: "[FILTERED]"
+ config.filtered_debug_keys += ["client_assertion"]
+end
+```
+
+- `filtered_label` controls the placeholder used when sensitive values are filtered from inspected objects and debug logging output.
+- `filtered_debug_keys` controls which key names have their values redacted from debug logging output when `OAUTH_DEBUG=true`.
+- Debug logging remains opt-in and should still be used cautiously in production environments.
+
## 🔧 Basic Usage
### Client Initialization Options
diff --git a/docs/OAuth2.html b/docs/OAuth2.html
index db795699..e69de29b 100644
--- a/docs/OAuth2.html
+++ b/docs/OAuth2.html
@@ -1,383 +0,0 @@
-
-
-
-
-
-
- Module: OAuth2
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
When true, enables verbose HTTP logging via Faraday’s logger middleware.
-Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive
-value equal to “true” will enable debugging.
# File 'lib/oauth2/client.rb', line 208
-
-defget_token(params,access_token_opts={},extract_access_token=nil,&block)
- warn("OAuth2::Client#get_token argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class` on #initialize.")ifextract_access_token
- extract_access_token||=options[:extract_access_token]
- req_opts=params_to_req_opts(params)
- response=request(http_method,token_url,req_opts,&block)
-
- # In v1.4.x, the deprecated extract_access_token option retrieves the token from the response.
-# We preserve this behavior here, but a custom access_token_class that implements #from_hash
-# should be used instead.
-ifextract_access_token
- parse_response_legacy(response,access_token_opts,extract_access_token)
- else
- parse_response(response,access_token_opts)
- end
-end
# File 'lib/oauth2/client.rb', line 294
-
-defpassword
- @password||=OAuth2::Strategy::Password.new(self)
-end
-
-
-
-
-
-
-
-
- #redirection_params ⇒ Hash
-
-
-
-
-
-
-
-
The redirect_uri parameters, if configured
-
-
The redirect_uri query parameter is OPTIONAL (though encouraged) when
-requesting authorization. If it is provided at authorization time it MUST
-also be provided with the token exchange request.
-
-
OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching.
-This client simply forwards the configured redirect_uri; the exact-match validation happens server-side.
-
-
Providing :redirect_uri to the OAuth2::Client instantiation will take
-care of managing this.
Makes a request relative to the specified site root.
-
-
Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616),
- allowing the use of relative URLs in Location headers.
If the token passed to the request
-is an access token, the server MAY revoke the respective refresh
-token as well.
-
-
-
-
- Note:
-
If the token passed to the request
-is a refresh token and the authorization server supports the
-revocation of access tokens, then the authorization server SHOULD
-also invalidate all access tokens based on the same authorization
-grant
-
-
-
-
- Note:
-
If the server responds with HTTP status code 503, your code must
-assume the token still exists and may retry after a reasonable delay.
-The server may include a “Retry-After” header in the response to
-indicate how long the service is expected to be unavailable to the
-requesting client.
-
-
-
-
Makes a request to revoke a token at the authorization server
Mixin that redacts sensitive instance variables in #inspect output.
-
-
Classes include this module and declare which attributes should be filtered
-using filtered_attributes. Any instance variable name that includes one of
-those attribute names will be shown as [FILTERED] in the object’s inspect.
The parser can be supplied as the +:parse+ option in the form of a Proc
-(or other Object responding to #call) or a Symbol. In the latter case,
-the actual parser will be looked up in @@parsers by the supplied Symbol.
-
-
-
-
- Note:
-
If no +:parse+ option is supplied, the lookup Symbol will be determined
-by looking up #content_type in @@content_types.
-
-
-
-
- Note:
-
If #parser is a Proc, it will be called with no arguments, just
-#body, or #body and #response, depending on the Proc’s arity.
-
-
-
-
Determines the parser to be used for the response body
access = client.assertion.get_token(claim_set, encoding)
- access.token # actual access_token string
- access.get(“/api/stuff”) # making api calls with access token in header
# File 'lib/oauth2/strategy/assertion.rb', line 36
-
-defauthorize_url
- raise(NotImplementedError,"The authorization endpoint is not used in this strategy")
-end
Retrieve an access token given the specified client.
-
-
For reading on JWT and claim keys:
- @see https://github.com/jwt/ruby-jwt
- @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
- @see https://datatracker.ietf.org/doc/html/rfc7523#section-3
- @see https://www.iana.org/assignments/jwt/jwt.xhtml
-
-
There are many possible claim keys, and applications may ask for their own custom keys.
-Some typically required ones:
- :iss (issuer)
- :aud (audience)
- :sub (subject) – formerly :prn https://datatracker.ietf.org/doc/html/draft-ietf-oauth-json-web-token-06#appendix-F
- :exp, (expiration time) – in seconds, e.g. Time.now.utc.to_i + 3600
-
-
Note that this method does not validate presence of those four claim keys indicated as required by RFC 7523.
-There are endpoints that may not conform with this RFC, and this gem should still work for those use cases.
-
-
These two options are passed directly to JWT.encode. For supported encoding arguments:
- @see https://github.com/jwt/ruby-jwt#algorithms-and-usage
- @see https://datatracker.ietf.org/doc/html/rfc7518#section-3.1
-
-
The object type of :key may depend on the value of :algorithm. Sample arguments:
- get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})
- get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})
-
-
-
-
-
-
Parameters:
-
-
-
-
- claims
-
-
- (Hash)
-
-
-
- —
-
the hash representation of the claims that should be encoded as a JWT (JSON Web Token)
-
-
-
-
-
-
- encoding_opts
-
-
- (Hash)
-
-
-
- —
-
a hash containing instructions on how the JWT should be encoded
PKCE is required for all OAuth clients using the authorization code flow (especially public clients).
-This library does not enforce PKCE generation/verification; implement PKCE in your application when required.
-
Redirect URIs must be compared using exact string matching by the Authorization Server.
-This client forwards redirect_uri but does not perform server-side validation.
# File 'lib/oauth2/strategy/client_credentials.rb', line 12
-
-defauthorize_url
- raise(NotImplementedError,"The authorization endpoint is not used in this strategy")
-end
IMPORTANT (OAuth 2.1): The Implicit grant (response_type=token) is omitted from the OAuth 2.1 draft specification.
-It remains here for backward compatibility with OAuth 2.0 providers. Prefer the Authorization Code flow with PKCE.
# File 'lib/oauth2/strategy/implicit.rb', line 35
-
-defget_token(*)
- raise(NotImplementedError,"The token is accessed differently in this strategy")
-end
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html
index 819e0946..e69de29b 100644
--- a/docs/OAuth2/Strategy/Password.html
+++ b/docs/OAuth2/Strategy/Password.html
@@ -1,384 +0,0 @@
-
-
-
-
-
-
- Class: OAuth2::Strategy::Password
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
The Resource Owner Password Credentials Authorization Strategy
-
-
IMPORTANT (OAuth 2.1): The Resource Owner Password Credentials grant is omitted in OAuth 2.1.
-It remains here for backward compatibility with OAuth 2.0 providers. Prefer Authorization Code + PKCE.
# File 'lib/oauth2/strategy/password.rb', line 20
-
-defauthorize_url
- raise(NotImplementedError,"The authorization endpoint is not used in this strategy")
-end
All notable changes to this project will be documented in this file.
-
-
The format is based on Keep a Changelog,
-and this project adheres to Semantic Versioning,
-and yes, platform and engine support are part of the public API.
-Please file a bug if you notice a violation of semantic versioning.
BRANCH COVERAGE: 100.00% – 174/174 branches in 14 files
-
90.48% documented
-
-
-
Added
-
-
-
improved documentation by @pboling
-
-gh!665 - Document Mutual TLS (mTLS) usage with example in README (connection_opts.ssl client_cert/client_key and auth_scheme: :tls_client_auth) by @pboling
-
-gh!666 - Document usage of flat query params using Faraday::FlatParamsEncoder, with example URI, in README by @pboling
-
-
Spec: verify flat params are preserved with Faraday::FlatParamsEncoder (skips on Faraday without FlatParamsEncoder)
-
-
-
-gh!662 - documentation notes in code comments and README highlighting OAuth 2.1 differences, with references, by @pboling
-
-
PKCE required for auth code,
-
exact redirect URI match,
-
implicit/password grants omitted,
-
avoid bearer tokens in query,
-
refresh token guidance for public clients,
-
simplified client definitions
-
-
-
-gh!663 - document how to implement an OIDC client with this gem in OIDC.md by @pboling
-
-
also, list libraries built on top of the oauth2 gem that implement OIDC
-
-
-
-gh!664 - README: Add example for JHipster UAA (Spring Cloud) password grant, converted from Postman/Net::HTTP by @pboling
All data in responses is now returned, with the access token removed and set as token
-
-
-refresh_token is no longer dropped
-
-BREAKING: Microsoft’s id_token is no longer left as access_token['id_token'], but moved to the standard access_token.token that all other strategies use
-
-
-
Remove parse and snaky from options so they don’t get included in response
-
There is now 100% test coverage, for lines and branches, and it will stay that way.
-!362 - Support SemVer release version scheme (@pboling)
-
-!363 - New method OAuth2::AccessToken#refresh! same as old refresh, with backwards compatibility alias (@pboling)
-
-!364 - Support application/hal+json format (@pboling)
-
-!365 - Support application/vnd.collection+json format (@pboling)
-
-!376 - Documentation: Example / Test for Google 2-legged JWT (@jhmoore)
-
-!381 - Spec for extra header params on client credentials (@nikz)
-
-!394 - Option: OAuth2::AccessToken#initialize - :expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency (@klippx)
-
-!412 - Support application/vdn.api+json format (from jsonapi.org) (@david-christensen)
-
-!413 - Documentation: License scan and report (@meganemura)
-
-!442 - Option: OAuth2::Client#initialize - :logger (::Logger.new($stdout)) logger to use when OAUTH_DEBUG is enabled (for parity with 1-4-stable branch) (@rthbound)
-!575 - Support IETF rfc7231, section 7.1.2 - relative location in redirect (@pboling)
-
-!581 - Documentation: of breaking changes (@pboling)
-
-
-
Changed
-
-
-
-!191 - BREAKING: Token is expired if expired_at time is now (@davestevens)
-
-!312 - BREAKING: Set :basic_auth as default for :auth_scheme instead of :request_body. This was default behavior before 1.3.0. (@tetsuya, @wy193777)
-
-!317 - Dependency: Upgrade jwt to 2.x.x (@travisofthenorth)
-
-!338 - Dependency: Switch from Rack::Utils.escape to CGI.escape (@josephpage)
-
-!339, !368, !424, !479, !493, !539, !542, !553 - CI Updates, code coverage, linting, spelling, type fixes, New VERSION constant (@pboling, @josephpage, @ahorek)
-
-!410 - BREAKING: Removed the ability to call .error from an OAuth2::Response object (@jhmoore)
-
-!414 - Use Base64.strict_encode64 instead of custom internal logic (@meganemura)
-
-!469 - BREAKING: Default value for option OAuth2::Client - :authorize_url removed leading slash to work with relative paths by default ('oauth/authorize') (@ghost)
-
-!469 - BREAKING: Default value for option OAuth2::Client - :token_url removed leading slash to work with relative paths by default ('oauth/token') (@ghost)
-
-!507, !575 - BREAKING: Transform keys to snake case, always, by default (ultimately via rash_alt gem)
-
-
Original keys will still work as previously, in most scenarios, thanks to rash_alt gem.
-
However, this is a breaking change if you rely on response.parsed.to_h, as the keys in the result will be snake case.
-
As of version 2.0.4 you can turn key transformation off with the snaky: false option.
Add support for header-based authentication to the Client so it can be used across the library (@bjeanes)
-
Default to header-based authentication when getting a token from an authorisation code (@maletor)
-
-Breaking: Allow an auth_scheme (:basic_auth or :request_body) to be set on the client, defaulting to :request_body to maintain backwards compatibility (@maletor, @bjeanes)
-
Handle redirect_uri according to the OAuth 2 spec, so it is passed on redirect and at the point of token exchange (@bjeanes)
-
Refactor handling of encoding of error responses (@urkle)
-
Avoid instantiating an Error if there is no error to raise (@urkle)
Various refactors (eliminating Hash#merge! usage in AccessToken#refresh!, use yield instead of #call, freezing mutable objects in constants, replacing constants with class variables) (@sferik)
-
Add support for Rack 2, and bump various other dependencies (@sferik)
cff-version: 1.2.0
-title: oauth2
-message: >-
- If you use this work and you want to cite it,
- then you can use the metadata from this file.
-type: software
-authors:
We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-
We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-
Our Standards
-
-
Examples of behavior that contributes to a positive environment for our
-community include:
-
-
-
Demonstrating empathy and kindness toward other people
-
Being respectful of differing opinions, viewpoints, and experiences
-
Giving and gracefully accepting constructive feedback
-
Accepting responsibility and apologizing to those affected by our mistakes,
-and learning from the experience
-
Focusing on what is best not just for us as individuals, but for the overall
-community
-
-
-
Examples of unacceptable behavior include:
-
-
-
The use of sexualized language or imagery, and sexual attention or advances of
-any kind
-
Trolling, insulting or derogatory comments, and personal or political attacks
-
Public or private harassment
-
Publishing others’ private information, such as a physical or email address,
-without their explicit permission
-
Other conduct which could reasonably be considered inappropriate in a
-professional setting
-
-
-
Enforcement Responsibilities
-
-
Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-
Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-
Scope
-
-
This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-
Enforcement
-
-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-.
-All complaints will be reviewed and investigated promptly and fairly.
-
-
All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-
Enforcement Guidelines
-
-
Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-
1. Correction
-
-
Community Impact: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-
Consequence: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-
2. Warning
-
-
Community Impact: A violation through a single incident or series of
-actions.
-
-
Consequence: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-
3. Temporary Ban
-
-
Community Impact: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-
Consequence: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-
4. Permanent Ban
-
-
Community Impact: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-
Consequence: A permanent ban from any sort of public interaction within the
-community.
Bug reports and pull requests are welcome on CodeBerg, GitLab, or GitHub.
-This project should be a safe, welcoming space for collaboration, so contributors agree to adhere to
-the code of conduct.
-
-
To submit a patch, please fork the project, create a patch with tests, and send a pull request.
-
-
Remember to if you make changes.
-
-
Help out!
-
-
Take a look at the reek list which is the file called REEK and find something to improve.
-
-
Follow these instructions:
-
-
-
Fork the repository
-
Create a feature branch (git checkout -b my-new-feature)
-
Make some fixes.
-
Commit changes (git commit -am 'Added some feature')
-
Push to the branch (git push origin my-new-feature)
-
Make sure to add tests for it. This is important, so it doesn’t break in a future release.
-
Create new Pull Request.
-
-
-
Executables vs Rake tasks
-
-
Executables shipped by dependencies, such as kettle-dev, and stone_checksums, are available
-after running bin/setup. These include:
-
-
-
gem_checksums
-
kettle-changelog
-
kettle-commit-msg
-
kettle-dev-setup
-
kettle-dvcs
-
kettle-pre-release
-
kettle-readme-backers
-
kettle-release
-
-
-
There are many Rake tasks available as well. You can see them by running:
-
-
bin/rake -T
-
-
-
Environment Variables for Local Development
-
-
Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string “true” to enable.
-
-
General/runtime
-
-
DEBUG: Enable extra internal logging for this library (default: false)
-
REQUIRE_BENCH: Enable require_bench to profile requires (default: false)
-
CI: When set to true, adjusts default rake tasks toward CI behavior
-
-
-
Coverage (kettle-soup-cover / SimpleCov)
-
-
K_SOUP_COV_DO: Enable coverage collection (default: true in .envrc)
-
K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty)
-
K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100)
K_SOUP_COV_MIN_HARD: Fail the run if thresholds are not met (true/false)
-
K_SOUP_COV_MULTI_FORMATTERS: Enable multiple formatters at once (true/false)
-
K_SOUP_COV_OPEN_BIN: Path to browser opener for HTML (empty disables auto-open)
-
MAX_ROWS: Limit console output rows for simplecov-console (e.g., 1)
-Tip: When running a single spec file locally, you may want K_SOUP_COV_MIN_HARD=false to avoid failing thresholds for a partial run.
-
-
-
GitHub API and CI helpers
-
-
GITHUB_TOKEN or GH_TOKEN: Token used by ci:act and release workflow checks to query GitHub Actions status at higher rate limits
-
-
-
Releasing and signing
-
-
SKIP_GEM_SIGNING: If set, skip gem signing during build/release
-
GEM_CERT_USER: Username for selecting your public cert in certs/<USER>.pem (defaults to $USER)
-kettle-release will set this automatically for the session.
-
Not needed on bundler >= 2.7.0, as reproducible builds have become the default.
-
-
-
-
-
Git hooks and commit message helpers (exe/kettle-commit-msg)
-
-
GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., jira) or false to disable
-
GIT_HOOK_FOOTER_APPEND: Append a footer to commit messages when goalie allows (true/false)
-
GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates
-
GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false)
-
-
-
For a quick starting point, this repository’s .envrc shows sane defaults, and .env.local can override them locally.
-
-
Appraisals
-
-
From time to time the appraisal2 gemfiles in gemfiles/ will need to be updated.
-They are created and updated with the commands:
-
-
bin/rake appraisal:update
-
-
-
When adding an appraisal to CI, check the runner tool cache to see which runner to use.
-
-
The Reek List
-
-
Take a look at the reek list which is the file called REEK and find something to improve.
-
-
To refresh the reek list:
-
-
bundle exec reek > REEK
-
-
-
Run Tests
-
-
To run all tests
-
-
bundle exec rake test
-
-
-
Spec organization (required)
-
-
-
One spec file per class/module. For each class or module under lib/, keep all of its unit tests in a single spec file under spec/ that mirrors the path and file name exactly: lib/oauth2/my_class.rb -> spec/oauth2/my_class_spec.rb.
-
Exception: Integration specs that intentionally span multiple classes. Place these under spec/integration/ (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.
-
-
-
Lint It
-
-
Run all the default tasks, which includes running the gradually autocorrecting linter, rubocop-gradual.
-
-
bundle exec rake
-
-
-
Or just run the linter.
-
-
bundle exec rake rubocop_gradual:autocorrect
-
-
-
For more detailed information about using RuboCop in this project, please see the RUBOCOP.md guide. This project uses rubocop_gradual instead of vanilla RuboCop, which requires specific commands for checking violations.
-
-
Important: Do not add inline RuboCop disables
-
-
Never add # rubocop:disable ... / # rubocop:enable ... comments to code or specs (except when following the few existing rubocop:disable patterns for a rule already being disabled elsewhere in the code). Instead:
-
-
-
Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via .rubocop.yml).
-
When a violation is temporary, and you plan to fix it later, record it in .rubocop_gradual.lock using the gradual workflow:
-
-bundle exec rake rubocop_gradual:force_update (only when you cannot fix the violations immediately)
-
-
-
-
-
As a general rule, fix style issues rather than ignoring them. For example, our specs should follow RSpec conventions like using described_class for the class under test.
IMPORTANT: To sign a build,
-a public key for signing gems will need to be picked up by the line in the
-gemspec defining the spec.cert_chain (check the relevant ENV variables there).
-All releases are signed releases.
-See: RubyGems Security Guide
-
-
NOTE: To build without signing the gem set SKIP_GEM_SIGNING to any value in the environment.
-
-
To release a new version:
-
-
Automated process
-
-
-
Update version.rb to contain the correct version-to-be-released.
-
Run bundle exec kettle-changelog.
-
Run bundle exec kettle-release.
-
Stay awake and monitor the release process for any errors, and answer any prompts.
-
-
-
Manual process
-
-
-
Run bin/setup && bin/rake as a “test, coverage, & linting” sanity check
-
Update the version number in version.rb, and ensure CHANGELOG.md reflects changes
-
Run bin/setup && bin/rake again as a secondary check, and to update Gemfile.lock
-
-
Run git commit -am "🔖 Prepare release v<VERSION>" to commit the changes
-
Run git push to trigger the final CI pipeline before release, and merge PRs
-
Run export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME
-
-
Run git checkout $GIT_TRUNK_BRANCH_NAME
-
-
Run git pull origin $GIT_TRUNK_BRANCH_NAME to ensure latest trunk code
-
Optional for older Bundler (< 2.7.0): Set SOURCE_DATE_EPOCH so rake build and rake release use the same timestamp and generate the same checksums
-
-
If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default.
-
Run export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH
-
-
If the echo above has no output, then it didn’t work.
-
Note: zsh/datetime module is needed, if running zsh.
-
In older versions of bash you can use date +%s instead, i.e. export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH
-
-
-
-
Run bundle exec rake build
-
-
Run bin/gem_checksums (more context 1, 2)
-to create SHA-256 and SHA-512 checksums. This functionality is provided by the stone_checksums
-gem.
-
-
The script automatically commits but does not push the checksums
-
-
-
Sanity check the SHA256, comparing with the output from the bin/gem_checksums command:
-
-
sha256sum pkg/<gem name>-<version>.gem
-
-
-
Run bundle exec rake release which will create a git tag for the version,
-push git commits and tags, and push the .gem file to the gem host configured in the gemspec.
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html
index b9bcffdb..e69de29b 100644
--- a/docs/file.FUNDING.html
+++ b/docs/file.FUNDING.html
@@ -1,109 +0,0 @@
-
-
-
-
-
-
- File: FUNDING
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Many paths lead to being a sponsor or a backer of this project. Are you on such a path?
-
-
-
-
-
-
-
-
🤑 A request for help
-
-
Maintainers have teeth and need to pay their dentists.
-After getting laid off in an RIF in March, and encountering difficulty finding a new one,
-I began spending most of my time building open source tools.
-I’m hoping to be able to pay for my kids’ health insurance this month,
-so if you value the work I am doing, I need your support.
-Please consider sponsoring me or the project.
-
-
To join the community or get help 👇️ Join the Discord.
-
-
-
-
To say “thanks!” ☝️ Join the Discord or 👇️ send money.
-
-
💌 💌 💌
-
-
Another Way to Support Open Source Software
-
-
I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small. Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions. I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈 cats).
-
-
If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in bundle fund.
-
-
I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
-
-
Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.IRP.html b/docs/file.IRP.html
index ee5c595c..e69de29b 100644
--- a/docs/file.IRP.html
+++ b/docs/file.IRP.html
@@ -1,221 +0,0 @@
-
-
-
-
-
-
- File: IRP
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
This Incident Response Plan (IRP) defines the steps the project maintainer(s) will follow when handling security incidents related to the oauth2 gem. It is written for a small project with a single primary maintainer and is intended to be practical, concise, and actionable.
-
-
Scope
-
-
Applies to security incidents that affect the oauth2 codebase, releases (gems), CI/CD infrastructure related to building and publishing the gem, repository credentials, or any compromise of project infrastructure that could impact users.
-
-
Key assumptions
-
-
This project is maintained primarily by a single maintainer.
-
Public vulnerability disclosure is handled via Tidelift (see SECURITY.md).
-
The maintainer will act as incident commander unless otherwise delegated.
-
-
-
Contact & Roles
-
-
-
Incident Commander: Primary maintainer (repo owner). Responsible for coordinating triage, remediation, and communications.
-
Secondary Contact: (optional) A trusted collaborator or organization contact if available.
-
-
-
If you are an external reporter
-
-
Do not publicly disclose details of an active vulnerability before coordination via Tidelift.
-
See SECURITY.md for Tidelift disclosure instructions. If the reporter has questions and cannot use Tidelift, they may open a direct encrypted report as described in SECURITY.md (if available) or email the maintainer contact listed in the repository.
-
-
-
Incident Handling Workflow (high level)
-
-
Identification & Reporting
-
-
Reports may arrive via Tidelift, issue tracker, direct email, or third-party advisories.
-
Immediately acknowledge receipt (within 24-72 hours) via the reporting channel.
-
-
-
Triage & Initial Assessment (first 72 hours)
-
-
Confirm the report is not duplicative and gather: reproducer, affected versions, attack surface, exploitability, and CVSS-like severity estimate.
-
Verify the issue against the codebase and reproduce locally if possible.
-
Determine scope: which versions are affected, whether the issue is in code paths executed in common setups, and whether a workaround exists.
-
-
-
Containment & Mitigation
-
-
If a simple mitigation or workaround (configuration change, safe default, or recommended upgrade) exists, document it clearly in the issue/Tidelift advisory.
-
If immediate removal of a release is required (rare), consult Tidelift for coordinated takedown and notify package hosts if applicable.
-
-
-
Remediation & Patch
-
-
Prepare a fix in a branch with tests and changelog entries. Prefer minimal, well-tested changes.
-
Include tests that reproduce the faulty behavior and demonstrate the fix.
-
Hardening: add fuzz tests, input validation, or additional checks as appropriate.
-
-
-
Release & Disclosure
-
-
Coordinate disclosure through Tidelift per SECURITY.md timelines. Aim for a coordinated disclosure and patch release to minimize risk to users.
-
Publish a patch release (increment gem version) and an advisory via Tidelift.
-
Update CHANGELOG.md and repository release notes with non-sensitive details.
-
-
-
Post-Incident
-
-
Produce a short postmortem: timeline, root cause, actions taken, and follow-ups.
-
Add/adjust tests and CI checks to prevent regressions.
-
If credentials or infrastructure were compromised, rotate secrets and audit access.
-
-
-
-
-
Severity classification (guidance)
-
-
High/Critical: Remote code execution, data exfiltration, or any vulnerability that can be exploited without user interaction. Immediate action and prioritized patching.
-
Medium: Privilege escalation, sensitive information leaks that require specific conditions. Patch in the next release cycle with advisory.
-
Low: Minor information leaks, UI issues, or non-exploitable bugs. Fix normally and include in the next scheduled release.
-
-
-
Preservation of evidence
-
-
Preserve all reporter-provided data, logs, and reproducer code in a secure location (local encrypted storage or private branch) for the investigation.
-
Do not publish evidence that would enable exploitation before coordinated disclosure.
-
-
-
Communication templates
-
Acknowledgement (to reporter)
-
-
“Thank you for reporting this issue. I’ve received your report and will triage it within 72 hours. If you can, please provide reproduction steps, affected versions, and any exploit PoC. I will coordinate disclosure through Tidelift per the project’s security policy.”
-
-
Public advisory (after patch is ready)
-
-
“A security advisory for oauth2 (versions X.Y.Z) has been published via Tidelift. Please upgrade to version A.B.C which patches [brief description]. See the advisory for details and recommended mitigations.”
-
-
Runbook: Quick steps for a maintainer to patch and release
-
-
Create a branch: git checkout -b fix/security-brief-description
-
-
Reproduce the issue locally and add a regression spec in spec/.
-
Implement the fix and run the test suite: bundle exec rspec (or the project’s preferred test command).
-
Bump version in lib/oauth2/version.rb following semantic versioning.
-
Update CHANGELOG.md with an entry describing the fix (avoid exploit details).
-
Commit and push the branch, open a PR, and merge after approvals.
-
Build and push the gem: gem build oauth2.gemspec && gem push pkg/... (coordinate with Tidelift before public push if disclosure is coordinated).
-
Publish a release on GitHub and ensure the Tidelift advisory is posted.
-
-
-
Operational notes
-
-
Secrets: Use local encrypted storage for any sensitive reporter data. If repository or CI secrets may be compromised, rotate them immediately and update dependent services.
-
Access control: Limit who can publish gems and who has admin access to the repo. Keep an up-to-date list of collaborators in a secure place.
-
-
-
Legal & regulatory
-
-
If the incident involves user data or has legal implications, consult legal counsel or the maintainers’ employer as appropriate. The maintainer should document the timeline and all communications.
-
-
-
Retrospective & continuous improvement
-
After an incident, perform a brief post-incident review covering:
-
-
What happened and why
-
What was done to contain and remediate
-
What tests or process changes will prevent recurrence
-
Assign owners and deadlines for follow-up tasks
-
-
-
References
-
-
See SECURITY.md for the project’s official disclosure channel (Tidelift).
-
-
-
Appendix: Example checklist for an incident
-
-
-Acknowledge report to reporter (24-72 hours)
-
-Reproduce and classify severity
-
-Prepare and test a fix in a branch
-
-Coordinate disclosure via Tidelift
-
-Publish patch release and advisory
-
-Postmortem and follow-up actions
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
index 590a43a5..e69de29b 100644
--- a/docs/file.LICENSE.html
+++ b/docs/file.LICENSE.html
@@ -1,70 +0,0 @@
-
-
-
-
-
-
- File: LICENSE
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Copyright (c) 2017-2026 Peter H. Boling, of Galtzo.com, and oauth2 contributors Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.OIDC.html b/docs/file.OIDC.html
index c61ee552..e69de29b 100644
--- a/docs/file.OIDC.html
+++ b/docs/file.OIDC.html
@@ -1,266 +0,0 @@
-
-
-
-
-
-
- File: OIDC
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
If any other libraries would like to be added to this list, please open an issue or pull request.
-
-
Raw OIDC with ruby-oauth/oauth2
-
-
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.
-
-
Scope of this document
-
-
-
Audience: Developers building an OAuth 2.0/OIDC Relying Party (RP, aka client) in Ruby.
-
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).
-
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.
-
-
-
Key concepts refresher
-
-
-
OAuth 2.0 delegates authorization; it does not define authentication of the end-user.
-
OIDC layers an identity layer on top of OAuth 2.0, introducing:
-
-
ID Token: a JWT carrying claims about the authenticated end-user and the authentication event.
UserInfo endpoint: a protected resource for retrieving user profile claims.
-
Discovery and Dynamic Client Registration (optional for providers/clients that support them).
-
-
-
-
-
What this gem provides for OIDC
-
-
-
All OAuth 2.0 client capabilities required for OIDC flows: building authorization requests, exchanging authorization codes, refreshing tokens, and making authenticated resource requests.
-
Transport and parsing conveniences (snaky hash, Faraday integration, error handling, etc.).
-
Optional client authentication schemes useful with OIDC deployments:
-
-
basic_auth (default)
-
request_body (legacy)
-
tls_client_auth (MTLS)
-
private_key_jwt (OIDC-compliant when configured per OP requirements)
-
-
-
-
-
What you must add in your app for OIDC
-
-
-
ID Token validation: This gem surfaces id_token values but does not verify them. Your app should:
-1) Parse the JWT (header, payload, signature)
-2) Fetch the OP JSON Web Key Set (JWKS) from discovery (or configure statically)
-3) Select the correct key by kid (when present) and verify the signature and algorithm
-4) Validate standard claims (iss, aud, exp, iat, nbf, azp, nonce when used, at_hash/c_hash when applicable)
-5) Enforce expected client_id, issuer, and clock skew policies
-
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.
-
PKCE is best practice and often required by OPs: generate/verifier, send challenge in authorize, send verifier in token request.
-
Session/state management: continue to validate state to mitigate CSRF; use exact redirect_uri matching.
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.
-
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.
-
-
-
Common pitfalls and tips
-
-
-
Always request the openid scope when you expect an ID Token. Without it, the OP may behave as vanilla OAuth 2.0.
-
Validate ID Token signature and claims before trusting any identity data. Do not rely solely on the presence of an id_token field.
-
Prefer Authorization Code + PKCE. Avoid Implicit; it is discouraged in modern guidance and may be disabled by providers.
-
Use exact redirect_uri matching, and keep your allow-list short.
-
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.
-
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.
Spring Authorization Server’s list of OAuth2/OIDC specs: https://github.com/spring-projects/spring-authorization-server/wiki/OAuth2-and-OIDC-Specifications
-
-
-
See also
-
-
-
README sections on OAuth 2.1 notes and OIDC notes
-
Strategy classes under lib/oauth2/strategy for flow helpers
-
Specs under spec/oauth2 for concrete usage patterns
-
-
-
Contributions welcome
-
-
-
If you discover provider-specific nuances, consider contributing examples or clarifications (without embedding provider-specific hacks into the library).
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.README.html b/docs/file.README.html
index bec62448..e69de29b 100644
--- a/docs/file.README.html
+++ b/docs/file.README.html
@@ -1,1655 +0,0 @@
-
-
-
-
-
-
- File: README
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
-
-
-
-
- 👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️
-
-I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-takeover-of-rubygems-my-thoughts-5hlo).
-
-
-
-
🌻 Synopsis
-
-
OAuth 2.0 is the industry-standard protocol for authorization.
-This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.
-
-
⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC)
-
-
Quick Examples
-
-
- Convert the following `curl` command into a token request using this gem...
-
-
E2E example does not ship with the released gem, so clone the source to play with it.
-
-
-
docker compose -f docker-compose-ssl.yml up -d --wait
-ruby examples/e2e.rb
-# If your machine is slow or Docker pulls are cold, increase the wait:
-E2E_WAIT_TIMEOUT=120 ruby examples/e2e.rb
-# The mock server serves HTTP on 8080; the example points to http://localhost:8080 by default.
-
The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
-
-
-
-
-
💡Subscribe for support guarantees covering all your FLOSS dependencies
💡Tidelift pays maintainers to maintain the software you depend on! 📊@Pointy Haired Boss: An enterprise support subscription is “never gonna let you down”, and supports open source maintainers
-
-
-
Alternatively:
-
-
-
-
-
-
-
-
-
-
✨ Installation
-
-
Install the gem and add to the application’s Gemfile by executing:
-
-
bundle add oauth2
-
-
-
If bundler is not being used to manage dependencies, install the gem by executing:
-
-
gem install oauth2
-
-
-
🔒 Secure Installation
-
-
- For Medium or High Security Installations
-
-
This gem is cryptographically signed, and has verifiable SHA-256 and SHA-512 checksums by
-stone_checksums. Be sure the gem you install hasn’t been tampered with
-by following the instructions below.
-
-
Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
Support new formats, including from jsonapi.org: application/vdn.api+json, application/vnd.collection+json, application/hal+json, application/problem+json
-
-
Adds option to OAuth2::Client#get_token:
-
-
-:access_token_class (AccessToken); user specified class to use for all calls to get_token
-
-
-
-
Adds option to OAuth2::AccessToken#initialize:
-
-
-:expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency
-
-
-
By default, keys are transformed to snake case.
-
-
Original keys will still work as previously, in most scenarios, thanks to snaky_hash gem.
-
However, this is a breaking change if you rely on response.parsed.to_h to retain the original case, and the original wasn’t snake case, as the keys in the result will be snake case.
-
As of version 2.0.4 you can turn key transformation off with the snaky: false option.
-
-
-
By default, the :auth_scheme is now :basic_auth (instead of :request_body)
-
-
Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body
Targeted ruby compatibility is non-EOL versions of Ruby, currently 3.2, 3.3, and 3.4.
-Compatibility is further distinguished as “Best Effort Support” or “Incidental Support” for older versions of Ruby.
-This gem will install on Ruby versions >= v2.2 for 2.x releases.
-See 1-4-stable branch for older rubies.
-
-
- Ruby Engine Compatibility Policy
-
-
This gem is tested against MRI, JRuby, and Truffleruby.
-Each of those has varying versions that target a specific version of MRI Ruby.
-This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below.
-If you would like to add support for additional engines,
-see gemfiles/README.md, then submit a PR to the correct maintenance branch as according to the table below.
-
-
-
-
- Ruby Version Compatibility Policy
-
-
If something doesn’t work on one of these interpreters, it’s a bug.
-
-
This library may inadvertently work (or seem to work) on other Ruby
-implementations; however, support will only be provided for the versions listed
-above.
-
-
If you would like this library to support another Ruby version, you may
-volunteer to be a maintainer. Being a maintainer entails making sure all tests
-run and pass on that implementation. When something breaks on your
-implementation, you will be responsible for providing patches in a timely
-fashion. If critical issues for a particular implementation exist at the time
-of a major release, support for that Ruby version may be dropped.
-
-
-
-
-
-
-
-
Ruby OAuth2 Version
-
Maintenance Branch
-
Targeted Support
-
Best Effort Support
-
Incidental Support
-
-
-
-
-
1️⃣
-
2.0.x
-
main
-
3.2, 3.3, 3.4
-
2.5, 2.6, 2.7, 3.0, 3.1
-
2.2, 2.3, 2.4
-
-
-
2️⃣
-
1.4.x
-
1-4-stable
-
3.2, 3.3, 3.4
-
2.5, 2.6, 2.7, 3.0, 3.1
-
1.9, 2.0, 2.1, 2.2, 2.3, 2.4
-
-
-
3️⃣
-
older
-
N/A
-
Best of luck to you!
-
Please upgrade!
-
-
-
-
-
-
NOTE: The 1.4 series will only receive critical security updates.
-See SECURITY.md and IRP.md.
Relative authorize_url and token_url (Not on site root, Just Works!)
-
-
In the above example, the default Authorization URL is oauth/authorize and default Access Token URL is oauth/token, and, as they are missing a leading /, both are relative.
Instances of OAuth2::AccessToken handle request signing and token expiration.
-
-
-
-Snake Case & Indifferent Access: response.parsed returns a SnakyHash allowing access via string/symbol and snake_case keys even if the provider returns CamelCase.
-
-Auto-Refresh: You can manually check token.expired? and call token.refresh.
-
-Serialization: Persist tokens using token.to_hash and restore via OAuth2::AccessToken.from_hash(client, hash).
-
-
-
snake_case and indifferent access in Response#parsed
-
-
response = access.get("/api/resource", params: {"query_foo" => "bar"})
-# Even if the actual response is CamelCase. it will be made available as snaky:
-JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
-response.parsed # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
-response.parsed.access_token # => "aaaaaaaa"
-response.parsed[:access_token] # => "aaaaaaaa"
-response.parsed.additional_data # => "additional"
-response.parsed[:additional_data] # => "additional"
-response.parsed.class.name # => SnakyHash::StringKeyed (from snaky_hash gem)
-
-
-
Serialization
-
-
As of v2.0.11, if you need to serialize the parsed result, you can!
-
-
There are two ways to do this, globally, or discretely. The discrete way is recommended.
-
-
Global Serialization Config
-
-
Globally configure SnakyHash::StringKeyed to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).
-
-
SnakyHash::StringKeyed.class_eval do
- extend SnakyHash::Serializer
-end
-
-
-
Discrete Serialization Config
-
-
Discretely configure a custom Snaky Hash class to use the serializer.
-
-
class MySnakyHash < SnakyHash::StringKeyed
- # Give this hash class `dump` and `load` abilities!
- extend SnakyHash::Serializer
-end
-
-# And tell your client to use the custom class in each call:
-client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
-token = client.get_token({snaky_hash_klass: MySnakyHash})
-
-
-
Serialization Extensions
-
-
These extensions work regardless of whether you used the global or discrete config above.
-
-
There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.
-They are likely not needed if you are on a newer Ruby.
-Expand the examples below, or the ruby-oauth/snaky_hash gem,
-or response_spec.rb, for more ideas, especially if you need to study the hacks for older Rubies.
-
-
- See Examples
-
-
class MySnakyHash < SnakyHash::StringKeyed
- # Give this hash class `dump` and `load` abilities!
- extend SnakyHash::Serializer
-
- #### Serialization Extentions
- #
- # Act on the non-hash values (including the values of hashes) as they are dumped to JSON
- # In other words, this retains nested hashes, and only the deepest leaf nodes become bananas.
- # WARNING: This is a silly example!
- dump_value_extensions.add(:to_fruit) do |value|
- "banana" # => Make values "banana" on dump
- end
-
- # Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump
- # In other words, this retains nested hashes, and only the deepest leaf nodes become ***.
- # WARNING: This is a silly example!
- load_value_extensions.add(:to_stars) do |value|
- "***" # Turn dumped bananas into *** when they are loaded
- end
-
- # Act on the entire hash as it is prepared for dumping to JSON
- # WARNING: This is a silly example!
- dump_hash_extensions.add(:to_cheese) do |value|
- if value.is_a?(Hash)
- value.transform_keys do |key|
- split = key.split("_")
- first_word = split[0]
- key.sub(first_word, "cheese")
- end
- else
- value
- end
- end
-
- # Act on the entire hash as it is loaded from the JSON dump
- # WARNING: This is a silly example!
- load_hash_extensions.add(:to_pizza) do |value|
- if value.is_a?(Hash)
- res = klass.new
- value.keys.each_with_object(res) do |key, result|
- split = key.split("_")
- last_word = split[-1]
- new_key = key.sub(last_word, "pizza")
- result[new_key] = value[key]
- end
- res
- else
- value
- end
- end
-end
-
The AccessToken methods #get, #post, #put and #delete and the generic #request
-will return an instance of the OAuth2::Response class.
-
-
This instance contains a #parsed method that will parse the response body and
-return a Hash-like SnakyHash::StringKeyed if the Content-Type is application/x-www-form-urlencoded or if
-the body is a JSON object. It will return an Array if the body is a JSON
-array. Otherwise, it will return the original body string.
-
-
The original response body, headers, and status can be accessed via their
-respective methods.
-
-
OAuth2::AccessToken
-
-
If you have an existing Access Token for a user, you can initialize an instance
-using various class methods including the standard new, from_hash (if you have
-a hash of the values), or from_kvform (if you have an
-application/x-www-form-urlencoded encoded string of the values).
-
-
Options (since v2.0.x unless noted):
-
-
-
-
-
-
-
-expires_latency (Integer
-
nil): Seconds to subtract from expires_in when computing #expired? to offset latency.
-
-
-
-
-
-
-
-
-
-token_name (String
-
Symbol
-
nil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
-
-
-
-
-
-
-
-
-
-mode (Symbol
-
Proc
-
Hash): Controls how the token is transmitted on requests made via this AccessToken instance.
-
-
-
-
-
-:header — Send as Authorization: Bearer header (default and preferred by OAuth 2.1 draft guidance).
-
-
-:query — Send as access_token query parameter (discouraged in general, but required by some providers).
-
Verb-dependent (since v2.0.15): Provide either:
-
-
a Proc taking |verb| and returning :header or :query, or
-
a Hash with verb symbols as keys, for example {get: :query, post: :header, delete: :header}.
-
-
-
-
-
-
-
Note: Verb-dependent mode supports providers like Instagram that require query mode for GET and header mode for POST/DELETE
-
-
-
Verb-dependent mode via Proc was added in v2.0.15
-
Verb-dependent mode via Hash was added in v2.0.16
-
-
-
OAuth2::Error
-
-
On 400+ status code responses, an OAuth2::Error will be raised. If it is a
-standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and
-error_description parameters. The #response property of OAuth2::Error will
-always contain the OAuth2::Response instance.
-
-
If you do not want an error to be raised, you may use :raise_errors => false
-option on initialization of the client. In this case the OAuth2::Response
-instance will be returned as usual and on 400+ status code responses, the
-Response instance will contain the OAuth2::Error instance.
-
-
Authorization Grants
-
-
Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
-authentication grant types have helper strategy classes that simplify client
-use. They are available via the #auth_code,
-#implicit,
-#password,
-#client_credentials, and
-#assertion methods respectively.
-
-
OAuth 2.1 (draft) Note:
-
-
-
-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.
-
-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.
-
-Redirect URIs must be compared using exact string matching by the Authorization Server.
-
-
- JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible)
-
-
# This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage.
-# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token.
-# The original snippet included:
-# - Basic Authorization header for the client (web_app:changeit)
-# - X-XSRF-TOKEN header from a cookie (some deployments require it)
-# - grant_type=password with username/password and client_id
-# Using oauth2 gem, you don't need to build multipart bodies; the gem sends
-# application/x-www-form-urlencoded as required by RFC 6749.
-
-require "oauth2"
-
-client = OAuth2::Client.new(
- "web_app", # client_id
- "changeit", # client_secret
- site: "http://localhost:8080/uaa",
- token_url: "/oauth/token", # absolute under site (or "oauth/token" relative)
- auth_scheme: :basic_auth, # sends HTTP Basic Authorization header
-)
-
-# If your UAA requires an XSRF header for the token call, provide it as a header.
-# Often this is not required for token endpoints, but if your gateway enforces it,
-# obtain the value from the XSRF-TOKEN cookie and pass it here.
-xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value
-
-access = client.password.get_token(
- "admin", # username
- "admin", # password
- headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {},
- # JHipster commonly also accepts/needs the client_id in the body; include if required:
- # client_id: "web_app",
-)
-
-puts access.token
-puts access.to_hash # full token response
-
-
-
Notes:
-
-
-
Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE.
-
If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often “/” or a login page) and pass it to headers.
-
For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually.
-
-
-
-
-
Verb‑dependent Token Mode
-
-
Providers like Instagram require the access token to be sent differently depending on the HTTP verb:
-
-
-
GET requests: token must be in the query string (?access_token=…)
-
POST/DELETE requests: token must be in the Authorization header (Bearer …)
-
-
-
Since v2.0.15, you can configure an AccessToken with a verb‑dependent mode. The gem will choose how to send the token based on the request method.
-
-
Tips:
-
-
-
Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for GET requests.
-
If you need a custom rule, you can pass a Proc for mode, e.g. mode: ->(verb) { verb == :get ? :query : :header }.
-
-
-
- Instagram API Example
-
-
Example: exchanging and refreshing long‑lived Instagram tokens, and making API calls
-
-
require "oauth2"
-
-# NOTE: Users authenticate via Facebook Login to obtain a short‑lived user token (not shown here).
-# See Facebook Login docs for obtaining the initial short‑lived token.
-
-client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com")
-
-# Start with a short‑lived token you already obtained via Facebook Login
-short_lived = OAuth2::AccessToken.new(
- client,
- ENV["IG_SHORT_LIVED_TOKEN"],
- # Key part: verb‑dependent mode
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 1) Exchange for a long‑lived token (Instagram requires GET with access_token in query)
-# Endpoint: GET https://graph.instagram.com/access_token
-# Params: grant_type=ig_exchange_token, client_secret=APP_SECRET
-exchange = short_lived.get(
- "/access_token",
- params: {
- grant_type: "ig_exchange_token",
- client_secret: ENV["IG_APP_SECRET"],
- # access_token param will be added automatically by the AccessToken (mode => :query for GET)
- },
-)
-long_lived_token_value = exchange.parsed["access_token"]
-
-long_lived = OAuth2::AccessToken.new(
- client,
- long_lived_token_value,
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 2) Refresh the long‑lived token (Instagram uses GET with token in query)
-# Endpoint: GET https://graph.instagram.com/refresh_access_token
-refresh_resp = long_lived.get(
- "/refresh_access_token",
- params: {grant_type: "ig_refresh_token"},
-)
-long_lived = OAuth2::AccessToken.new(
- client,
- refresh_resp.parsed["access_token"],
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 3) Typical API GET request (token in query automatically)
-me = long_lived.get("/me", params: {fields: "id,username"}).parsed
-
-# 4) Example POST (token sent via Bearer header automatically)
-# Note: Replace the path/params with a real Instagram Graph API POST you need,
-# such as publishing media via the Graph API endpoints.
-# long_lived.post("/me/media", body: {image_url: "https://...", caption: "hello"})
-
-
-
-
-
Refresh Tokens
-
-
When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.
-
-
-
Manual refresh:
-
-
-
if access.expired?
- access = access.refresh
-end
-
-
-
-
Auto-refresh wrapper pattern:
-
-
-
class AutoRefreshingToken
- def initialize(token_provider, store: nil)
- @token = token_provider
- @store = store # e.g., something that responds to read/write for token data
- end
-
- def with(&blk)
- tok = ensure_fresh!
- blk ? blk.call(tok) : tok
- rescue OAuth2::Error => e
- # If a 401 suggests token invalidation, try one refresh and retry once
- if e.response && e.response.status == 401 && @token.refresh_token
- @token = @token.refresh
- @store.write(@token.to_hash) if @store
- retry
- end
- raise
- end
-
-private
-
- def ensure_fresh!
- if @token.expired? && @token.refresh_token
- @token = @token.refresh
- @store.write(@token.to_hash) if @store
- end
- @token
- end
-end
-
-# usage
-keeper = AutoRefreshingToken.new(access)
-keeper.with { |tok| tok.get("/v1/protected") }
-
-
-
Persist the token across processes using AccessToken#to_hash and AccessToken.from_hash(client, hash).
-
-
Token Revocation (RFC 7009)
-
-
You can revoke either the access token or the refresh token.
-
-
# Revoke the current access token
-access.revoke(token_type_hint: :access_token)
-
-# Or explicitly revoke the refresh token (often also invalidates associated access tokens)
-access.revoke(token_type_hint: :refresh_token)
-
-
-
Client Configuration Tips
-
-
Mutual TLS (mTLS) client authentication
-
-
Some providers require OAuth requests (including the token request and subsequent API calls) to be sender‑constrained using mutual TLS (mTLS). With this gem, you enable mTLS by providing a client certificate/private key to Faraday via connection_opts.ssl and, if your provider requires it for client authentication, selecting the tls_client_auth auth_scheme.
-
-
Example using PEM files (certificate and key):
-
-
require "oauth2"
-require "openssl"
-
-client = OAuth2::Client.new(
- ENV.fetch("CLIENT_ID"),
- ENV.fetch("CLIENT_SECRET"),
- site: "https://example.com",
- authorize_url: "/oauth/authorize/",
- token_url: "/oauth/token/",
- auth_scheme: :tls_client_auth, # if your AS requires mTLS-based client authentication
- connection_opts: {
- ssl: {
- client_cert: OpenSSL::X509::Certificate.new(File.read("localhost.pem")),
- client_key: OpenSSL::PKey::RSA.new(File.read("localhost-key.pem")),
- # Optional extras, uncomment as needed:
- # ca_file: "/path/to/ca-bundle.pem", # custom CA(s)
- # verify: true # enable server cert verification (recommended)
- },
- },
-)
-
-# Example token request (any grant type can be used). The mTLS handshake
-# will occur automatically on HTTPS calls using the configured cert/key.
-access = client.client_credentials.get_token
-
-# Subsequent resource requests will also use mTLS on HTTPS endpoints of `site`:
-resp = access.get("/v1/protected")
-
-
-
Notes:
-
-
-
Files must contain the appropriate PEMs. The private key may be encrypted; if so, pass a password to OpenSSL::PKey::RSA.new(File.read(path), ENV["KEY_PASSWORD"]).
-
If your certificate and key are in a PKCS#12/PFX bundle, you can load them like:
-
If your environment does not have system CAs, specify ca_file or ca_path inside the ssl: hash.
-
Keep verify: true in production. Set verify: false only for local testing.
-
-
-
Faraday adapter: Any adapter that supports Ruby’s OpenSSL should work. net_http (default) and net_http_persistent are common choices.
-
Scope of mTLS: The SSL client cert is applied to any HTTPS request made by this client (token and resource requests) to the configured site base URL (and absolute URLs you call with the same client).
-
OIDC tie-in: Some OPs require tls_client_auth at the token endpoint per OIDC/OAuth specifications. That is enabled via auth_scheme: :tls_client_auth as shown above.
client = OAuth2::Client.new(
- id,
- secret,
- site: "https://provider.example.com",
- connection_opts: {
- request: {open_timeout: 5, timeout: 15},
- proxy: ENV["HTTPS_PROXY"],
- ssl: {verify: true},
- },
-) do |faraday|
- faraday.request(:url_encoded)
- # faraday.response :logger, Logger.new($stdout) # see OAUTH_DEBUG below
- faraday.adapter(:net_http_persistent) # or any Faraday adapter you need
-end
-
-
-
Using flat query params (Faraday::FlatParamsEncoder)
-
-
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.
-
-
require "faraday"
-
-client = OAuth2::Client.new(
- id,
- secret,
- site: "https://api.example.com",
- # Pass Faraday connection options to make FlatParamsEncoder the default
- connection_opts: {
- request: {params_encoder: Faraday::FlatParamsEncoder},
- },
-) do |faraday|
- faraday.request(:url_encoded)
- faraday.adapter(:net_http)
-end
-
-access = client.client_credentials.get_token
-
-# Example of a GET with two flat filter params (not an array):
-# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000
-resp = access.get(
- "/v1/orders",
- params: {
- # Provide the values as an array; FlatParamsEncoder expands them as repeated keys
- filter: [
- "order.clientCreatedTime>1445006997000",
- "order.clientCreatedTime<1445611797000",
- ],
- },
-)
-
-
-
If you instead need to build a raw Faraday connection yourself, the equivalent configuration is:
If the token response includes an id_token (a JWT), this gem surfaces it in token.params['id_token'].
-
-Note: This gem does not validate the signature of the id_token. You must use a JWT library (like the jwtgem) and your provider’s JWKs to verify it.
-
For private_key_jwt client authentication, provide auth_scheme: :private_key_jwt and ensure your key configuration matches the provider requirements.
-
See OIDC.md for a more complete OIDC overview and examples.
-
-
-
Debugging
-
-
-
Set environment variable OAUTH_DEBUG=true to enable verbose Faraday logging (uses the client-provided logger).
-
To mirror a working curl request, ensure you set the same auth scheme, params, and content type. The Quick Example at the top shows a curl-to-ruby translation.
-
-
-
-
-
🦷 FLOSS Funding
-
-
While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding.
-Raising a monthly budget of… “dollars” would make the project more sustainable.
-
-
We welcome both individual and corporate sponsors! We also offer a
-wide array of funding channels to account for your preferences
-(although currently Open Collective is our preferred funding platform).
-
-
If you’re working in a company that’s making significant use of ruby-oauth tools we’d
-appreciate it if you suggest to your company to become a ruby-oauth sponsor.
If doing a sponsorship in the form of donation is problematic for your company from an accounting standpoint, we’d recommend the use of Tidelift, where you can get a support-like subscription instead.
-
-
-
-
-
Open Collective for Individuals
-
-
Support us with a monthly donation and help us continue our activities. [Become a backer]
I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small. Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions. I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈 cats).
-
-
If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in bundle fund.
-
-
I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
-
-
Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags
-
-
-
-
🔐 Security
-
-
To report a security vulnerability, please use the Tidelift security contact.
-Tidelift will coordinate the fix and disclosure.
If you need some ideas of where to help, you could work on adding more code coverage,
-or if it is already 💯 (see below) check reek, issues, or PRs,
-or use the gem and think about how it could be better.
This Library adheres to .
-Violations of this scheme should be reported as bugs.
-Specifically, if a minor or patch version is released that breaks backward compatibility,
-a new version should be immediately released that restores compatibility.
-Breaking changes to the public API will only be introduced with new major versions.
-
-
-
dropping support for a platform is both obviously and objectively a breaking change
I understand that policy doesn’t work universally (“exceptions to every rule!”),
-but it is the policy here.
-As such, in many cases it is good to specify a dependency on this library using
-the Pessimistic Version Constraint with two digits of precision.
-
-
For example:
-
-
spec.add_dependency("oauth2", "~> 2.0")
-
-
-
- 📌 Is "Platform Support" part of the public API? More details inside.
-
-
SemVer should, IMO, but doesn’t explicitly, say that dropping support for specific Platforms
-is a breaking change to an API, and for that reason the bike shedding is endless.
-
-
To get a better understanding of how SemVer is intended to work over a project’s lifetime,
-read this article from the creator of SemVer:
- Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.
-
-
-
-
🤑 A request for help
-
-
Maintainers have teeth and need to pay their dentists.
-After getting laid off in an RIF in March, and encountering difficulty finding a new one,
-I began spending most of my time building open source tools.
-I’m hoping to be able to pay for my kids’ health insurance this month,
-so if you value the work I am doing, I need your support.
-Please consider sponsoring me or the project.
-
-
To join the community or get help 👇️ Join the Discord.
-
-
-
-
To say “thanks!” ☝️ Join the Discord or 👇️ send money.
-
-
💌 💌 💌
-
-
Please give the project a star ⭐ ♥.
-
-
Thanks for RTFM. ☺️
-
-
-
- rel="me" Social Proofs
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.REEK.html b/docs/file.REEK.html
index 967ab7e7..e69de29b 100644
--- a/docs/file.REEK.html
+++ b/docs/file.REEK.html
@@ -1,71 +0,0 @@
-
-
-
-
-
-
- File: REEK
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
This project uses rubocop_gradual instead of vanilla RuboCop for code style checking. The rubocop_gradual tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
-
-
RuboCop LTS
-
-
This project uses rubocop-lts to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
-RuboCop rules are meticulously configured by the rubocop-lts family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
-
-
Checking RuboCop Violations
-
-
To check for RuboCop violations in this project, always use:
-
-
bundle exec rake rubocop_gradual:check
-
-
-
Do not use the standard RuboCop commands like:
-
-
bundle exec rubocop
-
rubocop
-
-
-
Understanding the Lock File
-
-
The .rubocop_gradual.lock file tracks all current RuboCop violations in the project. This allows the team to:
-
-
-
Prevent new violations while gradually fixing existing ones
-
Track progress on code style improvements
-
Ensure CI builds don’t fail due to pre-existing violations
-
-
-
Common Commands
-
-
-
-Check violations
-
-
bundle exec rake rubocop_gradual
-
bundle exec rake rubocop_gradual:check
-
-
-
-(Safe) Autocorrect violations, and update lockfile if no new violations
-
-
bundle exec rake rubocop_gradual:autocorrect
-
-
-
-Force update the lock file (w/o autocorrect) to match violations present in code
-
-
bundle exec rake rubocop_gradual:force_update
-
-
-
-
-
Workflow
-
-
-
Before submitting a PR, run bundle exec rake rubocop_gradual:autocorrect
-a. or just the default bundle exec rake, as autocorrection is a pre-requisite of the default task.
-
If there are new violations, either:
-
-
Fix them in your code
-
Run bundle exec rake rubocop_gradual:force_update to update the lock file (only for violations you can’t fix immediately)
-
-
-
Commit the updated .rubocop_gradual.lock file along with your changes
-
-
-
Never add inline RuboCop disables
-
-
Do not add inline rubocop:disable / rubocop:enable comments anywhere in the codebase (including specs, except when following the few existing rubocop:disable patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
-
-
-
Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in .rubocop.yml) to exclude a rule for a path or file pattern when it makes sense project-wide.
-
Temporary exceptions while improving code: record the current violations in .rubocop_gradual.lock via the gradual workflow:
-
-
-bundle exec rake rubocop_gradual:autocorrect (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
-
If needed, bundle exec rake rubocop_gradual:force_update (as a last resort when you cannot fix the newly reported violations immediately)
-
-
-
-
-
In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect described_class to be used in specs that target a specific class under test.
-
-
Benefits of rubocop_gradual
-
-
-
Allows incremental adoption of code style rules
-
Prevents CI failures due to pre-existing violations
-
Provides a clear record of code style debt
-
Enables focused efforts on improving code quality over time
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html
index aa31edb4..e69de29b 100644
--- a/docs/file.SECURITY.html
+++ b/docs/file.SECURITY.html
@@ -1,103 +0,0 @@
-
-
-
-
-
-
- File: SECURITY
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
To report a security vulnerability, please use the
-Tidelift security contact.
-Tidelift will coordinate the fix and disclosure.
-
-
More detailed explanation of the process is in IRP.md
-
-
Additional Support
-
-
If you are interested in support for versions older than the latest release,
-please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
-or find other sponsorship links in the README.
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/file.THREAT_MODEL.html b/docs/file.THREAT_MODEL.html
index dc3ccd32..e69de29b 100644
--- a/docs/file.THREAT_MODEL.html
+++ b/docs/file.THREAT_MODEL.html
@@ -1,216 +0,0 @@
-
-
-
-
-
-
- File: THREAT_MODEL
-
- — Documentation by YARD 0.9.38
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
This document outlines the threat model for the oauth2 Ruby gem, which implements OAuth 2.0, 2.1, and OIDC Core protocols. The gem is used to facilitate secure authorization and authentication in Ruby applications.
-
-
2. Assets to Protect
-
-
OAuth access tokens, refresh tokens, and ID tokens
-
User credentials (if handled)
-
Client secrets and application credentials
-
Sensitive user data accessed via OAuth
-
Private keys and certificates (for signing/verifying tokens)
if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
-
-
-
-
- 👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️
-
-I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-takeover-of-rubygems-my-thoughts-5hlo).
-
-
-
-
🌻 Synopsis
-
-
OAuth 2.0 is the industry-standard protocol for authorization.
-This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.
-
-
⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC)
-
-
Quick Examples
-
-
- Convert the following `curl` command into a token request using this gem...
-
-
E2E example does not ship with the released gem, so clone the source to play with it.
-
-
-
docker compose -f docker-compose-ssl.yml up -d --wait
-ruby examples/e2e.rb
-# If your machine is slow or Docker pulls are cold, increase the wait:
-E2E_WAIT_TIMEOUT=120 ruby examples/e2e.rb
-# The mock server serves HTTP on 8080; the example points to http://localhost:8080 by default.
-
The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
-
-
-
-
-
💡Subscribe for support guarantees covering all your FLOSS dependencies
💡Tidelift pays maintainers to maintain the software you depend on! 📊@Pointy Haired Boss: An enterprise support subscription is “never gonna let you down”, and supports open source maintainers
-
-
-
Alternatively:
-
-
-
-
-
-
-
-
-
-
✨ Installation
-
-
Install the gem and add to the application’s Gemfile by executing:
-
-
bundle add oauth2
-
-
-
If bundler is not being used to manage dependencies, install the gem by executing:
-
-
gem install oauth2
-
-
-
🔒 Secure Installation
-
-
- For Medium or High Security Installations
-
-
This gem is cryptographically signed, and has verifiable SHA-256 and SHA-512 checksums by
-stone_checksums. Be sure the gem you install hasn’t been tampered with
-by following the instructions below.
-
-
Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
Support new formats, including from jsonapi.org: application/vdn.api+json, application/vnd.collection+json, application/hal+json, application/problem+json
-
-
Adds option to OAuth2::Client#get_token:
-
-
-:access_token_class (AccessToken); user specified class to use for all calls to get_token
-
-
-
-
Adds option to OAuth2::AccessToken#initialize:
-
-
-:expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency
-
-
-
By default, keys are transformed to snake case.
-
-
Original keys will still work as previously, in most scenarios, thanks to snaky_hash gem.
-
However, this is a breaking change if you rely on response.parsed.to_h to retain the original case, and the original wasn’t snake case, as the keys in the result will be snake case.
-
As of version 2.0.4 you can turn key transformation off with the snaky: false option.
-
-
-
By default, the :auth_scheme is now :basic_auth (instead of :request_body)
-
-
Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body
Targeted ruby compatibility is non-EOL versions of Ruby, currently 3.2, 3.3, and 3.4.
-Compatibility is further distinguished as “Best Effort Support” or “Incidental Support” for older versions of Ruby.
-This gem will install on Ruby versions >= v2.2 for 2.x releases.
-See 1-4-stable branch for older rubies.
-
-
- Ruby Engine Compatibility Policy
-
-
This gem is tested against MRI, JRuby, and Truffleruby.
-Each of those has varying versions that target a specific version of MRI Ruby.
-This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below.
-If you would like to add support for additional engines,
-see gemfiles/README.md, then submit a PR to the correct maintenance branch as according to the table below.
-
-
-
-
- Ruby Version Compatibility Policy
-
-
If something doesn’t work on one of these interpreters, it’s a bug.
-
-
This library may inadvertently work (or seem to work) on other Ruby
-implementations; however, support will only be provided for the versions listed
-above.
-
-
If you would like this library to support another Ruby version, you may
-volunteer to be a maintainer. Being a maintainer entails making sure all tests
-run and pass on that implementation. When something breaks on your
-implementation, you will be responsible for providing patches in a timely
-fashion. If critical issues for a particular implementation exist at the time
-of a major release, support for that Ruby version may be dropped.
-
-
-
-
-
-
-
-
Ruby OAuth2 Version
-
Maintenance Branch
-
Targeted Support
-
Best Effort Support
-
Incidental Support
-
-
-
-
-
1️⃣
-
2.0.x
-
main
-
3.2, 3.3, 3.4
-
2.5, 2.6, 2.7, 3.0, 3.1
-
2.2, 2.3, 2.4
-
-
-
2️⃣
-
1.4.x
-
1-4-stable
-
3.2, 3.3, 3.4
-
2.5, 2.6, 2.7, 3.0, 3.1
-
1.9, 2.0, 2.1, 2.2, 2.3, 2.4
-
-
-
3️⃣
-
older
-
N/A
-
Best of luck to you!
-
Please upgrade!
-
-
-
-
-
-
NOTE: The 1.4 series will only receive critical security updates.
-See SECURITY.md and IRP.md.
Relative authorize_url and token_url (Not on site root, Just Works!)
-
-
In the above example, the default Authorization URL is oauth/authorize and default Access Token URL is oauth/token, and, as they are missing a leading /, both are relative.
Instances of OAuth2::AccessToken handle request signing and token expiration.
-
-
-
-Snake Case & Indifferent Access: response.parsed returns a SnakyHash allowing access via string/symbol and snake_case keys even if the provider returns CamelCase.
-
-Auto-Refresh: You can manually check token.expired? and call token.refresh.
-
-Serialization: Persist tokens using token.to_hash and restore via OAuth2::AccessToken.from_hash(client, hash).
-
-
-
snake_case and indifferent access in Response#parsed
-
-
response = access.get("/api/resource", params: {"query_foo" => "bar"})
-# Even if the actual response is CamelCase. it will be made available as snaky:
-JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
-response.parsed # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
-response.parsed.access_token # => "aaaaaaaa"
-response.parsed[:access_token] # => "aaaaaaaa"
-response.parsed.additional_data # => "additional"
-response.parsed[:additional_data] # => "additional"
-response.parsed.class.name # => SnakyHash::StringKeyed (from snaky_hash gem)
-
-
-
Serialization
-
-
As of v2.0.11, if you need to serialize the parsed result, you can!
-
-
There are two ways to do this, globally, or discretely. The discrete way is recommended.
-
-
Global Serialization Config
-
-
Globally configure SnakyHash::StringKeyed to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).
-
-
SnakyHash::StringKeyed.class_eval do
- extend SnakyHash::Serializer
-end
-
-
-
Discrete Serialization Config
-
-
Discretely configure a custom Snaky Hash class to use the serializer.
-
-
class MySnakyHash < SnakyHash::StringKeyed
- # Give this hash class `dump` and `load` abilities!
- extend SnakyHash::Serializer
-end
-
-# And tell your client to use the custom class in each call:
-client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
-token = client.get_token({snaky_hash_klass: MySnakyHash})
-
-
-
Serialization Extensions
-
-
These extensions work regardless of whether you used the global or discrete config above.
-
-
There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.
-They are likely not needed if you are on a newer Ruby.
-Expand the examples below, or the ruby-oauth/snaky_hash gem,
-or response_spec.rb, for more ideas, especially if you need to study the hacks for older Rubies.
-
-
- See Examples
-
-
class MySnakyHash < SnakyHash::StringKeyed
- # Give this hash class `dump` and `load` abilities!
- extend SnakyHash::Serializer
-
- #### Serialization Extentions
- #
- # Act on the non-hash values (including the values of hashes) as they are dumped to JSON
- # In other words, this retains nested hashes, and only the deepest leaf nodes become bananas.
- # WARNING: This is a silly example!
- dump_value_extensions.add(:to_fruit) do |value|
- "banana" # => Make values "banana" on dump
- end
-
- # Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump
- # In other words, this retains nested hashes, and only the deepest leaf nodes become ***.
- # WARNING: This is a silly example!
- load_value_extensions.add(:to_stars) do |value|
- "***" # Turn dumped bananas into *** when they are loaded
- end
-
- # Act on the entire hash as it is prepared for dumping to JSON
- # WARNING: This is a silly example!
- dump_hash_extensions.add(:to_cheese) do |value|
- if value.is_a?(Hash)
- value.transform_keys do |key|
- split = key.split("_")
- first_word = split[0]
- key.sub(first_word, "cheese")
- end
- else
- value
- end
- end
-
- # Act on the entire hash as it is loaded from the JSON dump
- # WARNING: This is a silly example!
- load_hash_extensions.add(:to_pizza) do |value|
- if value.is_a?(Hash)
- res = klass.new
- value.keys.each_with_object(res) do |key, result|
- split = key.split("_")
- last_word = split[-1]
- new_key = key.sub(last_word, "pizza")
- result[new_key] = value[key]
- end
- res
- else
- value
- end
- end
-end
-
The AccessToken methods #get, #post, #put and #delete and the generic #request
-will return an instance of the OAuth2::Response class.
-
-
This instance contains a #parsed method that will parse the response body and
-return a Hash-like SnakyHash::StringKeyed if the Content-Type is application/x-www-form-urlencoded or if
-the body is a JSON object. It will return an Array if the body is a JSON
-array. Otherwise, it will return the original body string.
-
-
The original response body, headers, and status can be accessed via their
-respective methods.
-
-
OAuth2::AccessToken
-
-
If you have an existing Access Token for a user, you can initialize an instance
-using various class methods including the standard new, from_hash (if you have
-a hash of the values), or from_kvform (if you have an
-application/x-www-form-urlencoded encoded string of the values).
-
-
Options (since v2.0.x unless noted):
-
-
-
-
-
-
-
-expires_latency (Integer
-
nil): Seconds to subtract from expires_in when computing #expired? to offset latency.
-
-
-
-
-
-
-
-
-
-token_name (String
-
Symbol
-
nil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
-
-
-
-
-
-
-
-
-
-mode (Symbol
-
Proc
-
Hash): Controls how the token is transmitted on requests made via this AccessToken instance.
-
-
-
-
-
-:header — Send as Authorization: Bearer header (default and preferred by OAuth 2.1 draft guidance).
-
-
-:query — Send as access_token query parameter (discouraged in general, but required by some providers).
-
Verb-dependent (since v2.0.15): Provide either:
-
-
a Proc taking |verb| and returning :header or :query, or
-
a Hash with verb symbols as keys, for example {get: :query, post: :header, delete: :header}.
-
-
-
-
-
-
-
Note: Verb-dependent mode supports providers like Instagram that require query mode for GET and header mode for POST/DELETE
-
-
-
Verb-dependent mode via Proc was added in v2.0.15
-
Verb-dependent mode via Hash was added in v2.0.16
-
-
-
OAuth2::Error
-
-
On 400+ status code responses, an OAuth2::Error will be raised. If it is a
-standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and
-error_description parameters. The #response property of OAuth2::Error will
-always contain the OAuth2::Response instance.
-
-
If you do not want an error to be raised, you may use :raise_errors => false
-option on initialization of the client. In this case the OAuth2::Response
-instance will be returned as usual and on 400+ status code responses, the
-Response instance will contain the OAuth2::Error instance.
-
-
Authorization Grants
-
-
Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
-authentication grant types have helper strategy classes that simplify client
-use. They are available via the #auth_code,
-#implicit,
-#password,
-#client_credentials, and
-#assertion methods respectively.
-
-
OAuth 2.1 (draft) Note:
-
-
-
-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.
-
-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.
-
-Redirect URIs must be compared using exact string matching by the Authorization Server.
-
-
- JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible)
-
-
# This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage.
-# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token.
-# The original snippet included:
-# - Basic Authorization header for the client (web_app:changeit)
-# - X-XSRF-TOKEN header from a cookie (some deployments require it)
-# - grant_type=password with username/password and client_id
-# Using oauth2 gem, you don't need to build multipart bodies; the gem sends
-# application/x-www-form-urlencoded as required by RFC 6749.
-
-require "oauth2"
-
-client = OAuth2::Client.new(
- "web_app", # client_id
- "changeit", # client_secret
- site: "http://localhost:8080/uaa",
- token_url: "/oauth/token", # absolute under site (or "oauth/token" relative)
- auth_scheme: :basic_auth, # sends HTTP Basic Authorization header
-)
-
-# If your UAA requires an XSRF header for the token call, provide it as a header.
-# Often this is not required for token endpoints, but if your gateway enforces it,
-# obtain the value from the XSRF-TOKEN cookie and pass it here.
-xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value
-
-access = client.password.get_token(
- "admin", # username
- "admin", # password
- headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {},
- # JHipster commonly also accepts/needs the client_id in the body; include if required:
- # client_id: "web_app",
-)
-
-puts access.token
-puts access.to_hash # full token response
-
-
-
Notes:
-
-
-
Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE.
-
If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often “/” or a login page) and pass it to headers.
-
For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually.
-
-
-
-
-
Verb‑dependent Token Mode
-
-
Providers like Instagram require the access token to be sent differently depending on the HTTP verb:
-
-
-
GET requests: token must be in the query string (?access_token=…)
-
POST/DELETE requests: token must be in the Authorization header (Bearer …)
-
-
-
Since v2.0.15, you can configure an AccessToken with a verb‑dependent mode. The gem will choose how to send the token based on the request method.
-
-
Tips:
-
-
-
Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for GET requests.
-
If you need a custom rule, you can pass a Proc for mode, e.g. mode: ->(verb) { verb == :get ? :query : :header }.
-
-
-
- Instagram API Example
-
-
Example: exchanging and refreshing long‑lived Instagram tokens, and making API calls
-
-
require "oauth2"
-
-# NOTE: Users authenticate via Facebook Login to obtain a short‑lived user token (not shown here).
-# See Facebook Login docs for obtaining the initial short‑lived token.
-
-client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com")
-
-# Start with a short‑lived token you already obtained via Facebook Login
-short_lived = OAuth2::AccessToken.new(
- client,
- ENV["IG_SHORT_LIVED_TOKEN"],
- # Key part: verb‑dependent mode
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 1) Exchange for a long‑lived token (Instagram requires GET with access_token in query)
-# Endpoint: GET https://graph.instagram.com/access_token
-# Params: grant_type=ig_exchange_token, client_secret=APP_SECRET
-exchange = short_lived.get(
- "/access_token",
- params: {
- grant_type: "ig_exchange_token",
- client_secret: ENV["IG_APP_SECRET"],
- # access_token param will be added automatically by the AccessToken (mode => :query for GET)
- },
-)
-long_lived_token_value = exchange.parsed["access_token"]
-
-long_lived = OAuth2::AccessToken.new(
- client,
- long_lived_token_value,
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 2) Refresh the long‑lived token (Instagram uses GET with token in query)
-# Endpoint: GET https://graph.instagram.com/refresh_access_token
-refresh_resp = long_lived.get(
- "/refresh_access_token",
- params: {grant_type: "ig_refresh_token"},
-)
-long_lived = OAuth2::AccessToken.new(
- client,
- refresh_resp.parsed["access_token"],
- mode: {get: :query, post: :header, delete: :header},
-)
-
-# 3) Typical API GET request (token in query automatically)
-me = long_lived.get("/me", params: {fields: "id,username"}).parsed
-
-# 4) Example POST (token sent via Bearer header automatically)
-# Note: Replace the path/params with a real Instagram Graph API POST you need,
-# such as publishing media via the Graph API endpoints.
-# long_lived.post("/me/media", body: {image_url: "https://...", caption: "hello"})
-
-
-
-
-
Refresh Tokens
-
-
When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.
-
-
-
Manual refresh:
-
-
-
if access.expired?
- access = access.refresh
-end
-
-
-
-
Auto-refresh wrapper pattern:
-
-
-
class AutoRefreshingToken
- def initialize(token_provider, store: nil)
- @token = token_provider
- @store = store # e.g., something that responds to read/write for token data
- end
-
- def with(&blk)
- tok = ensure_fresh!
- blk ? blk.call(tok) : tok
- rescue OAuth2::Error => e
- # If a 401 suggests token invalidation, try one refresh and retry once
- if e.response && e.response.status == 401 && @token.refresh_token
- @token = @token.refresh
- @store.write(@token.to_hash) if @store
- retry
- end
- raise
- end
-
-private
-
- def ensure_fresh!
- if @token.expired? && @token.refresh_token
- @token = @token.refresh
- @store.write(@token.to_hash) if @store
- end
- @token
- end
-end
-
-# usage
-keeper = AutoRefreshingToken.new(access)
-keeper.with { |tok| tok.get("/v1/protected") }
-
-
-
Persist the token across processes using AccessToken#to_hash and AccessToken.from_hash(client, hash).
-
-
Token Revocation (RFC 7009)
-
-
You can revoke either the access token or the refresh token.
-
-
# Revoke the current access token
-access.revoke(token_type_hint: :access_token)
-
-# Or explicitly revoke the refresh token (often also invalidates associated access tokens)
-access.revoke(token_type_hint: :refresh_token)
-
-
-
Client Configuration Tips
-
-
Mutual TLS (mTLS) client authentication
-
-
Some providers require OAuth requests (including the token request and subsequent API calls) to be sender‑constrained using mutual TLS (mTLS). With this gem, you enable mTLS by providing a client certificate/private key to Faraday via connection_opts.ssl and, if your provider requires it for client authentication, selecting the tls_client_auth auth_scheme.
-
-
Example using PEM files (certificate and key):
-
-
require "oauth2"
-require "openssl"
-
-client = OAuth2::Client.new(
- ENV.fetch("CLIENT_ID"),
- ENV.fetch("CLIENT_SECRET"),
- site: "https://example.com",
- authorize_url: "/oauth/authorize/",
- token_url: "/oauth/token/",
- auth_scheme: :tls_client_auth, # if your AS requires mTLS-based client authentication
- connection_opts: {
- ssl: {
- client_cert: OpenSSL::X509::Certificate.new(File.read("localhost.pem")),
- client_key: OpenSSL::PKey::RSA.new(File.read("localhost-key.pem")),
- # Optional extras, uncomment as needed:
- # ca_file: "/path/to/ca-bundle.pem", # custom CA(s)
- # verify: true # enable server cert verification (recommended)
- },
- },
-)
-
-# Example token request (any grant type can be used). The mTLS handshake
-# will occur automatically on HTTPS calls using the configured cert/key.
-access = client.client_credentials.get_token
-
-# Subsequent resource requests will also use mTLS on HTTPS endpoints of `site`:
-resp = access.get("/v1/protected")
-
-
-
Notes:
-
-
-
Files must contain the appropriate PEMs. The private key may be encrypted; if so, pass a password to OpenSSL::PKey::RSA.new(File.read(path), ENV["KEY_PASSWORD"]).
-
If your certificate and key are in a PKCS#12/PFX bundle, you can load them like:
-
If your environment does not have system CAs, specify ca_file or ca_path inside the ssl: hash.
-
Keep verify: true in production. Set verify: false only for local testing.
-
-
-
Faraday adapter: Any adapter that supports Ruby’s OpenSSL should work. net_http (default) and net_http_persistent are common choices.
-
Scope of mTLS: The SSL client cert is applied to any HTTPS request made by this client (token and resource requests) to the configured site base URL (and absolute URLs you call with the same client).
-
OIDC tie-in: Some OPs require tls_client_auth at the token endpoint per OIDC/OAuth specifications. That is enabled via auth_scheme: :tls_client_auth as shown above.
client = OAuth2::Client.new(
- id,
- secret,
- site: "https://provider.example.com",
- connection_opts: {
- request: {open_timeout: 5, timeout: 15},
- proxy: ENV["HTTPS_PROXY"],
- ssl: {verify: true},
- },
-) do |faraday|
- faraday.request(:url_encoded)
- # faraday.response :logger, Logger.new($stdout) # see OAUTH_DEBUG below
- faraday.adapter(:net_http_persistent) # or any Faraday adapter you need
-end
-
-
-
Using flat query params (Faraday::FlatParamsEncoder)
-
-
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.
-
-
require "faraday"
-
-client = OAuth2::Client.new(
- id,
- secret,
- site: "https://api.example.com",
- # Pass Faraday connection options to make FlatParamsEncoder the default
- connection_opts: {
- request: {params_encoder: Faraday::FlatParamsEncoder},
- },
-) do |faraday|
- faraday.request(:url_encoded)
- faraday.adapter(:net_http)
-end
-
-access = client.client_credentials.get_token
-
-# Example of a GET with two flat filter params (not an array):
-# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000
-resp = access.get(
- "/v1/orders",
- params: {
- # Provide the values as an array; FlatParamsEncoder expands them as repeated keys
- filter: [
- "order.clientCreatedTime>1445006997000",
- "order.clientCreatedTime<1445611797000",
- ],
- },
-)
-
-
-
If you instead need to build a raw Faraday connection yourself, the equivalent configuration is:
If the token response includes an id_token (a JWT), this gem surfaces it in token.params['id_token'].
-
-Note: This gem does not validate the signature of the id_token. You must use a JWT library (like the jwtgem) and your provider’s JWKs to verify it.
-
For private_key_jwt client authentication, provide auth_scheme: :private_key_jwt and ensure your key configuration matches the provider requirements.
-
See OIDC.md for a more complete OIDC overview and examples.
-
-
-
Debugging
-
-
-
Set environment variable OAUTH_DEBUG=true to enable verbose Faraday logging (uses the client-provided logger).
-
To mirror a working curl request, ensure you set the same auth scheme, params, and content type. The Quick Example at the top shows a curl-to-ruby translation.
-
-
-
-
-
🦷 FLOSS Funding
-
-
While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding.
-Raising a monthly budget of… “dollars” would make the project more sustainable.
-
-
We welcome both individual and corporate sponsors! We also offer a
-wide array of funding channels to account for your preferences
-(although currently Open Collective is our preferred funding platform).
-
-
If you’re working in a company that’s making significant use of ruby-oauth tools we’d
-appreciate it if you suggest to your company to become a ruby-oauth sponsor.
If doing a sponsorship in the form of donation is problematic for your company from an accounting standpoint, we’d recommend the use of Tidelift, where you can get a support-like subscription instead.
-
-
-
-
-
Open Collective for Individuals
-
-
Support us with a monthly donation and help us continue our activities. [Become a backer]
I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small. Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions. I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈 cats).
-
-
If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in bundle fund.
-
-
I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
-
-
Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags
-
-
-
-
🔐 Security
-
-
To report a security vulnerability, please use the Tidelift security contact.
-Tidelift will coordinate the fix and disclosure.
If you need some ideas of where to help, you could work on adding more code coverage,
-or if it is already 💯 (see below) check reek, issues, or PRs,
-or use the gem and think about how it could be better.
This Library adheres to .
-Violations of this scheme should be reported as bugs.
-Specifically, if a minor or patch version is released that breaks backward compatibility,
-a new version should be immediately released that restores compatibility.
-Breaking changes to the public API will only be introduced with new major versions.
-
-
-
dropping support for a platform is both obviously and objectively a breaking change
I understand that policy doesn’t work universally (“exceptions to every rule!”),
-but it is the policy here.
-As such, in many cases it is good to specify a dependency on this library using
-the Pessimistic Version Constraint with two digits of precision.
-
-
For example:
-
-
spec.add_dependency("oauth2", "~> 2.0")
-
-
-
- 📌 Is "Platform Support" part of the public API? More details inside.
-
-
SemVer should, IMO, but doesn’t explicitly, say that dropping support for specific Platforms
-is a breaking change to an API, and for that reason the bike shedding is endless.
-
-
To get a better understanding of how SemVer is intended to work over a project’s lifetime,
-read this article from the creator of SemVer:
- Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.
-
-
-
-
🤑 A request for help
-
-
Maintainers have teeth and need to pay their dentists.
-After getting laid off in an RIF in March, and encountering difficulty finding a new one,
-I began spending most of my time building open source tools.
-I’m hoping to be able to pay for my kids’ health insurance this month,
-so if you value the work I am doing, I need your support.
-Please consider sponsoring me or the project.
-
-
To join the community or get help 👇️ Join the Discord.
-
-
-
-
To say “thanks!” ☝️ Join the Discord or 👇️ send money.
-
-
💌 💌 💌
-
-
Please give the project a star ⭐ ♥.
-
-
Thanks for RTFM. ☺️
-
-
-
- rel="me" Social Proofs
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/method_list.html b/docs/method_list.html
index dd8fb87a..e69de29b 100644
--- a/docs/method_list.html
+++ b/docs/method_list.html
@@ -1,742 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Method List
-
-
-
-
-
-
\ No newline at end of file
diff --git a/lib/oauth2.rb b/lib/oauth2.rb
index db9e94da..b89f72a5 100644
--- a/lib/oauth2.rb
+++ b/lib/oauth2.rb
@@ -10,7 +10,9 @@
# includes gem files
require_relative "oauth2/version"
+require_relative "oauth2/thing_filter"
require_relative "oauth2/filtered_attributes"
+require_relative "oauth2/sanitized_logger"
require_relative "oauth2/error"
require_relative "oauth2/authenticator"
require_relative "oauth2/client"
@@ -43,18 +45,40 @@ module OAuth2
# config[:silence_no_tokens_warning] = false
# end
#
+ # @example Customize filtered output markers and debug-log value filtering by key name
+ # OAuth2.configure do |config|
+ # config[:filtered_label] = "[REDACTED]"
+ # config[:filtered_debug_keys] += ["client_assertion"]
+ # end
+ #
+ # Existing objects and logger wrappers snapshot filtering configuration during
+ # initialization. Changing these config values later affects only newly
+ # initialized objects and debug loggers.
+ #
# @return [SnakyHash::SymbolKeyed] A mutable Hash-like config with symbol keys
DEFAULT_CONFIG = SnakyHash::SymbolKeyed.new(
silence_extra_tokens_warning: true,
silence_no_tokens_warning: true,
+ filtered_label: "[FILTERED]",
+ filtered_debug_keys: %w[
+ access_token
+ refresh_token
+ id_token
+ client_secret
+ assertion
+ code_verifier
+ token
+ ],
)
# The current runtime configuration for the library.
#
# @return [SnakyHash::SymbolKeyed]
+ CONFIG = DEFAULT_CONFIG.dup
+
class << self
def config
- @config ||= DEFAULT_CONFIG.dup
+ CONFIG
end
# Configure global library behavior.
diff --git a/lib/oauth2/client.rb b/lib/oauth2/client.rb
index 7c64c3c1..848524f2 100644
--- a/lib/oauth2/client.rb
+++ b/lib/oauth2/client.rb
@@ -42,7 +42,7 @@ class Client # rubocop:disable Metrics/ClassLength
# @option options [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday
# @option options [Boolean] :raise_errors (true) whether to raise an OAuth2::Error on responses with 400+ status codes
# @option options [Integer] :max_redirects (5) maximum number of redirects to follow
- # @option options [Logger] :logger (::Logger.new($stdout)) Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true
+ # @option options [Logger] :logger (::Logger.new($stdout)) Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true. When debug logging is enabled, sensitive values are filtered using a {ThingFilter} initialized from `OAuth2.config[:filtered_label]` and the key names in `OAuth2.config[:filtered_debug_keys]`.
# @option options [Class] :access_token_class (AccessToken) class to use for access tokens; you can subclass OAuth2::AccessToken, @version 2.0+
# @option options [Hash] :ssl SSL options for Faraday
#
@@ -563,7 +563,7 @@ def build_access_token_legacy(response, access_token_opts, extract_access_token)
end
def oauth_debug_logging(builder)
- builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG
+ builder.response(:logger, SanitizedLogger.new(options[:logger]), bodies: true) if OAuth2::OAUTH_DEBUG
end
end
end
diff --git a/lib/oauth2/error.rb b/lib/oauth2/error.rb
index bccbe193..550d4727 100644
--- a/lib/oauth2/error.rb
+++ b/lib/oauth2/error.rb
@@ -17,6 +17,8 @@ class Error < StandardError
# @param [OAuth2::Response, Hash, Object] response A Response or error payload
def initialize(response)
@response = response
+ @code = nil
+ @description = nil
if response.respond_to?(:parsed)
if response.parsed.is_a?(Hash)
@code = response.parsed["error"]
diff --git a/lib/oauth2/filtered_attributes.rb b/lib/oauth2/filtered_attributes.rb
index 71204621..dfee909f 100644
--- a/lib/oauth2/filtered_attributes.rb
+++ b/lib/oauth2/filtered_attributes.rb
@@ -1,17 +1,40 @@
+# frozen_string_literal: true
+
module OAuth2
- # Mixin that redacts sensitive instance variables in #inspect output.
+ # Mixin that redacts sensitive instance variables in `#inspect` output.
+ #
+ # Classes include this module and declare which attribute names should be
+ # filtered via {.filtered_attributes}. Matching and replacement behavior is
+ # delegated to {ThingFilter}, which is initialized once per object.
#
- # Classes include this module and declare which attributes should be filtered
- # using {.filtered_attributes}. Any instance variable name that includes one of
- # those attribute names will be shown as [FILTERED] in the object's inspect.
+ # This means existing objects keep the filter configuration that was present
+ # when they were initialized, even if global config or class-level filter
+ # declarations change later.
module FilteredAttributes
- # Hook invoked when the module is included. Extends the including class with
- # class-level helpers.
+ class << self
+ # Hook invoked when the module is included. Extends the including class with
+ # class-level helpers and prepends the initializer hook.
+ #
+ # @param [Class] base The including class
+ # @return [void]
+ def included(base)
+ base.extend(ClassMethods)
+ base.prepend(InitializerMethods)
+ end
+ end
+
+ # Initializer hook that snapshots the thing filter for this object.
#
- # @param [Class] base The including class
- # @return [void]
- def self.included(base)
- base.extend(ClassMethods)
+ # The snapshot captures both the class-level filtered attribute names and
+ # the current `OAuth2.config[:filtered_label]` value.
+ module InitializerMethods
+ def initialize(*args, &block)
+ super(*args, &block)
+ @thing_filter = ThingFilter.new(
+ self.class.filtered_attribute_names,
+ label: OAuth2.config[:filtered_label],
+ )
+ end
end
# Class-level helpers for configuring filtered attributes.
@@ -30,6 +53,8 @@ def filtered_attributes(base, *attributes)
# @param [Class] base The class to get filtered attributes for
# @return [Array]
def filtered_attribute_names(base)
+ return [] unless base.instance_variable_defined?(:@filtered_attribute_names)
+
base.instance_variable_get(:@filtered_attribute_names) || []
end
end
@@ -50,16 +75,24 @@ def filtered_attribute_names
end
end
+ # The initialized thing filter used by this object.
+ #
+ # This is a per-instance snapshot created during initialization.
+ #
+ # @return [ThingFilter]
+ def thing_filter
+ @thing_filter
+ end
+
# Custom inspect that redacts configured attributes.
#
# @return [String]
def inspect
- filtered_attribute_names = ClassMethods.filtered_attribute_names(self.class)
- return super if filtered_attribute_names.empty?
+ return super if thing_filter.things.empty?
inspected_vars = instance_variables.map do |var|
- if filtered_attribute_names.any? { |filtered_var| var.to_s.include?(filtered_var.to_s) }
- "#{var}=[FILTERED]"
+ if thing_filter.filtered?(var)
+ "#{var}=#{thing_filter.label}"
else
"#{var}=#{instance_variable_get(var).inspect}"
end
diff --git a/lib/oauth2/sanitized_logger.rb b/lib/oauth2/sanitized_logger.rb
new file mode 100644
index 00000000..3ae9ec1e
--- /dev/null
+++ b/lib/oauth2/sanitized_logger.rb
@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module OAuth2
+ # Logger wrapper that redacts sensitive values from debug output before
+ # delegating to the underlying logger instance.
+ #
+ # This class is intentionally narrow in scope: it only sanitizes string
+ # messages emitted through the debug logging path and leaves request/response
+ # behavior unchanged.
+ #
+ # The underlying {ThingFilter} is initialized once when the logger wrapper is
+ # created, so later config changes do not alter the behavior of existing
+ # logger instances.
+ class SanitizedLogger
+ # Create a new sanitized logger wrapper.
+ #
+ # @param [#add, #debug, #info, #warn, #error, #fatal, #unknown] logger
+ # The underlying logger instance that will receive sanitized messages.
+ #
+ # The debug filtering key list and replacement label are snapshotted from
+ # `OAuth2.config` during initialization.
+ def initialize(logger)
+ @logger = logger
+ @thing_filter = ThingFilter.new(
+ OAuth2.config[:filtered_debug_keys],
+ label: OAuth2.config[:filtered_label],
+ )
+ end
+
+ # Add a log entry after sanitizing any string payloads.
+ #
+ # @param [Integer, Symbol, String, nil] severity Logger severity
+ # @param [Object, nil] message Optional log message
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def add(severity, message = nil, progname = nil)
+ if block_given?
+ @logger.add(severity, sanitize(message), sanitize(progname)) { sanitize(yield) }
+ else
+ @logger.add(severity, sanitize(message), sanitize(progname))
+ end
+ end
+
+ # Append a message to the underlying logger after sanitization.
+ #
+ # @param [String] message Message to append
+ # @return [Object] The underlying logger result
+ def <<(message)
+ @logger << sanitize(message)
+ end
+
+ # Log a debug message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def debug(progname = nil, &block)
+ log(:debug, progname, &block)
+ end
+
+ # Log an info message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def info(progname = nil, &block)
+ log(:info, progname, &block)
+ end
+
+ # Log a warning message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def warn(progname = nil, &block)
+ log(:warn, progname, &block)
+ end
+
+ # Log an error message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def error(progname = nil, &block)
+ log(:error, progname, &block)
+ end
+
+ # Log a fatal message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def fatal(progname = nil, &block)
+ log(:fatal, progname, &block)
+ end
+
+ # Log an unknown-severity message after sanitization.
+ #
+ # @param [Object, nil] progname Optional program name
+ # @yieldreturn [Object] Deferred log message
+ # @return [Object] The underlying logger result
+ def unknown(progname = nil, &block)
+ log(:unknown, progname, &block)
+ end
+
+ # Close the underlying logger if supported.
+ #
+ # @return [void]
+ def close
+ @logger.close if @logger.respond_to?(:close)
+ end
+
+ # Access the formatter of the underlying logger if supported.
+ #
+ # @return [Object, nil]
+ def formatter
+ @logger.formatter if @logger.respond_to?(:formatter)
+ end
+
+ # Set the formatter of the underlying logger if supported.
+ #
+ # @param [Object] formatter Formatter object
+ # @return [void]
+ def formatter=(formatter)
+ @logger.formatter = formatter if @logger.respond_to?(:formatter=)
+ end
+
+ # Access the logger level if supported.
+ #
+ # @return [Object, nil]
+ def level
+ @logger.level if @logger.respond_to?(:level)
+ end
+
+ # Set the logger level if supported.
+ #
+ # @param [Object] level Logger level
+ # @return [void]
+ def level=(level)
+ @logger.level = level if @logger.respond_to?(:level=)
+ end
+
+ # Access the logger progname if supported.
+ #
+ # @return [Object, nil]
+ def progname
+ @logger.progname if @logger.respond_to?(:progname)
+ end
+
+ # Set the logger progname if supported.
+ #
+ # @param [Object] progname Logger progname
+ # @return [void]
+ def progname=(progname)
+ @logger.progname = progname if @logger.respond_to?(:progname=)
+ end
+
+ # Report support for methods provided by the wrapped logger.
+ #
+ # @param [Symbol] method_name Method name to check
+ # @param [Boolean] include_private Whether private methods are considered
+ # @return [Boolean]
+ def respond_to_missing?(method_name, include_private = false)
+ @logger.respond_to?(method_name, include_private) || super
+ end
+
+ # Delegate unsupported methods to the wrapped logger.
+ #
+ # @param [Symbol] method_name Method to invoke
+ # @param [Array
-AABBCC?style=for-the-badge&logo=ruby&logoColor=red){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=red){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=red){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink){kind=icon}
-AABBCC?style=for-the-badge&logo=ruby&logoColor=white){kind=icon}
- 
