diff --git a/CHANGELOG.md b/CHANGELOG.md index c576d7ed..9f8da0df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ Please file a bug if you notice a violation of semantic versioning. ### Added +- [gh!683][gh!683] Improve documentation by @pboling + ### Changed ### Deprecated @@ -30,6 +32,8 @@ Please file a bug if you notice a violation of semantic versioning. ### Security +[gh!683]: https://github.com/ruby-oauth/oauth2/pull/683 + ## [2.0.17] - 2025-09-15 - TAG: [v2.0.17][2.0.17t] @@ -41,6 +45,8 @@ Please file a bug if you notice a violation of semantic versioning. - [gh!682][gh!682] - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., {get: :query, post: :header}) +[gh!682]: https://github.com/ruby-oauth/oauth2/pull/682 + ## [2.0.16] - 2025-09-14 - TAG: [v2.0.16][2.0.16t] diff --git a/README.md b/README.md index 2f1019b5..a555249f 100644 --- a/README.md +++ b/README.md @@ -62,9 +62,10 @@ NOTE: `header` - The content type specified in the `curl` is already the default
-Complete E2E single file script against [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server) +Complete E2E single file script against mock-oauth2-server -- E2E example using the mock test server added in v2.0.11 +- E2E example uses [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), which was added in v2.0.11 +- E2E example does not ship with the released gem, so clone the source to play with it. ```console docker compose -f docker-compose-ssl.yml up -d --wait @@ -93,26 +94,26 @@ docker compose -f docker-compose-ssl.yml down Troubleshooting: validate connectivity to the mock server - Check container status and port mapping: - - docker compose -f docker-compose-ssl.yml ps + - `docker compose -f docker-compose-ssl.yml ps` - From the host, try the discovery URL directly (this is what the example uses by default): - - curl -v http://localhost:8080/default/.well-known/openid-configuration - - If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration -- From inside the container (to distinguish container vs host networking): - - docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration + - `curl -v http://localhost:8080/default/.well-known/openid-configuration` + - If that fails immediately, also try: `curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration` +- From inside the container (to distinguish container vs. host networking): + - `docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration` - Simple TCP probe from the host: - - nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"' + - `nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'` - Inspect which host port 8080 is bound to (should be 8080): - - docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1 + - `docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1` - Look at server logs for readiness/errors: - - docker logs -n 200 oauth2-mock-oauth2-server-1 + - `docker logs -n 200 oauth2-mock-oauth2-server-1` - On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking: - - ss -ltnp | grep :8080 + - `ss -ltnp | grep :8080` Notes -- Discovery URL pattern is: http://localhost:8080//.well-known/openid-configuration, where defaults to "default". +- Discovery URL pattern is: `http://localhost:8080//.well-known/openid-configuration`, where `` defaults to `default`. - You can change these with env vars when running the example: - - E2E_ISSUER_BASE (default: http://localhost:8080) - - E2E_REALM (default: default) + - `E2E_ISSUER_BASE` (default: http://localhost:8080) + - `E2E_REALM` (default: default)
@@ -144,7 +145,7 @@ If it seems like you are in the wrong place, you might try one of these: ### Compatibility -* Operating Systems: Linux, MacOS, Windows +* Operating Systems: Linux, macOS, Windows * MRI Ruby @ v2.3, v2.4, v2.5, v2.6, v2.7, v3.0, v3.1, v3.2, v3.3, v3.4, HEAD * NOTE: This gem may still _install_ and _run_ on ruby v2.2, but vanilla GitHub Actions no longer supports testing against it, so YMMV. Accept patches so long as they don't break the platforms that do run in CI. * JRuby @ v9.4, v10.0, HEAD @@ -213,7 +214,7 @@ The various versions of each are tested via the Ruby test matrix, along with wha * time * logger (removed from stdlib in Ruby 3.5 so added as runtime dependency in v2.0.10) -If you use a gem version of a core Ruby library it should work fine! +If you use a gem version of a core Ruby library, it should work fine! @@ -413,11 +414,11 @@ gem install oauth2
For Medium or High Security Installations -This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by +This gem is cryptographically signed and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by [stone_checksums][💎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: +Add my public key (if you haven’t already; will expire 2045-04-29) as a trusted certificate: ```console gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem) @@ -492,7 +493,7 @@ see [gemfiles/README.md](gemfiles/README.md), then submit a PR to the correct ma 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 +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 @@ -531,13 +532,13 @@ Some OAuth 2.0 standards legitimately have multiple tokens. You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in. Specify your custom class with the `access_token_class` option. -If you only need one token you can, as of v2.0.10, +If you only need one token, you can, as of v2.0.10, specify the exact token name you want to extract via the `OAuth2::AccessToken` using the `token_name` option. You'll likely need to do some source diving. This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas. -If you have time and energy please contribute to the documentation! +If you have time and energy, please contribute to the documentation! ## 🔧 Basic Usage @@ -558,7 +559,7 @@ response.class.name ### Relative `authorize_url` and `token_url` (Not on site root, Just Works!) -In 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. +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. ```ruby client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server") @@ -751,16 +752,18 @@ 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). +- `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}. + - 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 was added in v2.0.15 to support providers like Instagram that require query mode for GET and header mode for POST/DELETE. +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 diff --git a/docs/OAuth2.html b/docs/OAuth2.html index e60933d9..3e0fcdaf 100644 --- a/docs/OAuth2.html +++ b/docs/OAuth2.html @@ -415,7 +415,7 @@

diff --git a/docs/OAuth2/AccessToken.html b/docs/OAuth2/AccessToken.html index ebc602da..c83cc5ea 100644 --- a/docs/OAuth2/AccessToken.html +++ b/docs/OAuth2/AccessToken.html @@ -3083,7 +3083,7 @@

diff --git a/docs/OAuth2/Authenticator.html b/docs/OAuth2/Authenticator.html index 79af5249..5e899294 100644 --- a/docs/OAuth2/Authenticator.html +++ b/docs/OAuth2/Authenticator.html @@ -883,7 +883,7 @@

diff --git a/docs/OAuth2/Client.html b/docs/OAuth2/Client.html index 002faa94..af25fba5 100644 --- a/docs/OAuth2/Client.html +++ b/docs/OAuth2/Client.html @@ -2656,7 +2656,7 @@

diff --git a/docs/OAuth2/Error.html b/docs/OAuth2/Error.html index 85c0519a..42fb3123 100644 --- a/docs/OAuth2/Error.html +++ b/docs/OAuth2/Error.html @@ -772,7 +772,7 @@

diff --git a/docs/OAuth2/FilteredAttributes.html b/docs/OAuth2/FilteredAttributes.html index 1259edff..67a4aa42 100644 --- a/docs/OAuth2/FilteredAttributes.html +++ b/docs/OAuth2/FilteredAttributes.html @@ -335,7 +335,7 @@

diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/docs/OAuth2/FilteredAttributes/ClassMethods.html index 8059ded1..f09c5ff1 100644 --- a/docs/OAuth2/FilteredAttributes/ClassMethods.html +++ b/docs/OAuth2/FilteredAttributes/ClassMethods.html @@ -280,7 +280,7 @@

diff --git a/docs/OAuth2/Response.html b/docs/OAuth2/Response.html index 77602e6b..cc9ba6f4 100644 --- a/docs/OAuth2/Response.html +++ b/docs/OAuth2/Response.html @@ -1619,7 +1619,7 @@

diff --git a/docs/OAuth2/Strategy.html b/docs/OAuth2/Strategy.html index 3fb5311a..a674e081 100644 --- a/docs/OAuth2/Strategy.html +++ b/docs/OAuth2/Strategy.html @@ -107,7 +107,7 @@

Defined Under Namespace

diff --git a/docs/OAuth2/Strategy/Assertion.html b/docs/OAuth2/Strategy/Assertion.html index 7b9910f7..bafdf1de 100644 --- a/docs/OAuth2/Strategy/Assertion.html +++ b/docs/OAuth2/Strategy/Assertion.html @@ -481,7 +481,7 @@

diff --git a/docs/OAuth2/Strategy/AuthCode.html b/docs/OAuth2/Strategy/AuthCode.html index 16d22ff8..9509bcde 100644 --- a/docs/OAuth2/Strategy/AuthCode.html +++ b/docs/OAuth2/Strategy/AuthCode.html @@ -483,7 +483,7 @@

diff --git a/docs/OAuth2/Strategy/Base.html b/docs/OAuth2/Strategy/Base.html index 17a8748c..b6f5ffe6 100644 --- a/docs/OAuth2/Strategy/Base.html +++ b/docs/OAuth2/Strategy/Base.html @@ -195,7 +195,7 @@

diff --git a/docs/OAuth2/Strategy/ClientCredentials.html b/docs/OAuth2/Strategy/ClientCredentials.html index d703001b..f58a3e1e 100644 --- a/docs/OAuth2/Strategy/ClientCredentials.html +++ b/docs/OAuth2/Strategy/ClientCredentials.html @@ -343,7 +343,7 @@

diff --git a/docs/OAuth2/Strategy/Implicit.html b/docs/OAuth2/Strategy/Implicit.html index 14cab52b..0c5b11bc 100644 --- a/docs/OAuth2/Strategy/Implicit.html +++ b/docs/OAuth2/Strategy/Implicit.html @@ -420,7 +420,7 @@

diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html index 5b8b0abe..5ec03d21 100644 --- a/docs/OAuth2/Strategy/Password.html +++ b/docs/OAuth2/Strategy/Password.html @@ -374,7 +374,7 @@

diff --git a/docs/OAuth2/Version.html b/docs/OAuth2/Version.html index 0f77a1a2..14bb7a4c 100644 --- a/docs/OAuth2/Version.html +++ b/docs/OAuth2/Version.html @@ -111,7 +111,7 @@

diff --git a/docs/_index.html b/docs/_index.html index 830e48cd..ceaf684e 100644 --- a/docs/_index.html +++ b/docs/_index.html @@ -111,25 +111,31 @@

File Listing

  • oauth2-2.0.16.gem
    • -
  • oauth2-2.0.10.gem
    • +
  • oauth2-2.0.17.gem
    • -
  • oauth2-2.0.11.gem
    • +
  • oauth2-2.0.10.gem
    • -
  • oauth2-2.0.12.gem
    • +
  • oauth2-2.0.11.gem
    • -
  • oauth2-2.0.13.gem
    • +
  • oauth2-2.0.12.gem
    • -
  • oauth2-2.0.14.gem
    • +
  • oauth2-2.0.13.gem
    • -
  • oauth2-2.0.15.gem
    • +
  • oauth2-2.0.14.gem
    • + + +
  • oauth2-2.0.15.gem
    • + + +
  • oauth2-2.0.16.gem
    • -
  • oauth2-2.0.16.gem
    • +
  • oauth2-2.0.17.gem
  • REEK
    • @@ -384,7 +390,7 @@

    Namespace Listing A-Z

    diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html index 302c0b51..6896d328 100644 --- a/docs/file.CHANGELOG.html +++ b/docs/file.CHANGELOG.html @@ -72,6 +72,11 @@

    Added

    + +

    Changed

    Deprecated

    @@ -96,7 +101,8 @@

    Added

      -
    • [gh!682][gh!682] - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., :query, post: :header)
      • +
    • +gh!682 - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., :query, post: :header)

    @@ -1274,7 +1280,7 @@

    diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html index 798db503..1641271f 100644 --- a/docs/file.CITATION.html +++ b/docs/file.CITATION.html @@ -82,7 +82,7 @@ diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html index 477f470f..1ba415b5 100644 --- a/docs/file.CODE_OF_CONDUCT.html +++ b/docs/file.CODE_OF_CONDUCT.html @@ -191,7 +191,7 @@

    Attribution

    diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html index 357fcd9d..7753fe72 100644 --- a/docs/file.CONTRIBUTING.html +++ b/docs/file.CONTRIBUTING.html @@ -308,7 +308,7 @@

    Manual process

    diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html index 94f053d3..6482a6ba 100644 --- a/docs/file.FUNDING.html +++ b/docs/file.FUNDING.html @@ -104,7 +104,7 @@

    Another Way to Support Open diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html index 724956cf..bc3e8fef 100644 --- a/docs/file.LICENSE.html +++ b/docs/file.LICENSE.html @@ -60,7 +60,7 @@
    MIT License

    Copyright (c) 2017-2025 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.
    diff --git a/docs/file.OIDC.html b/docs/file.OIDC.html index 1c150afa..93c12ff0 100644 --- a/docs/file.OIDC.html +++ b/docs/file.OIDC.html @@ -247,7 +247,7 @@

    Raw OIDC with ruby-oauth/oauth2

    diff --git a/docs/file.README.html b/docs/file.README.html index c1b750ff..e69c42b7 100644 --- a/docs/file.README.html +++ b/docs/file.README.html @@ -114,9 +114,10 @@

    Quick Examples

    -Complete E2E single file script against [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server) +Complete E2E single file script against mock-oauth2-server -- E2E example using the mock test server added in v2.0.11 +- E2E example uses [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), which was added in v2.0.11 +- E2E example does not ship with the released gem, so clone the source to play with it. ```console docker compose -f docker-compose-ssl.yml up -d --wait @@ -145,26 +146,26 @@

    Quick Examples

    Troubleshooting: validate connectivity to the mock server - Check container status and port mapping: - - docker compose -f docker-compose-ssl.yml ps + - `docker compose -f docker-compose-ssl.yml ps` - From the host, try the discovery URL directly (this is what the example uses by default): - - curl -v http://localhost:8080/default/.well-known/openid-configuration - - If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration -- From inside the container (to distinguish container vs host networking): - - docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration + - `curl -v http://localhost:8080/default/.well-known/openid-configuration` + - If that fails immediately, also try: `curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration` +- From inside the container (to distinguish container vs. host networking): + - `docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration` - Simple TCP probe from the host: - - nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"' + - `nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'` - Inspect which host port 8080 is bound to (should be 8080): - - docker inspect -f '(index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }' oauth2-mock-oauth2-server-1 + - `docker inspect -f '(index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }' oauth2-mock-oauth2-server-1` - Look at server logs for readiness/errors: - - docker logs -n 200 oauth2-mock-oauth2-server-1 + - `docker logs -n 200 oauth2-mock-oauth2-server-1` - On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking: - - ss -ltnp | grep :8080 + - `ss -ltnp | grep :8080` Notes -- Discovery URL pattern is: http://localhost:8080//.well-known/openid-configuration, where defaults to "default". +- Discovery URL pattern is: `http://localhost:8080//.well-known/openid-configuration`, where `` defaults to `default`. - You can change these with env vars when running the example: - - E2E_ISSUER_BASE (default: http://localhost:8080) - - E2E_REALM (default: default) + - `E2E_ISSUER_BASE` (default: http://localhost:8080) + - `E2E_REALM` (default: default) </details> @@ -196,7 +197,7 @@

    Quick Examples

    ### Compatibility -* Operating Systems: Linux, MacOS, Windows +* Operating Systems: Linux, macOS, Windows * MRI Ruby @ v2.3, v2.4, v2.5, v2.6, v2.7, v3.0, v3.1, v3.2, v3.3, v3.4, HEAD * NOTE: This gem may still _install_ and _run_ on ruby v2.2, but vanilla GitHub Actions no longer supports testing against it, so YMMV. Accept patches so long as they don't break the platforms that do run in CI. * JRuby @ v9.4, v10.0, HEAD @@ -265,7 +266,7 @@

    Quick Examples

    * time * logger (removed from stdlib in Ruby 3.5 so added as runtime dependency in v2.0.10) -If you use a gem version of a core Ruby library it should work fine! +If you use a gem version of a core Ruby library, it should work fine!
    @@ -465,11 +466,11 @@

    Quick Examples

    For Medium or High Security Installations -This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by +This gem is cryptographically signed and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by [stone_checksums][💎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: +Add my public key (if you haven’t already; will expire 2045-04-29) as a trusted certificate: ```console gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem) @@ -544,7 +545,7 @@

    Quick Examples

    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 +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 @@ -583,13 +584,13 @@

    Quick Examples

    You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in. Specify your custom class with the `access_token_class` option. -If you only need one token you can, as of v2.0.10, +If you only need one token, you can, as of v2.0.10, specify the exact token name you want to extract via the `OAuth2::AccessToken` using the `token_name` option. You'll likely need to do some source diving. This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas. -If you have time and energy please contribute to the documentation! +If you have time and energy, please contribute to the documentation! ## 🔧 Basic Usage @@ -610,7 +611,7 @@

    Quick Examples

    ### Relative `authorize_url` and `token_url` (Not on site root, Just Works!) -In 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. +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. ```ruby client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server") @@ -803,16 +804,18 @@

    Quick Examples

    `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). +- `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: :query, post: :header, delete: :header. + - a `Proc` taking `|verb|` and returning `:header` or `:query`, or + - a `Hash` with verb symbols as keys, for example `:query, post: :header, delete: :header`. -Note: Verb-dependent mode was added in v2.0.15 to support providers like Instagram that require query mode for GET and header mode for POST/DELETE. +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 @@ -1724,7 +1727,7 @@

    Quick Examples

    diff --git a/docs/file.REEK.html b/docs/file.REEK.html index 194b0183..94ca44fa 100644 --- a/docs/file.REEK.html +++ b/docs/file.REEK.html @@ -61,7 +61,7 @@ diff --git a/docs/file.RUBOCOP.html b/docs/file.RUBOCOP.html index 374b63fa..8ebb7fa4 100644 --- a/docs/file.RUBOCOP.html +++ b/docs/file.RUBOCOP.html @@ -161,7 +161,7 @@

    Benefits of rubocop_gradual

    diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html index f5d6b05d..a85a26ad 100644 --- a/docs/file.SECURITY.html +++ b/docs/file.SECURITY.html @@ -91,7 +91,7 @@

    Additional Support

    diff --git a/docs/file.access_token.html b/docs/file.access_token.html index cadab659..581ce7a2 100644 --- a/docs/file.access_token.html +++ b/docs/file.access_token.html @@ -84,7 +84,7 @@ diff --git a/docs/file.authenticator.html b/docs/file.authenticator.html index 9984a34b..e9266862 100644 --- a/docs/file.authenticator.html +++ b/docs/file.authenticator.html @@ -81,7 +81,7 @@ diff --git a/docs/file.client.html b/docs/file.client.html index 5e19362d..679d9745 100644 --- a/docs/file.client.html +++ b/docs/file.client.html @@ -111,7 +111,7 @@ diff --git a/docs/file.error.html b/docs/file.error.html index 1f383acd..2dc3063a 100644 --- a/docs/file.error.html +++ b/docs/file.error.html @@ -68,7 +68,7 @@ diff --git a/docs/file.filtered_attributes.html b/docs/file.filtered_attributes.html index 62841903..497b0bc1 100644 --- a/docs/file.filtered_attributes.html +++ b/docs/file.filtered_attributes.html @@ -66,7 +66,7 @@ diff --git a/docs/file.oauth2-2.0.10.gem.html b/docs/file.oauth2-2.0.10.gem.html index d0a6124f..4ad3a95e 100644 --- a/docs/file.oauth2-2.0.10.gem.html +++ b/docs/file.oauth2-2.0.10.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.11.gem.html b/docs/file.oauth2-2.0.11.gem.html index d4df7513..ba8afba3 100644 --- a/docs/file.oauth2-2.0.11.gem.html +++ b/docs/file.oauth2-2.0.11.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.12.gem.html b/docs/file.oauth2-2.0.12.gem.html index b87f95e8..38b648c7 100644 --- a/docs/file.oauth2-2.0.12.gem.html +++ b/docs/file.oauth2-2.0.12.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.13.gem.html b/docs/file.oauth2-2.0.13.gem.html index 0001dcc6..7675b534 100644 --- a/docs/file.oauth2-2.0.13.gem.html +++ b/docs/file.oauth2-2.0.13.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.14.gem.html b/docs/file.oauth2-2.0.14.gem.html index bfa78aab..75e0e4f0 100644 --- a/docs/file.oauth2-2.0.14.gem.html +++ b/docs/file.oauth2-2.0.14.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.15.gem.html b/docs/file.oauth2-2.0.15.gem.html index ca7f8c53..acc6d04b 100644 --- a/docs/file.oauth2-2.0.15.gem.html +++ b/docs/file.oauth2-2.0.15.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.16.gem.html b/docs/file.oauth2-2.0.16.gem.html index 1233eca9..645dfeec 100644 --- a/docs/file.oauth2-2.0.16.gem.html +++ b/docs/file.oauth2-2.0.16.gem.html @@ -61,7 +61,7 @@ diff --git a/docs/file.oauth2-2.0.17.gem.html b/docs/file.oauth2-2.0.17.gem.html new file mode 100644 index 00000000..1bd99aa2 --- /dev/null +++ b/docs/file.oauth2-2.0.17.gem.html @@ -0,0 +1,71 @@ + + + + + + + File: oauth2-2.0.17.gem + + — Documentation by YARD 0.9.37 + + + + + + + + + + + + + + + + + +
    + +
    +
    + +
    + + +

    6385dfb2d4cb0309745de2d442d99c6148744abaca5599bd1e4f6038e99734d9cf90d1de83d1833e416e2682f0e3d6ae83e10a5a55d6e884b9cdc54e6070fb8b

    +
    + + + +
    + + \ No newline at end of file diff --git a/docs/file.oauth2.html b/docs/file.oauth2.html index 0b984e14..c948f189 100644 --- a/docs/file.oauth2.html +++ b/docs/file.oauth2.html @@ -69,7 +69,7 @@ diff --git a/docs/file.response.html b/docs/file.response.html index ef3c596d..eeb77a37 100644 --- a/docs/file.response.html +++ b/docs/file.response.html @@ -77,7 +77,7 @@ diff --git a/docs/file.strategy.html b/docs/file.strategy.html index 799d823a..355274e6 100644 --- a/docs/file.strategy.html +++ b/docs/file.strategy.html @@ -93,7 +93,7 @@ diff --git a/docs/file.version.html b/docs/file.version.html index 2105ed13..ed83c163 100644 --- a/docs/file.version.html +++ b/docs/file.version.html @@ -65,7 +65,7 @@ diff --git a/docs/file_list.html b/docs/file_list.html index ef094c1a..e0fe7d43 100644 --- a/docs/file_list.html +++ b/docs/file_list.html @@ -132,41 +132,51 @@

    File List

    -
  • +
  • +
    oauth2-2.0.17.gem
    +
    • + + +
  • oauth2-2.0.10.gem
    • -
  • +
  • oauth2-2.0.11.gem
    • -
  • +
  • oauth2-2.0.12.gem
    • -
  • +
  • oauth2-2.0.13.gem
    • -
  • +
  • oauth2-2.0.14.gem
    • -
  • +
  • oauth2-2.0.15.gem
    • -
  • +
  • oauth2-2.0.16.gem
    • +
  • +
    oauth2-2.0.17.gem
    +
    • + +
  • REEK
    • diff --git a/docs/index.html b/docs/index.html index 26f9a51e..2ac32ab5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -114,9 +114,10 @@

    Quick Examples

    -Complete E2E single file script against [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server) +Complete E2E single file script against mock-oauth2-server -- E2E example using the mock test server added in v2.0.11 +- E2E example uses [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), which was added in v2.0.11 +- E2E example does not ship with the released gem, so clone the source to play with it. ```console docker compose -f docker-compose-ssl.yml up -d --wait @@ -145,26 +146,26 @@

    Quick Examples

    Troubleshooting: validate connectivity to the mock server - Check container status and port mapping: - - docker compose -f docker-compose-ssl.yml ps + - `docker compose -f docker-compose-ssl.yml ps` - From the host, try the discovery URL directly (this is what the example uses by default): - - curl -v http://localhost:8080/default/.well-known/openid-configuration - - If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration -- From inside the container (to distinguish container vs host networking): - - docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration + - `curl -v http://localhost:8080/default/.well-known/openid-configuration` + - If that fails immediately, also try: `curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration` +- From inside the container (to distinguish container vs. host networking): + - `docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration` - Simple TCP probe from the host: - - nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"' + - `nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'` - Inspect which host port 8080 is bound to (should be 8080): - - docker inspect -f '(index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }' oauth2-mock-oauth2-server-1 + - `docker inspect -f '(index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }' oauth2-mock-oauth2-server-1` - Look at server logs for readiness/errors: - - docker logs -n 200 oauth2-mock-oauth2-server-1 + - `docker logs -n 200 oauth2-mock-oauth2-server-1` - On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking: - - ss -ltnp | grep :8080 + - `ss -ltnp | grep :8080` Notes -- Discovery URL pattern is: http://localhost:8080//.well-known/openid-configuration, where defaults to "default". +- Discovery URL pattern is: `http://localhost:8080//.well-known/openid-configuration`, where `` defaults to `default`. - You can change these with env vars when running the example: - - E2E_ISSUER_BASE (default: http://localhost:8080) - - E2E_REALM (default: default) + - `E2E_ISSUER_BASE` (default: http://localhost:8080) + - `E2E_REALM` (default: default) </details> @@ -196,7 +197,7 @@

    Quick Examples

    ### Compatibility -* Operating Systems: Linux, MacOS, Windows +* Operating Systems: Linux, macOS, Windows * MRI Ruby @ v2.3, v2.4, v2.5, v2.6, v2.7, v3.0, v3.1, v3.2, v3.3, v3.4, HEAD * NOTE: This gem may still _install_ and _run_ on ruby v2.2, but vanilla GitHub Actions no longer supports testing against it, so YMMV. Accept patches so long as they don't break the platforms that do run in CI. * JRuby @ v9.4, v10.0, HEAD @@ -265,7 +266,7 @@

    Quick Examples

    * time * logger (removed from stdlib in Ruby 3.5 so added as runtime dependency in v2.0.10) -If you use a gem version of a core Ruby library it should work fine! +If you use a gem version of a core Ruby library, it should work fine!
    @@ -465,11 +466,11 @@

    Quick Examples

    For Medium or High Security Installations -This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by +This gem is cryptographically signed and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by [stone_checksums][💎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: +Add my public key (if you haven’t already; will expire 2045-04-29) as a trusted certificate: ```console gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem) @@ -544,7 +545,7 @@

    Quick Examples

    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 +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 @@ -583,13 +584,13 @@

    Quick Examples

    You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in. Specify your custom class with the `access_token_class` option. -If you only need one token you can, as of v2.0.10, +If you only need one token, you can, as of v2.0.10, specify the exact token name you want to extract via the `OAuth2::AccessToken` using the `token_name` option. You'll likely need to do some source diving. This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas. -If you have time and energy please contribute to the documentation! +If you have time and energy, please contribute to the documentation! ## 🔧 Basic Usage @@ -610,7 +611,7 @@

    Quick Examples

    ### Relative `authorize_url` and `token_url` (Not on site root, Just Works!) -In 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. +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. ```ruby client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server") @@ -803,16 +804,18 @@

    Quick Examples

    `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). +- `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: :query, post: :header, delete: :header. + - a `Proc` taking `|verb|` and returning `:header` or `:query`, or + - a `Hash` with verb symbols as keys, for example `:query, post: :header, delete: :header`. -Note: Verb-dependent mode was added in v2.0.15 to support providers like Instagram that require query mode for GET and header mode for POST/DELETE. +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 @@ -1724,7 +1727,7 @@

    Quick Examples

    diff --git a/docs/top-level-namespace.html b/docs/top-level-namespace.html index b624c656..47e1417a 100644 --- a/docs/top-level-namespace.html +++ b/docs/top-level-namespace.html @@ -100,7 +100,7 @@

    Defined Under Namespace