oauth2 1.4.9 → 2.0.2

data/README.md

@@ -1,8 +1,8 @@
 <p align="center">
-    <a href="http://oauth.net/2/" target="_blank" rel="noopener noreferrer">
+    <a href="http://oauth.net/2/" target="_blank" rel="noopener">
       <img src="https://github.com/oauth-xx/oauth2/raw/master/docs/images/logo/oauth2-logo-124px.png?raw=true" alt="OAuth 2.0 Logo by Chris Messina, CC BY-SA 3.0">
     </a>
-    <a href="https://www.ruby-lang.org/" target="_blank" rel="noopener noreferrer">
+    <a href="https://www.ruby-lang.org/" target="_blank" rel="noopener">
       <img width="124px" src="https://github.com/oauth-xx/oauth2/raw/master/docs/images/logo/ruby-logo-198px.svg?raw=true" alt="Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5">
     </a>
 </p>
@@ -15,29 +15,36 @@ OAuth 2.0 focuses on client developer simplicity while providing specific author
 This is a RubyGem for implementing OAuth 2.0 clients and servers in Ruby applications.
 See the sibling `oauth` gem for OAuth 1.0 implementations in Ruby.
 
-⚠️ **_WARNING_**: You are viewing the `README` of the soon-to-be-deprecated `1-4-stable`
-branch which for version 1.4.x releases. Version 2.0 is coming! ⚠️
-
 ---
 
 * [OAuth 2.0 Spec][oauth2-spec]
