oauth2 1.4.7 → 2.0.3

Sign up to get free protection for your applications and to get access to all the features.
data/README.md CHANGED
@@ -1,100 +1,403 @@
1
- # OAuth2
1
+ <p align="center">
2
+ <a href="http://oauth.net/2/" target="_blank" rel="noopener">
3
+ <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">
4
+ </a>
5
+ <a href="https://www.ruby-lang.org/" target="_blank" rel="noopener">
6
+ <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">
7
+ </a>
8
+ </p>
9
+
10
+ ## What
11
+
12
+ OAuth 2.0 is the industry-standard protocol for authorization.
13
+ OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications,
14
+ desktop applications, mobile phones, and living room devices.
15
+ This is a RubyGem for implementing OAuth 2.0 clients and servers in Ruby applications.
16
+ See the sibling `oauth` gem for OAuth 1.0 implementations in Ruby.
2
17
 
3
- If you need the readme for a released version of the gem please find it below:
18
+ ---
19
+
20
+ * [OAuth 2.0 Spec][oauth2-spec]
21
+ * [oauth sibling gem][sibling-gem] for OAuth 1.0 implementations in Ruby.
22
+
23
+ [oauth2-spec]: https://oauth.net/2/
24
+ [sibling-gem]: https://github.com/oauth-xx/oauth-ruby
25
+
26
+ ## Release Documentation
27
+
28
+ ### Version 2.0.x
29
+
30
+ <details>
31
+ <summary>2.0.x Readmes</summary>
32
+
33
+ | Version | Release Date | Readme |
34
+ |---------|--------------|----------------------------------------------------------|
35
+ | 2.0.3 | 2022-06-28 | https://github.com/oauth-xx/oauth2/blob/v2.0.3/README.md |
36
+ | 2.0.2 | 2022-06-24 | https://github.com/oauth-xx/oauth2/blob/v2.0.2/README.md |
37
+ | 2.0.1 | 2022-06-22 | https://github.com/oauth-xx/oauth2/blob/v2.0.1/README.md |
38
+ | 2.0.0 | 2022-06-21 | https://github.com/oauth-xx/oauth2/blob/v2.0.0/README.md |
39
+ </details>
40
+
41
+ ### Older Releases
42
+
43
+ <details>
44
+ <summary>1.4.x Readmes</summary>
45
+
46
+ | Version | Release Date | Readme |
47
+ |---------|--------------|----------------------------------------------------------|
48
+ | 1.4.9 | Feb 20, 2022 | https://github.com/oauth-xx/oauth2/blob/v1.4.9/README.md |
49
+ | 1.4.8 | Feb 18, 2022 | https://github.com/oauth-xx/oauth2/blob/v1.4.8/README.md |
50
+ | 1.4.7 | Mar 19, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.7/README.md |
51
+ | 1.4.6 | Mar 19, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.6/README.md |
52
+ | 1.4.5 | Mar 18, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.5/README.md |
53
+ | 1.4.4 | Feb 12, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.4/README.md |
54
+ | 1.4.3 | Jan 29, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.3/README.md |
55
+ | 1.4.2 | Oct 1, 2019 | https://github.com/oauth-xx/oauth2/blob/v1.4.2/README.md |
56
+ | 1.4.1 | Oct 13, 2018 | https://github.com/oauth-xx/oauth2/blob/v1.4.1/README.md |
57
+ | 1.4.0 | Jun 9, 2017 | https://github.com/oauth-xx/oauth2/blob/v1.4.0/README.md |
58
+ </details>
59
+
60
+ <details>
61
+ <summary>1.3.x Readmes</summary>
4
62
 
5
63
  | Version | Release Date | Readme |
6
64
  |----------|--------------|----------------------------------------------------------|
7
- | 1.4.7 | Mar 18, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.7/README.md |
8
- | 1.4.6 | Mar 18, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.6/README.md |
9
- | 1.4.5 | Mar 18, 2021 | https://github.com/oauth-xx/oauth2/blob/v1.4.5/README.md |
10
- | 1.4.4 | Feb 12, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.4/README.md |
11
- | 1.4.3 | Jan 29, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.3/README.md |
12
- | 1.4.2 | Oct 1, 2019 | https://github.com/oauth-xx/oauth2/blob/v1.4.2/README.md |
13
- | 1.4.1 | Oct 13, 2018 | https://github.com/oauth-xx/oauth2/blob/v1.4.1/README.md |
14
- | 1.4.0 | Jun 9, 2017 | https://github.com/oauth-xx/oauth2/blob/v1.4.0/README.md |
15
65
  | 1.3.1 | Mar 3, 2017 | https://github.com/oauth-xx/oauth2/blob/v1.3.1/README.md |
