Add access token-related functionality including auto-refresh (#83)

The following new functionality has been **extracted** from
`code-club-frontend` and `experience-cs` to reduce duplication and
hopefully make useful functionality available to other Rails apps using
this gem.

[This pull
request](RaspberryPiFoundation/experience-cs#295)
where it was recently added to `experience-cs` and [this follow-up pull
request](RaspberryPiFoundation/experience-cs#315)
are good references.

* ✅ I've used the new `rpi-auth` code in the context of `experience-cs`
in [this pull
request](RaspberryPiFoundation/experience-cs#317)
and it seems to be OK.
* ✅ I've used the new `rpi-auth` code in the context of
`code-club-frontend` in [this pull
request](RaspberryPiFoundation/code-club-frontend#280)
and all the test pass.

## Add `RpiAuth::Models::WithTokens` concern

This can optionally be included into your user model in order to obtain
an access token, a refresh token, and an expiry time when logging in.
These attributes are set by the same mechanism in
`AuthController#callback` that populates `user_id` on the user via
`Authenticatable.from_omniauth`, but instead calls
`WithTokens.from_omniauth` which in turn calls
`Authenticatable.from_omniauth` via the ancestor chain.

This also relies on:
- `RpiAuth.configuration.scope` including the "offline" scope in the
Rails app which is using the `rpi_auth` gem.
- In the `profile` app `hydra_client` config for the Rails app,
`grant_types` must include "refresh_token" and `scope` must include
"offline".

This has been substantially copied from `code-club-frontend`:
- [`app/models/user.rb`][1]
- [`spec/models/user_spec.rb`][2]

## Add `RpiAuth::Controllers::AutoRefreshingToken` concern 

This can optionally be included into your controller to automatically
use the user's refresh token to obtain a new access token when the old
one expires. It adds a before action to the target controller which
automatically calls `OauthClient#refresh_credentials!` if the user is
signed in and their access token has expired. The latter makes a request
to the `profile` app using the refresh token to obtain a new access
token.

Again this has been substantially copied from `code-club-frontend`:
- [`app/controllers/application_controller.rb`][3]
- [`spec/requests/refresh_credentials_spec.rb`][4]
- [`lib/oauth_client.rb`][5]
- [`spec/lib/oauth_client_spec.rb`][6]

## Questions/issues

In general I'd prefer to postpone tackling any of the following to
separate PRs, because I think it's useful to have a version of the code
which matches what's currently in `code-club-frontend` & `experience-cs`
as closely as possible before we start changing things further. However,
hopefully the following notes are useful:

- I haven't included the aliasing of `#user_id` & `#user_id=` to `#id` &
`#id=` respectively, because I'm not yet sure whether it's more
generally useful - we don't seem to need it in `experience-cs` yet.
- I think it might simplify things a bit to move some of the
classes/modules that are currently in `lib` into relevant directories
under `app`, e.g. I think that moving
`lib/rpi_auth/models/authenticatable.rb` ->
`app/models/rpi_auth/authenticatable.rb` (or maybe
`app/models/concerns/rpi_auth/authenticatable.rb`) would mean the
classes were automatically loaded. This seems like a more idiomatic use
of a Rails engine. However, that's probably a bigger piece of work,
especially to make sure it works with the relevant versions of Rails.
- I'm slightly concerned about a few details of the implementation of
`AutoRefreshingToken#refresh_credentials_if_needed`:
- Rescuing all `ArgumentError` exceptions seems risky, because it's
quite a common exception. It would be better to be more specific.
- Even rescuing all `OAuth2::Error` exceptions seems a bit broad,
although I haven't investigated what this encompasses. At the very least
it would be good to log/report the details of the exception.
- While resetting the session in the event of an exception seems OK
security-wise, it probably doesn't result in a great user experience. It
would be better to redirect and/or display an error message to the user
to explain what's happened.

[1]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/app/models/user.rb
[2]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/spec/models/user_spec.rb
[3]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/app/controllers/application_controller.rb#L8
[4]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/spec/requests/refresh_credentials_spec.rb
[5]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/f7e965798d910584fed0d1eb7867f32a899f9ce8/lib/oauth_client.rb
[6]:
https://github.com/RaspberryPiFoundation/code-club-frontend/blob/main/spec/lib/oauth_client_spec.rb

Author: floehopper

.rubocop_todo.yml

@@ -12,7 +12,7 @@
 # Include: **/*.gemspec, **/Gemfile, **/gems.rb
 Gemspec/DevelopmentDependencies:
   Exclude:
-    - 'rpi_auth.gemspec'
+    - "rpi_auth.gemspec"
 
 # Offense count: 1
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
@@ -43,4 +43,5 @@ RSpec/NestedGroups:
 # Include: **/*_spec.rb
 RSpec/SpecFilePathFormat:
   Exclude:
-    - 'spec/rpi_auth/models/authenticatable_spec.rb'
+    - "spec/rpi_auth/models/authenticatable_spec.rb"
+    - "spec/rpi_auth/models/with_tokens_spec.rb"

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Add access token-related functionality including auto-refresh (#83)
 
 ### Fixed
 - Fix use of `User#expires_at` in `SpecHelpers#stub_auth_for` (#82)

README.md

@@ -187,6 +187,29 @@ class in `config/application.rb`.
 config.railties_order = [RpiAuth::Engine, :main_app, :all]
 ```
 
+### Obtaining an access token for user
+
+This optional behaviour is useful if your Rails app (which is using this gem)
+needs to use a RPF API which required authentication via an OAuth2 access
+token.
+
+Include the `RpiAuth::Models::WithTokens` concern (which depends on the
+`RpiAuth::Models::Authenticatable` concern) into your user model in order to
+add `access_token`, `refresh_token` & `expires_at` attributes. These methods
+are automatically populated by `RpiAuth::AuthController#callback` via the
+`RpiAuth::Models::WithTokens.from_omniauth` method.
+
+This also relies on the following:
+- `RpiAuth.configuration.scope` including the "offline" scope in the Rails app
+  which is using the `rpi_auth` gem.
+- In the `profile` app `hydra_client` config for the Rails app, `grant_types`
+  must include "refresh_token" and `scope` must include "offline".
+
+Include the `RpiAuth::Controllers::AutoRefreshingToken` concern (which depends
+on the `RpiAuth::Controllers::CurrentUser` concern) into your controller so
+that when the user's access token expires, a new one is obtained using the
+user's refresh token.
+
 ## Test helpers and routes
 
 There are some standardised test helpers in `RpiAuth::SpecHelpers` that can be used when testing.

gemfiles/rails_6.1.gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: ..
   specs:
     rpi_auth (4.0.0)
+      oauth2
       omniauth-rails_csrf_protection (~> 1.0.0)
       omniauth_openid_connect (~> 0.7.1)
       rails (>= 6.1.4)
@@ -74,6 +75,7 @@ GEM
     ast (2.4.3)
     attr_required (1.0.2)
     base64 (0.2.0)
+    bigdecimal (3.1.9)
     bindata (2.5.1)
     builder (3.3.0)
     byebug (12.0.0)
@@ -88,6 +90,9 @@ GEM
       xpath (~> 3.2)
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
+    crack (1.0.0)
+      bigdecimal
+      rexml
     crass (1.0.6)
     date (3.4.1)
     diff-lcs (1.6.1)
@@ -106,6 +111,7 @@ GEM
     ffi (1.17.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
+    hashdiff (1.1.2)
     hashie (5.0.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
@@ -117,6 +123,8 @@ GEM
       bindata
       faraday (~> 2.0)
       faraday-follow_redirects
+    jwt (2.10.1)
+      base64
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -137,6 +145,8 @@ GEM
     mini_mime (1.1.5)
     mini_portile2 (2.8.8)
     minitest (5.25.5)
+    multi_xml (0.7.1)
+      bigdecimal (~> 3.1)
     net-http (0.6.0)
       uri
     net-imap (0.5.6)
@@ -152,6 +162,13 @@ GEM
     nokogiri (1.18.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
+    oauth2 (2.0.9)
+      faraday (>= 0.17.3, < 3.0)
+      jwt (>= 1.0, < 3.0)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 4)
+      snaky_hash (~> 2.0)
+      version_gem (~> 1.1)
     omniauth (2.1.3)
       hashie (>= 3.4.6)
       rack (>= 2.2.3)
@@ -237,6 +254,7 @@ GEM
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     regexp_parser (2.10.0)
+    rexml (3.4.1)
     rspec-core (3.13.3)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.3)
@@ -290,6 +308,9 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    snaky_hash (2.0.1)
+      hashie
+      version_gem (~> 1.1, >= 1.1.1)
     sprockets (4.2.1)
       concurrent-ruby (~> 1.0)
       rack (>= 2.2.4, < 4)
@@ -313,10 +334,15 @@ GEM
     validate_url (1.0.15)
       activemodel (>= 3.0.0)
       public_suffix
+    version_gem (1.1.7)
     webfinger (2.1.3)
       activesupport
       faraday (~> 2.0)
       faraday-follow_redirects
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     websocket-driver (0.7.7)
       base64
       websocket-extensions (>= 0.1.0)
@@ -342,6 +368,7 @@ DEPENDENCIES
   rubocop-rails
   rubocop-rspec
   simplecov
+  webmock
 
 BUNDLED WITH
    2.3.27

gemfiles/rails_7.0.gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: ..
   specs:
     rpi_auth (4.0.0)
+      oauth2
       omniauth-rails_csrf_protection (~> 1.0.0)
       omniauth_openid_connect (~> 0.7.1)
       rails (>= 6.1.4)
@@ -80,6 +81,7 @@ GEM
     ast (2.4.3)
     attr_required (1.0.2)
     base64 (0.2.0)
+    bigdecimal (3.1.9)
     bindata (2.5.1)
     builder (3.3.0)
     byebug (12.0.0)
@@ -94,6 +96,9 @@ GEM
       xpath (~> 3.2)
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
+    crack (1.0.0)
+      bigdecimal
+      rexml
     crass (1.0.6)
     date (3.4.1)
     diff-lcs (1.6.1)
@@ -112,6 +117,7 @@ GEM
     ffi (1.17.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
+    hashdiff (1.1.2)
     hashie (5.0.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
@@ -123,6 +129,8 @@ GEM
       bindata
       faraday (~> 2.0)
       faraday-follow_redirects
+    jwt (2.10.1)
+      base64
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -143,6 +151,8 @@ GEM
     mini_mime (1.1.5)
     mini_portile2 (2.8.8)
     minitest (5.25.5)
+    multi_xml (0.7.1)
+      bigdecimal (~> 3.1)
     net-http (0.6.0)
       uri
     net-imap (0.5.6)
@@ -158,6 +168,13 @@ GEM
     nokogiri (1.18.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
+    oauth2 (2.0.9)
+      faraday (>= 0.17.3, < 3.0)
+      jwt (>= 1.0, < 3.0)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 4)
+      snaky_hash (~> 2.0)
+      version_gem (~> 1.1)
     omniauth (2.1.3)
       hashie (>= 3.4.6)
       rack (>= 2.2.3)
@@ -243,6 +260,7 @@ GEM
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     regexp_parser (2.10.0)
+    rexml (3.4.1)
     rspec-core (3.13.3)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.3)
@@ -296,6 +314,9 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    snaky_hash (2.0.1)
+      hashie
+      version_gem (~> 1.1, >= 1.1.1)
     swd (2.0.3)
       activesupport (>= 3)
       attr_required (>= 0.0.5)
@@ -312,10 +333,15 @@ GEM
     validate_url (1.0.15)
       activemodel (>= 3.0.0)
       public_suffix
+    version_gem (1.1.7)
     webfinger (2.1.3)
       activesupport
       faraday (~> 2.0)
       faraday-follow_redirects
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     websocket-driver (0.7.7)
       base64
       websocket-extensions (>= 0.1.0)
@@ -341,6 +367,7 @@ DEPENDENCIES
   rubocop-rails
   rubocop-rspec
   simplecov
+  webmock
 
 BUNDLED WITH
    2.3.27

gemfiles/rails_7.1.gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: ..
   specs:
     rpi_auth (4.0.0)
+      oauth2
       omniauth-rails_csrf_protection (~> 1.0.0)
       omniauth_openid_connect (~> 0.7.1)
       rails (>= 6.1.4)
@@ -109,6 +110,9 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.0)
+    crack (1.0.0)
+      bigdecimal
+      rexml
     crass (1.0.6)
     date (3.4.1)
     diff-lcs (1.6.1)
@@ -128,6 +132,7 @@ GEM
     ffi (1.17.1)
     globalid (1.2.1)
       activesupport (>= 6.1)
+    hashdiff (1.1.2)
     hashie (5.0.0)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
@@ -144,6 +149,8 @@ GEM
       bindata
       faraday (~> 2.0)
       faraday-follow_redirects
+    jwt (2.10.1)
+      base64
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -164,6 +171,8 @@ GEM
     mini_mime (1.1.5)
     mini_portile2 (2.8.8)
     minitest (5.25.5)
+    multi_xml (0.7.1)
+      bigdecimal (~> 3.1)
     mutex_m (0.3.0)
     net-http (0.6.0)
       uri
@@ -180,6 +189,13 @@ GEM
     nokogiri (1.18.7)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
+    oauth2 (2.0.9)
+      faraday (>= 0.17.3, < 3.0)
+      jwt (>= 1.0, < 3.0)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 4)
+      snaky_hash (~> 2.0)
+      version_gem (~> 1.1)
     omniauth (2.1.3)
       hashie (>= 3.4.6)
       rack (>= 2.2.3)
@@ -282,6 +298,7 @@ GEM
     regexp_parser (2.10.0)
     reline (0.6.1)
       io-console (~> 0.5)
+    rexml (3.4.1)
     rspec-core (3.13.3)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.3)
@@ -336,6 +353,9 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    snaky_hash (2.0.1)
+      hashie
+      version_gem (~> 1.1, >= 1.1.1)
     stringio (3.1.6)
     swd (2.0.3)
       activesupport (>= 3)
@@ -353,10 +373,15 @@ GEM
     validate_url (1.0.15)
       activemodel (>= 3.0.0)
       public_suffix
+    version_gem (1.1.7)
     webfinger (2.1.3)
       activesupport
       faraday (~> 2.0)
       faraday-follow_redirects
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     websocket-driver (0.7.7)
       base64
       websocket-extensions (>= 0.1.0)
@@ -382,6 +407,7 @@ DEPENDENCIES
   rubocop-rails
   rubocop-rspec
   simplecov
+  webmock
 
 BUNDLED WITH
    2.3.27