-* [OAuth 1.0 sibling gem][sibling-gem]
-* Help us finish release [![2.0.0 release milestone][next-milestone-pct-img]][next-milestone-pct] by submitting or reviewing PRs and issues.
-* Oauth2 gem is _always_ looking for additional maintainers. See [#307][maintainers-discussion].
+* [oauth sibling gem][sibling-gem] for OAuth 1.0 implementations in Ruby.
 
 [oauth2-spec]: https://oauth.net/2/
 [sibling-gem]: https://github.com/oauth-xx/oauth-ruby
-[next-milestone-pct]: https://github.com/oauth-xx/oauth2/milestone/1
-[next-milestone-pct-img]: https://img.shields.io/github/milestones/progress-percent/oauth-xx/oauth2/1
-[maintainers-discussion]: https://github.com/oauth-xx/oauth2/issues/307
 
 ## Release Documentation
 
+### Version 2.0.x
+
+<details>
+  <summary>2.0.x Readmes</summary>
+
+| Version | Release Date | Readme                                                   |
+|---------|--------------|----------------------------------------------------------|
+| 2.0.2   | 2022-06-24   | https://github.com/oauth-xx/oauth2/blob/v2.0.2/README.md |
+| 2.0.1   | 2022-06-22   | https://github.com/oauth-xx/oauth2/blob/v2.0.1/README.md |
+| 2.0.0   | 2022-06-21   | https://github.com/oauth-xx/oauth2/blob/v2.0.0/README.md |
+</details>
+
+### Older Releases
+
 <details>
   <summary>1.4.x Readmes</summary>
 
 | Version | Release Date | Readme                                                   |
 |---------|--------------|----------------------------------------------------------|
+| 1.4.9   | Feb 20, 2022 | https://github.com/oauth-xx/oauth2/blob/v1.4.9/README.md |
 | 1.4.8   | Feb 18, 2022 | https://github.com/oauth-xx/oauth2/blob/v1.4.8/README.md |
 | 1.4.7   | Mar 19, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.7/README.md |
 | 1.4.6   | Mar 19, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.6/README.md |
@@ -69,6 +76,8 @@ branch which for version 1.4.x releases. Version 2.0 is coming! ⚠️
 | < 1.0.0  | Find here    | https://github.com/oauth-xx/oauth2/tags                  |
 </details>
 
+## Status
+
 <!--
 Numbering rows and badges in each row as a visual "database" lookup,
     as the table is extremely dense, and it can be very difficult to find anything
@@ -91,17 +100,20 @@ badge #s:
 🖐
 🧮
 📗
+
+appended indicators:
+♻️ - URL needs to be updated from SASS integration. Find / Replace is insufficient.
 -->
 
-|     | Project               | oauth2                                                                                                                                                                                                                                                              |
-|:----|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 1️⃣ | name, license, docs   | [![RubyGems.org][⛳️name-img]][⛳️gem] [![License: MIT][🖇src-license-img]][🖇src-license] [![FOSSA][🏘fossa-img]][🏘fossa] [![RubyDoc.info][🚎yard-img]][🚎yard] [![InchCI][🖐inch-ci-img]][🚎yard]                                                                  |
-| 2️⃣ | version & activity    | [![Gem Version][⛳️version-img]][⛳️gem] [![Total Downloads][🖇DL-total-img]][⛳️gem] [![Download Rank][🏘DL-rank-img]][⛳️gem] [![Source Code][🚎src-home-img]][🚎src-home] [![Open PRs][🖐prs-open-img]][🖐prs-open] [![Closed PRs][🧮prs-closed-img]][🧮prs-closed]  |
-| 3️⃣ | maintanence & linting | [![Maintainability][⛳cclim-maint-img]][⛳cclim-maint] [![Helpers][🖇triage-help-img]][🖇triage-help] [![Depfu][🏘depfu-img]][🏘depfu] [![Contributors][🚎contributors-img]][🚎contributors] [![Style][🖐style-wf-img]][🖐style-wf] [![Kloc Roll][🧮kloc-img]][🧮kloc] |
-| 4️⃣ | testing               | [![Build][⛳️tot-bld-img]][⛳️tot-bld] [![supported][🖇supported-wf-img]][🖇supported-wf] [![EOL & Code Coverage Build][🏘eol-wf-img]][🏘eol-wf] [![unsupported][🚎unsupported-wf-img]][🚎unsupported-wf]                                                             |
-| 5️⃣ | coverage & security   | [![CodeClimate][⛳cclim-cov-img]][⛳cclim-cov] [![CodeCov][🖇codecov-img]][🖇codecov] [![Coveralls][🏘coveralls-img]][🏘coveralls] [![Security Policy][🚎sec-pol-img]][🚎sec-pol] [![CodeQL][🖐codeQL-img]][🖐codeQL]                                                 |
-| 6️⃣ | resources             | [![Discussion][⛳gh-discussions-img]][⛳gh-discussions] [![Get help on Codementor][🖇codementor-img]][🖇codementor] [![Chat][🏘chat-img]][🏘chat] [![Blog][🚎blog-img]][🚎blog] [![Blog][🖐wiki-img]][🖐wiki]                                                         |
-| 7️⃣ | spread 💖             | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Tweet @ Peter][🏘tweet-img]][🏘tweet] [🌏][aboutme] [👼][angelme] [💻][coderme] [🌹][politicme]                                                                     |
+|     | Project               | bundle add oauth2                                                                                                                                                                                                                                                                            |
+|:----|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1️⃣ | name, license, docs   | [![RubyGems.org][⛳️name-img]][⛳️gem] [![License: MIT][🖇src-license-img]][🖇src-license] [![FOSSA][🏘fossa-img]][🏘fossa] [![RubyDoc.info][🚎yard-img]][🚎yard] [![InchCI][🖐inch-ci-img]][🚎yard]                                                                                           |
+| 2️⃣ | version & activity    | [![Gem Version][⛳️version-img]][⛳️gem] [![Total Downloads][🖇DL-total-img]][⛳️gem] [![Download Rank][🏘DL-rank-img]][⛳️gem] [![Source Code][🚎src-home-img]][🚎src-home] [![Open PRs][🖐prs-o-img]][🖐prs-o] [![Closed PRs][🧮prs-c-img]][🧮prs-c] [![Next Version][📗next-img♻️]][📗next♻️] |
+| 3️⃣ | maintanence & linting | [![Maintainability][⛳cclim-maint-img♻️]][⛳cclim-maint] [![Helpers][🖇triage-help-img]][🖇triage-help] [![Depfu][🏘depfu-img♻️]][🏘depfu♻️] [![Contributors][🚎contributors-img]][🚎contributors] [![Style][🖐style-wf-img]][🖐style-wf] [![Kloc Roll][🧮kloc-img]][🧮kloc]                   |
+| 4️⃣ | testing               | [![Open Issues][⛳iss-o-img]][⛳iss-o] [![Closed Issues][🖇iss-c-img]][🖇iss-c] [![Supported][🏘sup-wf-img]][🏘sup-wf] [![Heads][🚎heads-wf-img]][🚎heads-wf] [![Unofficial Support][🖐uns-wf-img]][🖐uns-wf] [![MacOS][🧮mac-wf-img]][🧮mac-wf] [![Windows][📗win-wf-img]][📗win-wf]          |
+| 5️⃣ | coverage & security   | [![CodeClimate][⛳cclim-cov-img♻️]][⛳cclim-cov] [![CodeCov][🖇codecov-img♻️]][🖇codecov] [![Coveralls][🏘coveralls-img]][🏘coveralls] [![Security Policy][🚎sec-pol-img]][🚎sec-pol] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Code Coverage][🧮cov-wf-img]][🧮cov-wf]                           |
+| 6️⃣ | resources             | [![Discussion][⛳gh-discussions-img]][⛳gh-discussions] [![Get help on Codementor][🖇codementor-img]][🖇codementor] [![Chat][🏘chat-img]][🏘chat] [![Blog][🚎blog-img]][🚎blog] [![Blog][🖐wiki-img]][🖐wiki]                                                                                  |
+| 7️⃣ | spread 💖             | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Tweet @ Peter][🏘tweet-img]][🏘tweet] [🌏][aboutme] [👼][angelme] [💻][coderme] [🌹][politicme]                                                                                              |
 
 <!--
 The link tokens in the following sections should be kept ordered by the row and badge numbering scheme