16
66
  | 1.3.0 | Dec 27, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.3.0/README.md |
67
+ </details>
68
+
69
+ <details>
70
+ <summary>&le;= 1.2.x Readmes (2016 and before)</summary>
71
+
72
+ | Version | Release Date | Readme |
73
+ |----------|--------------|----------------------------------------------------------|
17
74
  | 1.2.0 | Jun 30, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.2.0/README.md |
18
75
  | 1.1.0 | Jan 30, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.1.0/README.md |
19
76
  | 1.0.0 | May 23, 2014 | https://github.com/oauth-xx/oauth2/blob/v1.0.0/README.md |
20
77
  | < 1.0.0 | Find here | https://github.com/oauth-xx/oauth2/tags |
78
+ </details>
79
+
80
+ ## Status
81
+
82
+ <!--
83
+ Numbering rows and badges in each row as a visual "database" lookup,
84
+ as the table is extremely dense, and it can be very difficult to find anything
85
+ Putting one on each row here, to document the emoji that should be used, and for ease of copy/paste.
86
+
87
+ row #s:
88
+ 1️⃣
89
+ 2️⃣
90
+ 3️⃣
91
+ 4️⃣
92
+ 5️⃣
93
+ 6️⃣
94
+ 7️⃣
95
+
96
+ badge #s:
97
+ ⛳️
98
+ 🖇
99
+ 🏘
100
+ 🚎
101
+ 🖐
102
+ 🧮
103
+ 📗
104
+
105
+ appended indicators:
106
+ ♻️ - URL needs to be updated from SASS integration. Find / Replace is insufficient.
107
+ -->
108
+
109
+ | | Project | bundle add oauth2 |
110
+ |:----|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
111
+ | 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] |
112
+ | 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♻️] |
113
+ | 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] |
114
+ | 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] |
115
+ | 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] |
116
+ | 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] |
117
+ | 7️⃣ | spread 💖 | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Tweet @ Peter][🏘tweet-img]][🏘tweet] [🌏][aboutme] [👼][angelme] [💻][coderme] |
118
+
119
+ <!--
120
+ The link tokens in the following sections should be kept ordered by the row and badge numbering scheme
121
+ -->
122
+
123
+ <!-- 1️⃣ name, license, docs -->
124
+ [⛳️gem]: https://rubygems.org/gems/oauth2
125
+ [⛳️name-img]: https://img.shields.io/badge/name-oauth2-brightgreen.svg?style=flat
126
+ [🖇src-license]: https://opensource.org/licenses/MIT
127
+ [🖇src-license-img]: https://img.shields.io/badge/License-MIT-green.svg
128
+ [🏘fossa]: https://app.fossa.io/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2?ref=badge_shield
129
+ [🏘fossa-img]: https://app.fossa.io/api/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2.svg?type=shield
130
+ [🚎yard]: https://www.rubydoc.info/github/oauth-xx/oauth2
131
+ [🚎yard-img]: https://img.shields.io/badge/documentation-rubydoc-brightgreen.svg?style=flat
132
+ [🖐inch-ci-img]: http://inch-ci.org/github/oauth-xx/oauth2.png
133
+
134
+ <!-- 2️⃣ version & activity -->
135
+ [⛳️version-img]: http://img.shields.io/gem/v/oauth2.svg
136
+ [🖇DL-total-img]: https://img.shields.io/gem/dt/oauth2.svg
137
+ [🏘DL-rank-img]: https://img.shields.io/gem/rt/oauth2.svg
138
+ [🚎src-home]: https://github.com/oauth-xx/oauth2
139
+ [🚎src-home-img]: https://img.shields.io/badge/source-github-brightgreen.svg?style=flat
140
+ [🖐prs-o]: https://github.com/oauth-xx/oauth2/pulls
141
+ [🖐prs-o-img]: https://img.shields.io/github/issues-pr/oauth-xx/oauth2
142
+ [🧮prs-c]: https://github.com/oauth-xx/oauth2/pulls?q=is%3Apr+is%3Aclosed
143
+ [🧮prs-c-img]: https://img.shields.io/github/issues-pr-closed/oauth-xx/oauth2
144
+ [📗next♻️]: https://github.com/oauth-xx/oauth2/milestone/15
145
+ [📗next-img♻️]: https://img.shields.io/github/milestones/progress/oauth-xx/oauth2/15?label=Next%20Version
146
+
147
+ <!-- 3️⃣ maintanence & linting -->
148
+ [⛳cclim-maint]: https://codeclimate.com/github/oauth-xx/oauth2/maintainability
149
+ [⛳cclim-maint-img♻️]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/maintainability
150
+ [🖇triage-help]: https://www.codetriage.com/oauth-xx/oauth2
151
+ [🖇triage-help-img]: https://www.codetriage.com/oauth-xx/oauth2/badges/users.svg
152
+ [🏘depfu♻️]: https://depfu.com/github/oauth-xx/oauth2?project_id=4445
153
+ [🏘depfu-img♻️]: https://badges.depfu.com/badges/6d34dc1ba682bbdf9ae2a97848241743/count.svg
154
+ [🚎contributors]: https://github.com/oauth-xx/oauth2/graphs/contributors
155
+ [🚎contributors-img]: https://img.shields.io/github/contributors-anon/oauth-xx/oauth2
156
+ [🖐style-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/style.yml
157
+ [🖐style-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/style.yml/badge.svg
158
+ [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
159
+ [🧮kloc-img]: https://img.shields.io/tokei/lines/github.com/oauth-xx/oauth2
160
+
161
+ <!-- 4️⃣ testing -->
162
+ [⛳iss-o]: https://github.com/oauth-xx/oauth2/issues
163
+ [⛳iss-o-img]: https://img.shields.io/github/issues-raw/oauth-xx/oauth2
164
+ [🖇iss-c]: https://github.com/oauth-xx/oauth2/issues?q=is%3Aissue+is%3Aclosed
165
+ [🖇iss-c-img]: https://img.shields.io/github/issues-closed-raw/oauth-xx/oauth2
166
+ [🏘sup-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml
167
+ [🏘sup-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/supported.yml/badge.svg
168
+ [🚎heads-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/heads.yml
169
+ [🚎heads-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/heads.yml/badge.svg
170
+ [🖐uns-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml
171
+ [🖐uns-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/unsupported.yml/badge.svg
172
+ [🧮mac-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/macos.yml
173
+ [🧮mac-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/macos.yml/badge.svg
174
+ [📗win-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/windows.yml
175
+ [📗win-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/windows.yml/badge.svg
176
+
177
+ <!-- 5️⃣ coverage & security -->
178
+ [⛳cclim-cov]: https://codeclimate.com/github/oauth-xx/oauth2/test_coverage
179
+ [⛳cclim-cov-img♻️]: https://api.codeclimate.com/v1/badges/688c612528ff90a46955/test_coverage
180
+ [🖇codecov-img♻️]: https://codecov.io/gh/oauth-xx/oauth2/branch/master/graph/badge.svg?token=bNqSzNiuo2
181
+ [🖇codecov]: https://codecov.io/gh/oauth-xx/oauth2
182
+ [🏘coveralls]: https://coveralls.io/github/oauth-xx/oauth2?branch=master
183
+ [🏘coveralls-img]: https://coveralls.io/repos/github/oauth-xx/oauth2/badge.svg?branch=master
184
+ [🚎sec-pol]: https://github.com/oauth-xx/oauth2/blob/master/SECURITY.md
185
+ [🚎sec-pol-img]: https://img.shields.io/badge/security-policy-brightgreen.svg?style=flat
186
+ [🖐codeQL]: https://github.com/oauth-xx/oauth2/security/code-scanning
187
+ [🖐codeQL-img]: https://github.com/oauth-xx/oauth2/actions/workflows/codeql-analysis.yml/badge.svg
188
+ [🧮cov-wf]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml
189
+ [🧮cov-wf-img]: https://github.com/oauth-xx/oauth2/actions/workflows/coverage.yml/badge.svg
190
+
191
+ <!-- 6️⃣ resources -->
192
+ [⛳gh-discussions]: https://github.com/oauth-xx/oauth2/discussions
193
+ [⛳gh-discussions-img]: https://img.shields.io/github/discussions/oauth-xx/oauth2
194
+ [🖇codementor]: https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github
195
+ [🖇codementor-img]: https://cdn.codementor.io/badges/get_help_github.svg
196
+ [🏘chat]: https://gitter.im/oauth-xx/oauth2
197
+ [🏘chat-img]: https://img.shields.io/gitter/room/oauth-xx/oauth2.svg
198
+ [🚎blog]: http://www.railsbling.com/tags/oauth2/
199
+ [🚎blog-img]: https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat
200
+ [🖐wiki]: https://github.com/oauth-xx/oauth2/wiki
201
+ [🖐wiki-img]: https://img.shields.io/badge/wiki-examples-brightgreen.svg?style=flat
202
+
203
+ <!-- 7️⃣ spread 💖 -->
204
+ [⛳liberapay-img]: https://img.shields.io/liberapay/patrons/pboling.svg?logo=liberapay
205
+ [⛳liberapay]: https://liberapay.com/pboling/donate
206
+ [🖇sponsor-img]: https://img.shields.io/badge/sponsor-pboling.svg?style=social&logo=github
207
+ [🖇sponsor]: https://github.com/sponsors/pboling
208
+ [🏘tweet-img]: https://img.shields.io/twitter/follow/galtzo.svg?style=social&label=Follow
209
+ [🏘tweet]: http://twitter.com/galtzo
210
+
211
+ <!-- Maintainer Contact Links -->
212
+ [railsbling]: http://www.railsbling.com
213
+ [peterboling]: http://www.peterboling.com
214
+ [aboutme]: https://about.me/peter.boling
215
+ [angelme]: https://angel.co/peter-boling
216
+ [coderme]:http://coderwall.com/pboling
21
217
 
22
- [![Gem Version](http://img.shields.io/gem/v/oauth2.svg)][gem]
23
- [![Total Downloads](https://img.shields.io/gem/dt/oauth2.svg)][gem]
24
- [![Downloads Today](https://img.shields.io/gem/rt/oauth2.svg)][gem]
25
- [![Build Status](https://travis-ci.org/oauth-xx/oauth2.svg?branch=1-4-stable)][travis]
26
- [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Foauth-xx%2Foauth2%2Fbadge&style=flat)][github-actions]
27
- [![Test Coverage](https://api.codeclimate.com/v1/badges/688c612528ff90a46955/test_coverage)][codeclimate-coverage]
28
- [![Maintainability](https://api.codeclimate.com/v1/badges/688c612528ff90a46955/maintainability)][codeclimate-maintainability]
29
- [![Depfu](https://badges.depfu.com/badges/6d34dc1ba682bbdf9ae2a97848241743/count.svg)][depfu]
30
- [![Open Source Helpers](https://www.codetriage.com/oauth-xx/oauth2/badges/users.svg)][code-triage]
31
- [![Chat](https://img.shields.io/gitter/room/oauth-xx/oauth2.svg)](https://gitter.im/oauth-xx/oauth2)
32
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][source-license]
33
- [![Documentation](http://inch-ci.org/github/oauth-xx/oauth2.png)][inch-ci]
34
-
35
- [gem]: https://rubygems.org/gems/oauth2
36
- [travis]: http://travis-ci.org/oauth-xx/oauth2
37
- [github-actions]: https://actions-badge.atrox.dev/oauth-xx/oauth2/goto
38
- [coveralls]: https://coveralls.io/r/oauth-xx/oauth2
39
- [codeclimate-maintainability]: https://codeclimate.com/github/oauth-xx/oauth2/maintainability
40
- [codeclimate-coverage]: https://codeclimate.com/github/oauth-xx/oauth2/test_coverage
41
- [depfu]: https://depfu.com/github/oauth-xx/oauth2
42
- [source-license]: https://opensource.org/licenses/MIT
43
- [inch-ci]: http://inch-ci.org/github/oauth-xx/oauth2
44
- [code-triage]: https://www.codetriage.com/oauth-xx/oauth2
45
- [fossa1]: https://app.fossa.io/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2?ref=badge_shield
46
-
47
- A Ruby wrapper for the [OAuth 2.0 specification][oauth2-spec].
218
+ ## Installation
48
219
 
49
- [oauth2-spec]: https://oauth.net/2/
220
+ Install the gem and add to the application's Gemfile by executing:
50
221
 
51
- ## Installation
222
+ $ bundle add oauth2
52
223
 
53
- Add this line to your application's Gemfile:
224
+ If bundler is not being used to manage dependencies, install the gem by executing:
54
225
 
55
- ```ruby
56
- gem 'oauth2'
57
- ```
226
+ $ gem install oauth2
58
227
 
59
- And then execute:
228
+ ## OAuth2 for Enterprise
60
229
 
61
- $ bundle
230
+ Available as part of the Tidelift Subscription.
62
231
 
63
- Or install it yourself as:
232
+ 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)
64
233
 
65
- $ gem install oauth2
234
+ ## Security contact information
235
+
236
+ To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
237
+ Tidelift will coordinate the fix and disclosure.
238
+
239
+ For more see [SECURITY.md][🚎sec-pol].
240
+
241
+ ## What is new for v2.0?
242
+
243
+ - Officially support Ruby versions >= 2.7
244
+ - Unofficially support Ruby versions >= 2.5
245
+ - Incidentally support Ruby versions >= 2.2
246
+ - Drop support for the expired MAC Draft (all versions)
247
+ - Support IETF rfc7523 JWT Bearer Tokens
248
+ - Support IETF rfc7231 Relative Location in Redirect
249
+ - Support IETF rfc6749 Don't set oauth params when nil
250
+ - 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)
251
+ - 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`
252
+ - Adds new option to `OAuth2::Client#get_token`:
253
+ - `:access_token_class` (`AccessToken`); user specified class to use for all calls to `get_token`
254
+ - Adds new option to `OAuth2::AccessToken#initialize`:
255
+ - `:expires_latency` (`nil`); number of seconds by which AccessToken validity will be reduced to offset latency
256
+ - [... A lot more](https://github.com/oauth-xx/oauth2/blob/master/CHANGELOG.md#2.0.0)
66
257
 
67
- ## Resources
258
+ ## Compatibility
68
259
 
69
- * [View Source on GitHub][code]
70
- * [Report Issues on GitHub][issues]
71
- * [Read More at the Wiki][wiki]
260
+ Targeted ruby compatibility is non-EOL versions of Ruby, currently 2.7, 3.0 and
261
+ 3.1. Compatibility is further distinguished by supported and unsupported versions of Ruby.
262
+ Ruby is limited to 2.2+ for 2.x releases. See `1-4-stable` branch for older rubies.
72
263
 
73
- [code]: https://github.com/oauth-xx/oauth2
74
- [issues]: https://github.com/oauth-xx/oauth2/issues
75
- [wiki]: https://wiki.github.com/oauth-xx/oauth2
264
+ <details>
265
+ <summary>Ruby Engine Compatibility Policy</summary>
266
+
267
+ This gem is tested against MRI, JRuby, and Truffleruby.
268
+ Each of those has varying versions that target a specific version of MRI Ruby.
269
+ This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below.
270
+ If you would like to add support for additional engines,
271
+ first make sure Github Actions supports the engine,
272
+ then submit a PR to the correct maintenance branch as according to the table below.
273
+ </details>
274
+
275
+ <details>
276
+ <summary>Ruby Version Compatibility Policy</summary>
277
+
278
+ If something doesn't work on one of these interpreters, it's a bug.
279
+
280
+ This library may inadvertently work (or seem to work) on other Ruby
281
+ implementations, however support will only be provided for the versions listed
282
+ above.
283
+
284
+ If you would like this library to support another Ruby version, you may
285
+ volunteer to be a maintainer. Being a maintainer entails making sure all tests
286
+ run and pass on that implementation. When something breaks on your
287
+ implementation, you will be responsible for providing patches in a timely
288
+ fashion. If critical issues for a particular implementation exist at the time
289
+ of a major release, support for that Ruby version may be dropped.
290
+ </details>
291
+
292
+ | | Ruby OAuth 2 Version | Maintenance Branch | Supported Officially | Supported Unofficially | Supported Incidentally |
293
+ |:----|----------------------|--------------------|-------------------------|------------------------|------------------------|
294
+ | 1️⃣ | 2.0.x | `master` | 2.7, 3.0, 3.1 | 2.5, 2.6 | 2.2, 2.3, 2.4 |
295
+ | 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 |
296
+ | 3️⃣ | older | N/A | Best of luck to you! | Please upgrade! | |
297
+
298
+ NOTE: The 1.4 series will only receive critical bug and security updates.
299
+ See [SECURITY.md][🚎sec-pol]
76
300
 
77
301
  ## Usage Examples
78
302
 
303
+ ### `authorize_url` and `token_url` are on site root (Just Works!)
304
+
79
305
  ```ruby
80
306
  require 'oauth2'
81
- client = OAuth2::Client.new('client_id', 'client_secret', :site => 'https://example.org')
82
-
83
- client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth2/callback')
84
- # => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:8080/oauth2/callback"
307
+ client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org')
308
+ # => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
309
+ client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
310
+ # => "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
85
311
 
86
- token = client.auth_code.get_token('authorization_code_value', :redirect_uri => 'http://localhost:8080/oauth2/callback', :headers => {'Authorization' => 'Basic some_password'})
87
- response = token.get('/api/resource', :params => {'query_foo' => 'bar'})
312
+ access = client.auth_code.get_token('authorization_code_value', redirect_uri: 'http://localhost:8080/oauth2/callback', headers: {'Authorization' => 'Basic some_password'})
313
+ response = access.get('/api/resource', params: {'query_foo' => 'bar'})
88
314
  response.class.name
89
315
  # => OAuth2::Response
90
316
  ```
317
+
318
+ ### Relative `authorize_url` and `token_url` (Not on site root, Just Works!)
319
+
320
+ 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.
321
+
322
+ ```ruby
323
+ client = OAuth2::Client.new('client_id', 'client_secret', site: 'https://example.org/nested/directory/on/your/server')
324
+ # => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
325
+ client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
326
+ # => "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"
327
+ ```
328
+
329
+ ### Customize `authorize_url` and `token_url`
330
+
331
+ You can specify custom URLs for authorization and access token, and when using a leading `/` they will _not be relative_, as shown below:
332
+
333
+ ```ruby
334
+ client = OAuth2::Client.new('client_id', 'client_secret',
335
+ site: 'https://example.org/nested/directory/on/your/server',
336
+ authorize_url: '/jaunty/authorize/',
337
+ token_url: '/stirrups/access_token')
338
+ # => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
339
+ client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth2/callback')
340
+ # => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
341
+ client.class.name
342
+ # => OAuth2::Client
343
+ ```
344
+
345
+ ### snake_case and indifferent access in Response#parsed
346
+
347
+ ```ruby
348
+ response = access.get('/api/resource', params: {'query_foo' => 'bar'})
349
+ # Even if the actual response is CamelCase. it will be made available as snaky:
350
+ JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
351
+ response.parsed # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
352
+ response.parsed.access_token # => "aaaaaaaa"
353
+ response.parsed[:access_token] # => "aaaaaaaa"
354
+ response.parsed.additional_data # => "additional"
355
+ response.parsed[:additional_data] # => "additional"
356
+ response.parsed.class.name # => OAuth2::SnakyHash (subclass of Hashie::Mash::Rash, from `rash_alt` gem)
357
+ ```
358
+
359
+ #### What if I hate snakes and/or indifference?
360
+
361
+ ```ruby
362
+ response = access.get('/api/resource', params: {'query_foo' => 'bar'}, snaky: false)
363
+ JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
364
+ response.parsed # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
365
+ response.parsed['accessToken'] # => "aaaaaaaa"
366
+ response.parsed['additionalData'] # => "additional"
367
+ response.parsed.class.name # => Hash (just, regular old Hash)
368
+ ```
369
+
370
+ <details>
371
+ <summary>Debugging</summary>
372
+
373
+ Set an environment variable, however you would [normally do that](https://github.com/bkeepers/dotenv).
374
+
375
+ ```ruby
376
+ # will log both request and response, including bodies
377
+ ENV['OAUTH_DEBUG'] = 'true'
378
+ ```
379
+
380
+ By default, debug output will go to `$stdout`. This can be overridden when
381
+ initializing your OAuth2::Client.
382
+
383
+ ```ruby
384
+ require 'oauth2'
385
+ client = OAuth2::Client.new(
386
+ 'client_id',
387
+ 'client_secret',
388
+ site: 'https://example.org',
389
+ logger: Logger.new('example.log', 'weekly')
390
+ )
391
+ ```
392
+ </details>
393
+
91
394
  ## OAuth2::Response
92
395
 
93
- The AccessToken methods #get, #post, #put and #delete and the generic #request
396
+ The `AccessToken` methods `#get`, `#post`, `#put` and `#delete` and the generic `#request`
94
397
  will return an instance of the #OAuth2::Response class.
95
398
 
96
- This instance contains a #parsed method that will parse the response body and
97
- return a Hash if the Content-Type is application/x-www-form-urlencoded or if
399
+ This instance contains a `#parsed` method that will parse the response body and
400
+ return a Hash-like [`OAuth2::SnakyHash`](https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/snaky_hash.rb) if the `Content-Type` is `application/x-www-form-urlencoded` or if
98
401
  the body is a JSON object. It will return an Array if the body is a JSON
99
402
  array. Otherwise, it will return the original body string.
100
403
 
@@ -104,100 +407,67 @@ respective methods.
104
407
  ## OAuth2::AccessToken
105
408
 
106
409
  If you have an existing Access Token for a user, you can initialize an instance
107
- using various class methods including the standard new, from_hash (if you have
108
- a hash of the values), or from_kvform (if you have an
109
- application/x-www-form-urlencoded encoded string of the values).
410
+ using various class methods including the standard new, `from_hash` (if you have
411
+ a hash of the values), or `from_kvform` (if you have an
412
+ `application/x-www-form-urlencoded` encoded string of the values).
110
413
 
111
414
  ## OAuth2::Error
112
415
 
113
- On 400+ status code responses, an OAuth2::Error will be raised. If it is a
114
- standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and
115
- error_description parameters. The #response property of OAuth2::Error will
116
- always contain the OAuth2::Response instance.
416
+ On 400+ status code responses, an `OAuth2::Error` will be raised. If it is a
417
+ standard OAuth2 error response, the body will be parsed and `#code` and `#description` will contain the values provided from the error and
418
+ `error_description` parameters. The `#response` property of `OAuth2::Error` will
419
+ always contain the `OAuth2::Response` instance.
117
420
 
118
- If you do not want an error to be raised, you may use :raise_errors => false
119
- option on initialization of the client. In this case the OAuth2::Response
421
+ If you do not want an error to be raised, you may use `:raise_errors => false`
422
+ option on initialization of the client. In this case the `OAuth2::Response`
120
423
  instance will be returned as usual and on 400+ status code responses, the
121
- Response instance will contain the OAuth2::Error instance.
424
+ Response instance will contain the `OAuth2::Error` instance.
122
425
 
123
426
  ## Authorization Grants
124
427
 
125
428
  Currently the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
126
429
  authentication grant types have helper strategy classes that simplify client
127
- use. They are available via the #auth_code, #implicit, #password, #client_credentials, and #assertion methods respectively.
430
+ 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.
128
431
 
432
+ These aren't full examples, but demonstrative of the differences between usage for each strategy.
129
433
  ```ruby
130
- auth_url = client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
131
- token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback')
434
+ auth_url = client.auth_code.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
435
+ access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback')
132
436
 
133
- auth_url = client.implicit.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
437
+ auth_url = client.implicit.authorize_url(redirect_uri: 'http://localhost:8080/oauth/callback')
134
438
  # get the token params in the callback and
135
- token = OAuth2::AccessToken.from_kvform(client, query_string)
136
-
137
- token = client.password.get_token('username', 'password')
138
-
139
- token = client.client_credentials.get_token
140
-
141
- token = client.assertion.get_token(assertion_params)
439
+ access = OAuth2::AccessToken.from_kvform(client, query_string)
440
+
441
+ access = client.password.get_token('username', 'password')
442
+
443
+ access = client.client_credentials.get_token
444
+
445
+ # Client Assertion Strategy
446
+ # see: https://tools.ietf.org/html/rfc7523
447
+ claimset = {
448
+ iss: 'http://localhost:3001',
449
+ aud: 'http://localhost:8080/oauth2/token',
450
+ sub: 'me@example.com',
451
+ exp: Time.now.utc.to_i + 3600,
452
+ }
453
+ assertion_params = [claimset, 'HS256', 'secret_key']
454
+ access = client.assertion.get_token(assertion_params)
455
+
456
+ # The `access` (i.e. access token) is then used like so:
457
+ access.token # actual access_token string, if you need it somewhere
458
+ access.get('/api/stuff') # making api calls with access token
142
459
  ```
143
460
 
144
461
  If you want to specify additional headers to be sent out with the
145
462
  request, add a 'headers' hash under 'params':
146
463
 
147
464
  ```ruby
148
- token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback', :headers => {'Some' => 'Header'})
465
+ access = client.auth_code.get_token('code_value', redirect_uri: 'http://localhost:8080/oauth/callback', headers: {'Some' => 'Header'})
149
466
  ```
150
467
 
151
- You can always use the #request method on the OAuth2::Client instance to make
468
+ You can always use the `#request` method on the `OAuth2::Client` instance to make
152
469
  requests for tokens for any Authentication grant type.
153
470
 
154
- ## Supported Ruby Versions
155
-
156
- This library aims to support and is [tested against][travis] the following Ruby
157
- implementations:
158
-
159
- ### Rubies with support ending at Oauth2 1.x
160
-
161
- * Ruby 1.9.3
162
- - [JRuby 1.7][jruby-1.7] (targets MRI v1.9)
163
-
164
- * Ruby 2.0.0
165
- - [JRuby 9.0][jruby-9.0] (targets MRI v2.0)
166
- * Ruby 2.1
167
-
168
- ---
169
-
170
- ### Rubies with continued support past Oauth2 2.x
171
-
172
- * Ruby 2.2 - Support ends with version 2.x series
173
- * Ruby 2.3 - Support ends with version 3.x series
174
- - [JRuby 9.1][jruby-9.1] (targets MRI v2.3)
175
- * Ruby 2.4 - Support ends with version 4.x series
176
- * Ruby 2.5 - Support ends with version 5.x series
177
- - [JRuby 9.2][jruby-9.2] (targets MRI v2.5)
178
- - [truffleruby][truffleruby] (targets MRI 2.5)
179
- * Ruby 2.6 - Support ends with version 6.x series
180
- * Ruby 2.7 - Support ends with version 7.x series
181
-
182
- [jruby-1.7]: https://www.jruby.org/2017/05/11/jruby-1-7-27.html
183
- [jruby-9.0]: https://www.jruby.org/2016/01/26/jruby-9-0-5-0.html
184
- [jruby-9.1]: https://www.jruby.org/2017/05/16/jruby-9-1-9-0.html
185
- [jruby-9.2]: https://www.jruby.org/2018/05/24/jruby-9-2-0-0.html
186
- [truffleruby]: https://github.com/oracle/truffleruby
187
-
188
- If something doesn't work on one of these interpreters, it's a bug.
189
-
190
- This library may inadvertently work (or seem to work) on other Ruby
191
- implementations, however support will only be provided for the versions listed
192
- above.
193
-
194
- If you would like this library to support another Ruby version, you may
195
- volunteer to be a maintainer. Being a maintainer entails making sure all tests
196
- run and pass on that implementation. When something breaks on your
197
- implementation, you will be responsible for providing patches in a timely
198
- fashion. If critical issues for a particular implementation exist at the time
199
- of a major release, support for that Ruby version may be dropped.
200
-
201
471
  ## Versioning
202
472
 
203
473
  This library aims to adhere to [Semantic Versioning 2.0.0][semver].
@@ -213,7 +483,7 @@ dependency on this gem using the [Pessimistic Version Constraint][pvc] with two
213
483
  For example:
214
484
 
215
485
  ```ruby
216
- spec.add_dependency 'oauth2', '~> 1.4'
486
+ spec.add_dependency 'oauth2', '~> 2.0'
217
487
  ```
218
488
 
219
489
  [semver]: http://semver.org/
@@ -221,27 +491,35 @@ spec.add_dependency 'oauth2', '~> 1.4'
221
491
 
222
492
  ## License
223
493
 
224
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][source-license]
494
+ [![License: MIT][🖇src-license-img]][🖇src-license]
225
495
 
226
496
  - Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.
227
- - Copyright (c) 2017-2018 [oauth-xx organization][oauth-xx]
497
+ - Copyright (c) 2017-2022 [oauth-xx organization][oauth-xx]
228
498
  - See [LICENSE][license] for details.
229
499
 
230
500
  [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2.svg?type=large)][fossa2]
231
501
 
232
- [license]: LICENSE
502
+ [license]: https://github.com/oauth-xx/oauth2/blob/master/LICENSE
233
503
  [oauth-xx]: https://github.com/oauth-xx
234
504
  [fossa2]: https://app.fossa.io/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2?ref=badge_large
235
505
 
236
506
  ## Development
237
507
 
238
- After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
508
+ 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.
239
509
 
240
510
  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).
241
511
 
242
512
  ## Contributing
243
513
 
244
- 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.
514
+ See [CONTRIBUTING.md][contributing]
515
+
516
+ [contributing]: https://github.com/oauth-xx/oauth2/blob/main/CONTRIBUTING.md
517
+
518
+ ## Contributors
519
+
520
+ [![Contributors](https://contrib.rocks/image?repo=oauth-xx/oauth2)]("https://github.com/oauth-xx/oauth2/graphs/contributors")
521
+
522
+ Made with [contributors-img](https://contrib.rocks).
245
523
 
246
524
  ## Code of Conduct
247
525