@@ -124,18 +136,20 @@ The link tokens in the following sections should be kept ordered by the row and
 [🏘DL-rank-img]: https://img.shields.io/gem/rt/oauth2.svg
 [🚎src-home]: https://github.com/oauth-xx/oauth2
 [🚎src-home-img]: https://img.shields.io/badge/source-github-brightgreen.svg?style=flat
-[🖐prs-open]: https://github.com/oauth-xx/oauth2/pulls
-[🖐prs-open-img]: https://img.shields.io/github/issues-pr/oauth-xx/oauth2
-[🧮prs-closed]: https://github.com/oauth-xx/oauth2/pulls?q=is%3Apr+is%3Aclosed
-[🧮prs-closed-img]: https://img.shields.io/github/issues-pr-closed/oauth-xx/oauth2
+[🖐prs-o]: https://github.com/oauth-xx/oauth2/pulls
+[🖐prs-o-img]: https://img.shields.io/github/issues-pr/oauth-xx/oauth2
+[🧮prs-c]: https://github.com/oauth-xx/oauth2/pulls?q=is%3Apr+is%3Aclosed
+[🧮prs-c-img]: https://img.shields.io/github/issues-pr-closed/oauth-xx/oauth2
+[📗next♻️]: https://github.com/oauth-xx/oauth2/milestone/14
+[📗next-img♻️]: https://img.shields.io/github/milestones/progress/oauth-xx/oauth2/14?label=Next%20Version
 
 <!-- 3️⃣ maintanence & linting -->
 [⛳cclim-maint]: https://codeclimate.com/github/oauth-xx/oauth2/maintainability
-[⛳cclim-maint-img]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/maintainability
+[⛳cclim-maint-img♻️]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/maintainability
 [🖇triage-help]: https://www.codetriage.com/oauth-xx/oauth2
 [🖇triage-help-img]: https://www.codetriage.com/oauth-xx/oauth2/badges/users.svg
-[🏘depfu]: https://depfu.com/github/oauth-xx/oauth2?project_id=4445
-[🏘depfu-img]: https://badges.depfu.com/badges/6d34dc1ba682bbdf9ae2a97848241743/count.svg
+[🏘depfu♻️]: https://depfu.com/github/oauth-xx/oauth2?project_id=4445
+[🏘depfu-img♻️]: https://badges.depfu.com/badges/6d34dc1ba682bbdf9ae2a97848241743/count.svg
 [🚎contributors]: https://github.com/oauth-xx/oauth2/graphs/contributors
 [🚎contributors-img]: https://img.shields.io/github/contributors-anon/oauth-xx/oauth2
 [🖐style-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/style.yml
@@ -144,28 +158,34 @@ The link tokens in the following sections should be kept ordered by the row and
 [🧮kloc-img]: https://img.shields.io/tokei/lines/github.com/oauth-xx/oauth2
 
 <!-- 4️⃣ testing -->
-[⛳️tot-bld]: https://actions-badge.atrox.dev/oauth-xx/oauth2/goto
-[⛳️tot-bld-img]: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Foauth-xx%2Foauth2%2Fbadge&style=flat
-[🖇supported-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml
-[🖇supported-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml/badge.svg
-[🏘eol-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml
-[🏘eol-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml/badge.svg
-[🚎unsupported-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml
-[🚎unsupported-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml/badge.svg
-[🖐issues]: https://github.com/oauth-xx/oauth2/issues
-[🖐issues-img]: https://github.com/oauth-xx/oauth2/issues
+[⛳iss-o]: https://github.com/oauth-xx/oauth2/issues
+[⛳iss-o-img]: https://img.shields.io/github/issues-raw/oauth-xx/oauth2
+[🖇iss-c]: https://github.com/oauth-xx/oauth2/issues?q=is%3Aissue+is%3Aclosed
+[🖇iss-c-img]: https://img.shields.io/github/issues-closed-raw/oauth-xx/oauth2
+[🏘sup-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml
+[🏘sup-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml/badge.svg
+[🚎heads-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/heads.yml
+[🚎heads-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/heads.yml/badge.svg
+[🖐uns-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml
+[🖐uns-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml/badge.svg
+[🧮mac-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/macos.yml
+[🧮mac-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/macos.yml/badge.svg
+[📗win-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/windows.yml
+[📗win-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/windows.yml/badge.svg
 
 <!-- 5️⃣ coverage & security -->
 [⛳cclim-cov]: https://codeclimate.com/github/oauth-xx/oauth2/test_coverage
-[⛳cclim-cov-img]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/test_coverage
-[🖇codecov-img]: https://codecov.io/gh/oauth-xx/oauth2/branch/1-4-stable/graph/badge.svg?token=bNqSzNiuo2
+[⛳cclim-cov-img♻️]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/test_coverage
+[🖇codecov-img♻️]: https://codecov.io/gh/oauth-xx/oauth2/branch/master/graph/badge.svg?token=bNqSzNiuo2
 [🖇codecov]: https://codecov.io/gh/oauth-xx/oauth2
-[🏘coveralls]: https://coveralls.io/github/oauth-xx/oauth2?branch=1-4-stable
-[🏘coveralls-img]: https://coveralls.io/repos/github/oauth-xx/oauth2/badge.svg?branch=1-4-stable
+[🏘coveralls]: https://coveralls.io/github/oauth-xx/oauth2?branch=master
+[🏘coveralls-img]: https://coveralls.io/repos/github/oauth-xx/oauth2/badge.svg?branch=master
 [🚎sec-pol]: https://github.com/oauth-xx/oauth2/blob/master/SECURITY.md
 [🚎sec-pol-img]: https://img.shields.io/badge/security-policy-brightgreen.svg?style=flat
 [🖐codeQL]: https://github.com/oauth-xx/oauth2/security/code-scanning
 [🖐codeQL-img]: https://github.com/oauth-xx/oauth2/actions/workflows/codeql-analysis.yml/badge.svg
+[🧮cov-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml
+[🧮cov-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml/badge.svg
 
 <!-- 6️⃣ resources -->
 [⛳gh-discussions]: https://github.com/oauth-xx/oauth2/discussions
@@ -195,29 +215,51 @@ The link tokens in the following sections should be kept ordered by the row and
 [coderme]:http://coderwall.com/pboling
 [politicme]: https://nationalprogressiveparty.org
 
-
 ## Installation
 
-```shell
-gem install oauth2
-```
+Install the gem and add to the application's Gemfile by executing:
 
-Or inside a `Gemfile`
+    $ bundle add oauth2
 
-```ruby
-gem 'oauth2'
-```
-And then execute in a shell:
-```shell
-bundle
-```
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install oauth2
+
+## OAuth2 for Enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of OAuth2 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. [Learn more.](https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=enterprise)
 
+## Security contact information
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+For more see [SECURITY.md][🚎sec-pol].
+
+## What is new for v2.0?
+
+- Officially support Ruby versions >= 2.7
+- Unofficially support Ruby versions >= 2.5
+- Incidentally support Ruby versions >= 2.2
+- Drop support for the expired MAC Draft (all versions)
+- Support IETF rfc7523 JWT Bearer Tokens
+- Support IETF rfc7231 Relative Location in Redirect
+- Support IETF rfc6749 Don't set oauth params when nil
+- Support [OIDC 1.0 Private Key JWT](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication); based on the OAuth JWT assertion specification [(RFC 7523)](https://tools.ietf.org/html/rfc7523)
+- Support new formats, including from [jsonapi.org](http://jsonapi.org/format/): `application/vdn.api+json`, `application/vnd.collection+json`, `application/hal+json`, `application/problem+json`
+- Adds new option to `OAuth2::Client#get_token`:
+    - `:access_token_class` (`AccessToken`); user specified class to use for all calls to `get_token`
+- Adds new option to `OAuth2::AccessToken#initialize`:
+    - `:expires_latency` (`nil`); number of seconds by which AccessToken validity will be reduced to offset latency
+- [... A lot more](https://github.com/oauth-xx/oauth2/blob/master/CHANGELOG.md#2.0.0)
 
 ## Compatibility
 
 Targeted ruby compatibility is non-EOL versions of Ruby, currently 2.7, 3.0 and
 3.1. Compatibility is further distinguished by supported and unsupported versions of Ruby.
-Ruby is limited to 1.9+ in the gemspec for the 1.4.x series and will be 2.2+ for 2.x releases (see `master` branch).
+Ruby is limited to 2.2+ for 2.x releases. See `1-4-stable` branch for older rubies.
 
 <details>
   <summary>Ruby Engine Compatibility Policy</summary>
@@ -249,28 +291,57 @@ of a major release, support for that Ruby version may be dropped.
 
 |     | Ruby OAuth 2 Version | Maintenance Branch | Supported Officially    | Supported Unofficially | Supported Incidentally |
 |:----|----------------------|--------------------|-------------------------|------------------------|------------------------|
-| 1️⃣ | 2.0.x (unreleased)   | `master`           | 2.7, 3.0, 3.1           | 2.6, 2.5               | 2.4, 2.3, 2.2          |
-| 2️⃣ | 1.4.x                | `1-4-stable`       | 2.5, 2.6, 2.7, 3.0, 3.1 | 2.1, 2.2, 2.3, 2.4     | 2.0, 1.9               |
+| 1️⃣ | 2.0.x                | `master`           | 2.7, 3.0, 3.1           | 2.5, 2.6               | 2.2, 2.3, 2.4          |
+| 2️⃣ | 1.4.x                | `1-4-stable`       | 2.5, 2.6, 2.7, 3.0, 3.1 | 2.1, 2.2, 2.3, 2.4     | 1.9, 2.0               |
 | 3️⃣ | older                | N/A                | Best of luck to you!    | Please upgrade!        |                        |
 
-NOTE: Once 2.0 is released, the 1.4 series will only receive critical bug and security updates.
+NOTE: The 1.4 series will only receive critical bug and security updates.
 See [SECURITY.md][🚎sec-pol]
 
 ## Usage Examples
 
+### `authorize_url` and `token_url` are on site root (Just Works!)
+
 ```ruby
 require 'oauth2'
-client = OAuth2::Client.new('client_id', 'client_secret', :site => 'https://example.org')
+client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org')
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
+# => "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
 
-client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth2/callback')
-# => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:8080/oauth2/callback"
-
-token = client.auth_code.get_token('authorization_code_value', :redirect_uri => 'http://localhost:8080/oauth2/callback', :headers => {'Authorization' => 'Basic some_password'})
-response = token.get('/api/resource', :params => {'query_foo' => 'bar'})
+access = client.auth_code.get_token('authorization_code_value', redirect_uri: 'http://localhost:8080/oauth2/callback', headers: {'Authorization' => 'Basic some_password'})
+response = access.get('/api/resource', params: {'query_foo' => 'bar'})
 response.class.name
 # => OAuth2::Response
 ```
 
+### 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.
+
+```ruby
+client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org/nested/directory/on/your/server')
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
+# => "https://example.org/nested/directory/on/your/server/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+```
+
+### Customize `authorize_url` and `token_url`
+
+You can specify custom URLs for authorization and access token, and when using a leading `/` they will _not be relative_, as shown below:
+
+```ruby
+client = OAuth2::Client.new('client_id', 'client_secret',
+                            site: 'https://example.org/nested/directory/on/your/server',
+                            authorize_url: '/jaunty/authorize/',
+                            token_url: '/stirrups/access_token')
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
+# => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+client.class.name
+# => OAuth2::Client
+```
+
 <details>
   <summary>Debugging</summary>
 
@@ -289,8 +360,8 @@ require 'oauth2'
 client = OAuth2::Client.new(
   'client_id',
   'client_secret',
-  :site => 'https://example.org',
-  :logger => Logger.new('example.log', 'weekly')
+  site: 'https://example.org',
+  logger: Logger.new('example.log', 'weekly')
 )
 ```
 </details>
@@ -331,28 +402,42 @@ Response instance will contain the `OAuth2::Error` instance.
 
 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.
+use. They are available via the [`#auth_code`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/strategy/auth_code.rb), [`#implicit`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/strategy/implicit.rb), [`#password`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/strategy/password.rb), [`#client_credentials`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/strategy/client_credentials.rb), and [`#assertion`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/strategy/assertion.rb) methods respectively.
 
+These aren't full examples, but demonstrative of the differences between usage for each strategy.
 ```ruby
-auth_url = client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
-token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback')
+auth_url = client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
+access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback')
 
-auth_url = client.implicit.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
+auth_url = client.implicit.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
 # get the token params in the callback and
-token = OAuth2::AccessToken.from_kvform(client, query_string)
-
-token = client.password.get_token('username', 'password')
-
-token = client.client_credentials.get_token
-
-token = client.assertion.get_token(assertion_params)
+access = OAuth2::AccessToken.from_kvform(client, query_string)
+
+access = client.password.get_token('username', 'password')
+
+access = client.client_credentials.get_token
+
+# Client Assertion Strategy
+# see: https://tools.ietf.org/html/rfc7523
+claimset = {
+  iss: 'http://localhost:3001',
+  aud: 'http://localhost:8080/oauth2/token',
+  sub: 'me@example.com',
+  exp: Time.now.utc.to_i + 3600,
+}
+assertion_params = [claimset, 'HS256', 'secret_key']
+access = client.assertion.get_token(assertion_params)
+
+# The `access` (i.e. access token) is then used like so:
+access.token # actual access_token string, if you need it somewhere
+access.get('/api/stuff') # making api calls with access token
 ```
 
 If you want to specify additional headers to be sent out with the
 request, add a 'headers' hash under 'params':
 
 ```ruby
-token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback', :headers => {'Some' => 'Header'})
+access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback', headers: {'Some' => 'Header'})
 ```
 
 You can always use the `#request` method on the `OAuth2::Client` instance to make
@@ -373,7 +458,7 @@ dependency on this gem using the [Pessimistic Version Constraint][pvc] with two
 For example:
 
 ```ruby
-spec.add_dependency 'oauth2', '~> 1.4'
+spec.add_dependency 'oauth2', '~> 2.0'
 ```
 
 [semver]: http://semver.org/
@@ -395,13 +480,13 @@ spec.add_dependency 'oauth2', '~> 1.4'
 
 ## Development
 
-After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle excec rake spec` to run the tests.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then 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 [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/oauth-xx/oauth2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/oauth-xx/oauth2](https://github.com/oauth-xx/oauth2). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## Code of Conduct
 

data/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+| Version      | Supported |
+|--------------|-----------|
+| 2.0.<latest> | ✅         |
+| 1.4.<latest> | ✅         |
+| older        | ⛔️        |
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## OAuth2 for Enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of oauth2 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. [Learn more.](https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

data/lib/oauth2/access_token.rb

@@ -1,33 +1,36 @@
 # frozen_string_literal: true
 
 module OAuth2
-  class AccessToken
-    attr_reader :client, :token, :expires_in, :expires_at, :params
-    attr_accessor :options, :refresh_token
+  class AccessToken # rubocop:disable Metrics/ClassLength
+    attr_reader :client, :token, :expires_in, :expires_at, :expires_latency, :params
+    attr_accessor :options, :refresh_token, :response
 
-    # Should these methods be deprecated?
     class << self
       # Initializes an AccessToken from a Hash
       #
-      # @param [Client] the OAuth2::Client instance
-      # @param [Hash] a hash of AccessToken property values
-      # @return [AccessToken] the initalized AccessToken
+      # @param client [Client] the OAuth2::Client instance
+      # @param hash [Hash] a hash of AccessToken property values
+      # @return [AccessToken] the initialized AccessToken
       def from_hash(client, hash)
         hash = hash.dup
-        new(client, hash.delete('access_token') || hash.delete(:access_token), hash)
+        new(client, hash.delete('access_token') || hash.delete(:access_token) || hash.delete('token') || hash.delete(:token), hash)
       end
 
       # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string
       #
       # @param [Client] client the OAuth2::Client instance
       # @param [String] kvform the application/x-www-form-urlencoded string
-      # @return [AccessToken] the initalized AccessToken
+      # @return [AccessToken] the initialized AccessToken
       def from_kvform(client, kvform)
         from_hash(client, Rack::Utils.parse_query(kvform))
       end
+
+      def contains_token?(hash)
+        hash.key?('access_token') || hash.key?('id_token') || hash.key?('token')
+      end
     end
 
-    # Initalize an AccessToken
+    # Initialize an AccessToken
     #
     # @param [Client] client the OAuth2::Client instance
     # @param [String] token the Access Token value
@@ -35,6 +38,7 @@ module OAuth2
     # @option opts [String] :refresh_token (nil) the refresh_token value
     # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire
     # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire
+    # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+
     # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
     #    one of :header, :body or :query
     # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
@@ -44,16 +48,18 @@ module OAuth2
       @client = client
       @token = token.to_s
       opts = opts.dup
-      [:refresh_token, :expires_in, :expires_at].each do |arg|
+      %i[refresh_token expires_in expires_at expires_latency].each do |arg|
         instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
       end
       @expires_in ||= opts.delete('expires')
       @expires_in &&= @expires_in.to_i
       @expires_at &&= convert_expires_at(@expires_at)
+      @expires_latency &&= @expires_latency.to_i
       @expires_at ||= Time.now.to_i + @expires_in if @expires_in
-      @options = {:mode => opts.delete(:mode) || :header,
-                  :header_format => opts.delete(:header_format) || 'Bearer %s',
-                  :param_name => opts.delete(:param_name) || 'access_token'}
+      @expires_at -= @expires_latency if @expires_latency
+      @options = {mode: opts.delete(:mode) || :header,
+                  header_format: opts.delete(:header_format) || 'Bearer %s',
+                  param_name: opts.delete(:param_name) || 'access_token'}
       @params = opts
     end
 
@@ -75,29 +81,32 @@ module OAuth2
     #
     # @return [Boolean]
     def expired?
-      expires? && (expires_at < Time.now.to_i)
+      expires? && (expires_at <= Time.now.to_i)
     end
 
     # Refreshes the current Access Token
     #
     # @return [AccessToken] a new AccessToken
     # @note options should be carried over to the new AccessToken
-    def refresh!(params = {})
+    def refresh(params = {}, access_token_opts = {})
       raise('A refresh_token is not available') unless refresh_token
 
       params[:grant_type] = 'refresh_token'
       params[:refresh_token] = refresh_token
-      new_token = @client.get_token(params)
+      new_token = @client.get_token(params, access_token_opts)
       new_token.options = options
       new_token.refresh_token = refresh_token unless new_token.refresh_token
       new_token
     end
+    # A compatibility alias
+    # @note does not modify the receiver, so bang is not the default method
+    alias refresh! refresh
 
     # Convert AccessToken to a hash which can be used to rebuild itself with AccessToken.from_hash
     #
     # @return [Hash] a hash of AccessToken property values
     def to_hash
-      params.merge(:access_token => token, :refresh_token => refresh_token, :expires_at => expires_at)
+      params.merge(access_token: token, refresh_token: refresh_token, expires_at: expires_at)
     end
 
     # Make a request with the Access Token
@@ -166,7 +175,7 @@ module OAuth2
         if opts[:body].is_a?(Hash)
           opts[:body][options[:param_name]] = token
         else
-          opts[:body] << "&#{options[:param_name]}=#{token}"
+          opts[:body] += "&#{options[:param_name]}=#{token}"
         end
         # @todo support for multi-part (file uploads)
       else

data/lib/oauth2/authenticator.rb

@@ -37,7 +37,7 @@ module OAuth2
     end
 
     def self.encode_basic_auth(user, password)
-      'Basic ' + Base64.encode64(user + ':' + password).delete("\n")
+      "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
     end
 
   private
@@ -45,13 +45,18 @@ module OAuth2
     # Adds client_id and client_secret request parameters if they are not
     # already set.
     def apply_params_auth(params)
-      {'client_id' => id, 'client_secret' => secret}.merge(params)
+      result = {}
+      result['client_id'] = id unless id.nil?
+      result['client_secret'] = secret unless secret.nil?
+      result.merge(params)
     end
 
     # When using schemes that don't require the client_secret to be passed i.e TLS Client Auth,
     # we don't want to send the secret
     def apply_client_id(params)
-      {'client_id' => id}.merge(params)
+      result = {}
+      result['client_id'] = id unless id.nil?
+      result.merge(params)
     end
 
     # Adds an `Authorization` header with Basic Auth credentials if and only if
@@ -59,7 +64,7 @@ module OAuth2
     def apply_basic_auth(params)
       headers = params.fetch(:headers, {})
       headers = basic_auth_header.merge(headers)
-      params.merge(:headers => headers)
+      params.merge(headers: headers)
     end
 
     # @see https://datatracker.ietf.org/doc/html/rfc2617#section-2