shopify_app 22.1.0 → 22.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0b7ce0abe557e14db6582b5cefd0bde0837c6e7f380934ddf9754311e8696a5
-  data.tar.gz: 215ce18139c607e2282f2ecf19cbc365f2fff92012bc4ea5e04cc5d3fe33f4ec
+  metadata.gz: 0e3a66e5b90c252c2d65a607911157a50a2d43ac799a70ef61bb5efaeab65013
+  data.tar.gz: 9c145d34b0c9a2f7f587ea2653d660ee7477f90f1348461e52c3dd84c6fc8c6a
 SHA512:
-  metadata.gz: 3ac07379b157096ad6d8c1817058ff2d49401d82af7309c36963b184d2e65053854d02de70cfbebd164a79fa72147a9bda14f209acbb7aadf971f31da9438a1f
-  data.tar.gz: ae2126091214107335550b527ec183499dd38e96bbcee3ac6a5585b287403b74a14c7a260d1929c65abbe6060f243ef64ebf62ba8adf8c8de3c7392316241e83
+  metadata.gz: ca6a9990ca94f975da2139e2e9ca4d85a9e967959e12cb08c2419d5614001b1245f292bff1916f2dfd45002a421a0a65b337148b917e4b56d6406e344c27e456
+  data.tar.gz: 2475faa54148b72d0764e29f101c4f6829f47d049cfcd2b800730a4fa1e6bfe35cf3e26f806366174b9e7a589e7a09143b0a4f9ef20cdbceb2e007b357bc63f3

data/CHANGELOG.md

@@ -1,6 +1,31 @@
 Unreleased
 ----------
 
+22.2.0 (May 2,2024)
+----------
+* Add new zero redirect authorization strategy - `Token Exchange`.
+  - This strategy replaces the existing OAuth flow for embedded apps and remove the redirects that were previously necessary to complete OAuth.
+  See ["New embedded app authorization strategy"](/README.md/#new-embedded-app-authorization-strategy) for how to enable this feature.
+  - Related PRs: [#1817](https://github.com/Shopify/shopify_app/pull/1817),
+  [#1818](https://github.com/Shopify/shopify_app/pull/1818),
+  [#1819](https://github.com/Shopify/shopify_app/pull/1819),
+  [#1821](https://github.com/Shopify/shopify_app/pull/1821),
+  [#1822](https://github.com/Shopify/shopify_app/pull/1822),
+  [#1823](https://github.com/Shopify/shopify_app/pull/1823),
+  [#1832](https://github.com/Shopify/shopify_app/pull/1832),
+  [#1833](https://github.com/Shopify/shopify_app/pull/1833),
+  [#1834](https://github.com/Shopify/shopify_app/pull/1834),
+  [#1836](https://github.com/Shopify/shopify_app/pull/1836),
+* Bumps `shopify_api` to `14.3.0` [1832](https://github.com/Shopify/shopify_app/pull/1832)
+* Support `id_token` from URL param [1832](https://github.com/Shopify/shopify_app/pull/1832)
+  * Extracted controller concern `WithShopifyIdToken`
+      * This concern provides a method `shopify_id_token` to retrieve the Shopify Id token from either the authorization header or the URL param `id_token`.
+  * `ShopifyApp::JWTMiddleware` supports retrieving session token from URL param `id_token`
+  * `ShopifyApp::JWTMiddleware` returns early if the app is not embedded to avoid unnecessary JWT verification
+  * `LoginProtection` now uses `WithShopifyIdToken` concern to retrieve the Shopify Id token, thus accepting the session token from the URL param `id_token`
+* Marking `ShopifyApp::JWT` to be deprecated in version 23.0.0 [1832](https://github.com/Shopify/shopify_app/pull/1832), use `ShopifyAPI::Auth::JwtPayload` instead.
+* Fix infinite redirect loop caused by handling errors from Billing API [1833](https://github.com/Shopify/shopify_app/pull/1833)
+
 22.1.0 (April 9,2024)
 ----------
 * Extracted class - `PostAuthenticateTasks` to handle post authenticate tasks. To learn more, see [post authenticate tasks](/docs/shopify_app/authentication.md#post-authenticate-tasks). [1819](https://github.com/Shopify/shopify_app/pull/1819)

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    shopify_app (22.1.0)
+    shopify_app (22.2.0)
       activeresource
       addressable (~> 2.7)
       jwt (>= 2.2.3)
       rails (> 5.2.1)
       redirect_safely (~> 1.0)
-      shopify_api (>= 14.1.0, < 15.0)
+      shopify_api (>= 14.3.0, < 15.0)
       sprockets-rails (>= 2.0.0)
 
 GEM
@@ -217,7 +217,7 @@ GEM
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     securerandom (0.2.2)
-    shopify_api (14.1.0)
+    shopify_api (14.3.0)
       activesupport
       concurrent-ruby
       hash_diff

data/README.md

@@ -129,6 +129,44 @@ These routes are configurable. See the more detailed [*Engine*](/docs/shopify_ap
 
 To learn more about how this gem authenticates with Shopify, see [*Authentication*](/docs/shopify_app/authentication.md).
 
+### New embedded app authorization strategy (Token Exchange)
+
+> [!TIP]
+> If you are building an embedded app, we **strongly** recommend using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+> with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) instead of the legacy authorization code grant flow.
+
+We've introduced a new installation and authorization strategy for **embedded apps** that
+eliminates the redirects that were previously necessary.
+It replaces the existing [installation and authorization code grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant).
+
+This is achieved by using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+to handle automatic app installations and scope updates, while utilizing
+[token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to retrieve an access token for
+authenticated API access.
+
+##### Enabling this new strategy in your app
+
+1. Enable [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+    by configuring your scopes [through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration).
+2. Enable the new auth strategy in your app's ShopifyApp configuration file.
+
+```ruby
+# config/initializers/shopify_app.rb
+ShopifyApp.configure do |config|
+  #.....
+  config.embedded_app = true
+  config.new_embedded_auth_strategy = true
+
+  # If your app is configured to use online sessions, you can enable session expiry date check so a new access token
+  # is fetched automatically when the session expires.
+  # See expiry date check docs: https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md#expiry-date
+  config.check_session_expiry_date = true
+  ...
+end
+
+```
+3. Enjoy a smoother and faster app installation process.
+
 ### API Versioning
 
 [Shopify's API is versioned](https://shopify.dev/concepts/about-apis/versioning). With Shopify App `v1.11.0`, the included Shopify API gem allows developers to specify and update the Shopify API version they want their app or service to use. The Shopify API gem also surfaces warnings to Rails apps about [deprecated endpoints, GraphQL fields and more](https://shopify.dev/concepts/about-apis/versioning#deprecation-practices).

data/app/controllers/concerns/shopify_app/ensure_installed.rb

@@ -17,9 +17,10 @@ module ShopifyApp
 
       before_action :check_shop_domain
 
-      unless ShopifyApp.configuration.use_new_embedded_auth_strategy?
-        # TODO: Add support to use new embedded auth strategy here when invalid
-        # session token can be handled by AppBridge app reload
+      if ShopifyApp.configuration.use_new_embedded_auth_strategy?
+        include ShopifyApp::TokenExchange
+        around_action :activate_shopify_session
+      else
         before_action :check_shop_known
         before_action :validate_non_embedded_session
       end

data/app/controllers/shopify_app/sessions_controller.rb

@@ -7,7 +7,7 @@ module ShopifyApp
 
     layout false, only: :new
 
-    after_action only: [:new, :create] do |controller|
+    after_action only: [:new, :create, :patch_shopify_id_token] do |controller|
       controller.response.headers.except!("X-Frame-Options")
     end
 
@@ -19,6 +19,10 @@ module ShopifyApp
       authenticate
     end
 
+    def patch_shopify_id_token
+      render(layout: "shopify_app/layouts/app_bridge")
+    end
+
     def top_level_interaction
       @url = login_url_with_optional_shop(top_level: true)
       validate_shop_presence

data/app/views/shopify_app/layouts/app_bridge.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title><%= ShopifyApp.configuration.application_name %></title>
+    <%= yield :head %>
+    <script
+      data-api-key="<%= ShopifyApp.configuration.api_key %>"
+      src="https://cdn.shopify.com/shopifycloud/app-bridge.js">
+    </script>
+    <%= csrf_meta_tags %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/config/routes.rb

@@ -8,6 +8,7 @@ ShopifyApp::Engine.routes.draw do
     get login_url => :new, :as => :login
     post login_url => :create, :as => :authenticate
     get "logout" => :destroy, :as => :logout
+    get "patch_shopify_id_token" => :patch_shopify_id_token
 
     # Kept to prevent apps relying on these routes from breaking
     if login_url.gsub(%r{^/}, "") != "login"

data/docs/Troubleshooting.md

@@ -92,29 +92,6 @@ Edit `config/initializer/shopify_app.rb` and ensure the following configurations
 + config.shop_session_repository = 'Shop'
 ```
 
-#### Inspect server logs
-
-If you have checked the configurations above, and the app is still using cookies, then it is possible that the `shopify_app` gem defaulted to relying on cookies. This would happen when your browser allows third-party cookies and a session token was not successfully found as part of your request.
-
-In this case, check the server logs to see if the session token was invalid:
-
-```los
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::<Error>] <Failure message>
-```
-
-*Example*
-
-```
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::ImmatureSignature] Signature nbf has not been reached
-```
-
-**Note:** In a local development environment, you may want to temporarily update your `Gemfile` to point to a local instance of the `shopify_app` library instad of an installed gem. This will enable you to use a debugging tool like `byebug` to debug the library.
-
-```diff
-- gem 'shopify_app', '~> 14.2'
-+ gem 'shopify_app', path: '/path/to/shopify_app'
-```
-
 ### My app can't make requests to the Shopify API
 
 > **Note:** Session tokens cannot be used to make authenticated requests to the Shopify API. Learn more about authenticating your backend requests to Shopify APIs at [Shopify API authentication](https://shopify.dev/concepts/about-apis/authentication).

data/docs/Upgrading.md

@@ -8,6 +8,8 @@ This file documents important changes needed to upgrade your app's Shopify App v
 
 [Unreleased](#unreleased)
 
+[Upgrading to `v22.2.0`](#upgrading-to-v2220)
+
 [Upgrading to `v22.0.0`](#upgrading-to-v2200)
 
 [Upgrading to `v20.3.0`](#upgrading-to-v2030)
@@ -51,6 +53,18 @@ If you have overwritten these methods in your callback controller to modify the
 update your app to use configurable option `config.custom_post_authenticate_tasks` instead. See [post authenticate tasks](/docs/shopify_app/authentication.md#post-authenticate-tasks)
 for more information.
 
+#### (v23.0.0) - Deprecated "ShopifyApp::JWT" class
+The `ShopifyApp::JWT` class has been deprecated in `v23.0.0`. Use [ShopifyAPI::Auth::JwtPayload](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/jwt_payload.rb)
+class from the `shopify_api` gem instead. A search and replace should be enough for this migration.
+  - `ShopifyAPI::Auth::JwtPayload` is a superset of the `ShopifyApp::JWT` class, and contains methods that were available in `ShopifyApp::JWT`. 
+  - `ShopifyAPI::Auth::JwtPayload` raises `ShopifyAPI::Errors::InvalidJwtTokenError` if the token is invalid.
+
+## Upgrading to `v22.2.0`
+#### Added new feature for zero redirect embedded app authorization flow - Token Exchange
+A new embedded app authorization strategy has been introduced in `v22.2.0` that eliminates the redirects that were previously necessary for OAuth. 
+It can replace the existing installation and authorization code grant flow.
+See [new embedded app authorization strategy](./README.md#new-embedded-app-authorization-strategy) for more information.
+
 ## Upgrading to `v22.0.0`
 #### Dropped support for Ruby 2.x
 Support for Ruby 2.x has been dropped as it is no longer supported. You'll need to upgrade to 3.x.x

data/docs/shopify_app/authentication.md

@@ -10,17 +10,73 @@ See [*Getting started with session token authentication*](https://shopify.dev/do
 
 #### Table of contents
 
-* [OAuth callback](#oauth-callback)
-  * [Customizing callback controller](#customizing-callback-controller)
+* [Supported types of OAuth Flow](#supported-types-of-oauth)
+  * [Token Exchange](#token-exchange)
+  * [Authorization Code Grant Flow](#authorization-code-grant-flow)
+    * [OAuth callback](#oauth-callback)
+      * [Customizing callback controller](#customizing-callback-controller)
+    * [Detecting scope changes](#detecting-scope-changes-1)
 * [Run jobs after the OAuth flow](#post-authenticate-tasks)
 * [Rotate API credentials](#rotate-api-credentials)
 * [Making authenticated API requests after authorization](#making-authenticated-api-requests-after-authorization)
 
-## OAuth callback
+## Supported types of OAuth
+> [!TIP]
+> If you are building an embedded app, we **strongly** recommend using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+with [token exchange](#token-exchange) instead of the authorization code grant flow.
 
->️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
+1. [Token Exchange](#token-exchange)
+    - Recommended and is only available for embedded apps
+    - Doesn't require redirects, which makes authorization faster and prevents flickering when loading the app
+    - Access scope changes are handled by Shopify when you use [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+2. [Authorization Code Grant Flow](#authorization-code-grant-flow)
+    - Suitable for non-embedded apps
+    - Installations, and access scope changes are managed by the app
 
-Upon completing the OAuth flow, Shopify calls the app at `ShopifyApp.configuration.login_callback_url`.
+## Token Exchange
+
+OAuth process by exchanging the current user's [session token (shopify id token)](https://shopify.dev/docs/apps/auth/session-tokens) for an
+[access token](https://shopify.dev/docs/apps/auth/access-token-types/online.md) to make
+authenticated Shopify API queries. This will replace authorization code grant flow completely when your app is configured with [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
+
+To enable token exchange authorization strategy, you can follow the steps in ["New embedded app authorization strategy"](/README.md#new-embedded-app-authorization-strategy).
+Upon completion of the token exchange to get the access token, [post authenticated tasks](#post-authenticate-tasks) will be run.
+
+Learn more about:
+- [How token exchange works](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange)
+- [Using Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+- [Configuring access scopes through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration)
+
+#### Handling invalid access tokens
+If the access token used to make an API call is invalid, the token exchange strategy will handle the error and try to retrieve a new access token before retrying 
+the same operation. 
+See ["Re-fetching an access token when API returns Unauthorized"](/docs/shopify_app/sessions.md#re-fetching-an-access-token-when-api-returns-unauthorized) section for more information.
+
+#### Detecting scope changes
+
+##### Shopify managed installation
+If your access scopes are [configured through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration), scope changes will be handled by Shopify automatically.
+Learn more about [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
+Using token exchange will ensure that the access token retrieved will always have the latest access scopes granted by the user.
+
+## Authorization Code Grant Flow
+Authorization code grant flow is the OAuth flow that requires the app to redirect the user 
+to Shopify for installation/authorization of the app to access the shop's data. It is still required for apps that are not embedded.
+
+To perform [authorization code grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant), you app will need to handle
+[begin OAuth](#begin-oauth) and [OAuth callback](#oauth-callback) routes.
+
+### Begin OAuth
+ShopifyApp automatically redirects the user to Shopify to complete OAuth to install the app when the `ShopifyApp.configuration.login_url` is reached.
+Behind the scenes the ShopifyApp gem starts the process by calling `ShopifyAPI::Auth::Oauth.begin_auth` to build the 
+redirect URL with necessary parameters like the OAuth callback URL, scopes requested, type of access token (offline or online) requested, etc.
+The ShopifyApp gem then redirect the merchant to Shopify, to ask for permission to install the app. (See [ShopifyApp::SessionsController.redirect_to_begin_oauth](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/sessions_controller.rb#L76-L96)
+for detailed implementation)
+
+### OAuth callback
+
+Shopify will redirect the merchant back to your app's callback URL once they approve the app installation.
+Upon completing the OAuth flow, Shopify calls the app at `ShopifyApp.configuration.login_callback_url`. (This was provided to Shopify in the OAuth begin URL parameters)
 
 The default callback controller [`ShopifyApp::CallbackController`](../../app/controllers/shopify_app/callback_controller.rb) provides the following behaviour:
 
@@ -63,7 +119,14 @@ Rails.application.routes.draw do
 end
 ```
 
-### Post Authenticate tasks
+### Detecting scope changes
+When the OAuth process is completed, the created session has a `scope` field which holds all of the access scopes that were requested from the merchant at the time.
+
+When an app's access scopes change, it needs to request merchants to go through OAuth again to renew its permissions.
+
+See [Handling changes in access scopes](/docs/shopify_app/handling-access-scopes-changes.md).
+
+## Post Authenticate tasks
 After authentication is complete, a few tasks are run by default by PostAuthenticateTasks:
 1. [Installing Webhooks](/docs/shopify_app/webhooks.md)
 2. [Run configured after_authenticate_job](#after_authenticate_job)

data/docs/shopify_app/sessions.md

@@ -3,12 +3,11 @@
 Sessions are used to make contextual API calls for either a shop (offline session) or a user (online session). This gem has ownership of session persistence.
 
 #### Table of contents
-
 - [Sessions](#sessions)
       - [Table of contents](#table-of-contents)
   - [Sessions](#sessions-1)
-      - [Types of session tokens](#types-of-session-tokens)
-      - [Session token storage](#session-token-storage)
+      - [Types of access tokens (sessions)](#types-of-access-tokens-sessions)
+      - [Access token storage (session)](#access-token-storage-session)
         - [Shop (offline) token storage](#shop-offline-token-storage)
         - [User (online) token storage](#user-online-token-storage)
         - [In-memory Session Storage for testing](#in-memory-session-storage-for-testing)
@@ -20,6 +19,7 @@ Sessions are used to make contextual API calls for either a shop (offline sessio
         - [**Shop Sessions - `EnsureInstalled`**](#shop-sessions---ensureinstalled)
         - [User Sessions - `EnsureHasSession`](#user-sessions---ensurehassession)
       - [Getting sessions from a Shop or User model record - 'with\_shopify\_session'](#getting-sessions-from-a-shop-or-user-model-record---with_shopify_session)
+      - [Re-fetching an access token when API returns Unauthorized](#re-fetching-an-access-token-when-api-returns-unauthorized)
   - [Access scopes](#access-scopes)
     - [`ShopifyApp::ShopSessionStorageWithScopes`](#shopifyappshopsessionstoragewithscopes)
     - [`ShopifyApp::UserSessionStorageWithScopes`](#shopifyappusersessionstoragewithscopes)
@@ -27,18 +27,16 @@ Sessions are used to make contextual API calls for either a shop (offline sessio
   - [Migrating from `ShopifyApi::Auth::SessionStorage` to `ShopifyApp::SessionStorage`](#migrating-from-shopifyapiauthsessionstorage-to-shopifyappsessionstorage)
 
 ## Sessions
-#### Types of session tokens
-- **Shop** ([offline access](https://shopify.dev/docs/apps/auth/oauth/access-modes#offline-access))
+#### Types of access tokens (sessions)
+- **Shop** ([offline access](https://shopify.dev/docs/apps/auth/access-token-types/offline))
   - Access token is linked to the store
   - Meant for long-term access to a store, where no user interaction is involved
   - Ideal for background jobs or maintenance work
-- **User** ([online access](https://shopify.dev/docs/apps/auth/oauth/access-modes#online-access))
+- **User** ([online access](https://shopify.dev/docs/apps/auth/access-token-types/online))
   - Access token is linked to an individual user on a store
   - Meant to be used when a user is interacting with your app through the web
 
-⚠️  [Read more about Online vs. Offline access here](https://shopify.dev/apps/auth/oauth/access-modes).
-
-#### Session token storage
+#### Access token storage (session)
 ##### Shop (offline) token storage
 ⚠️ All apps must have a shop session storage, if you started from the [Ruby App Template](https://github.com/Shopify/shopify-app-template-ruby), it's already configured to have a Shop model by default.
 
@@ -50,7 +48,7 @@ If you don't already have a repository to store the access tokens:
 rails generate shopify_app:shop_model
 ```
 
-2. Configure `config/initializers/shopify_app.rb` to enable shop session token persistance:
+2. Configure `config/initializers/shopify_app.rb` to enable shop access token persistance:
 
 ```ruby
 config.shop_session_repository = 'Shop'
@@ -66,7 +64,7 @@ If your app has user interactions and would like to control permission based on
 rails generate shopify_app:user_model
 ```
 
-2. Configure `config/initializers/shopify_app.rb` to enable user session token persistance:
+2. Configure `config/initializers/shopify_app.rb` to enable user access token persistance:
 
 ```ruby
 config.user_session_repository = 'User'
@@ -74,6 +72,8 @@ config.user_session_repository = 'User'
 
 The current Shopify user will be stored in the rails session at `session[:shopify_user]`
 
+You should also enable the [check for session expiry](#expiry-date) so that a new access token can be fetched before being used for an API operation.
+
 ##### In-memory Session Storage for testing
 The `ShopifyApp` gem includes methods for in-memory storage for both shop and user sessions. In-memory storage is intended to be used in a testing environment, please use a persistent storage for your application.
 - [InMemoryShopSessionStore](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/in_memory_shop_session_store.rb)
@@ -152,7 +152,7 @@ class MyController < ApplicationController
 
     client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_session)
     client.query(
-    #...
+      # ...
     )
   end
 end
@@ -171,7 +171,7 @@ class MyController < ApplicationController
 
     client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_session)
     client.query(
-    #...
+      # ...
     )
   end
 end
@@ -203,6 +203,100 @@ user.with_shopify_session do
 end
 ```
 
+#### Re-fetching an access token when API returns Unauthorized
+
+When using `ShopifyApp::EnsureHasSession` and the `new_embedded_auth_strategy` configuration, any **unhandled** Unauthorized `ShopifyAPI::Errors::HttpResponseError` will cause the app to perform token exchange to fetch a new access token from Shopify and the action to be executed again. This will update and store the new access token to the current session instance.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+
+    # If this call raises an Unauthorized error from Shopify, EnsureHasSession
+    # will execute the action again after performing token exchange.
+    # It will store and use the newly retrieved access token for this and any subsequent calls.
+    client.query(options)
+  end
+end
+```
+
+If the error is being rescued in the action, it's still possible to make use of `with_token_refetch` provided by `EnsureHasSession` so that a new access token is fetched and the code is executed again with it. This will also update the session parameter with the new attributes.
+This block should be used to wrap the code that makes API queries, so your business logic won't be retried.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    # Your app's business logic
+    with_token_refetch(current_shopify_session, shopify_id_token) do
+      # Unauthorized errors raised within this block will initiate token exchange.
+      # `with_token_refetch` will store the new access token and use it
+      # to execute this block again.
+      # Any subsequent calls using the same session instance will have the new token.
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+      client.query(options)
+    end
+    # Your app's business logic continues
+  rescue => error
+    # app's specific error handling
+  end
+end
+```
+
+It's also possible to use `with_token_refetch` on classes other than the controller by including the `ShopifyApp::AdminAPI::WithTokenRefetch` module and passing in the session along with the current request's `shopify_id_token`, which is provided by `ShopifyApp::EnsureHasSession`. This will also update the session parameter with the new attributes.
+
+```ruby
+# my_controller.rb
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    # shopify_id_token is a method provided by EnsureHasSession
+    MyClass.new.do_things(current_shopify_session, shopify_id_token)
+  end
+end
+
+# my_class.rb
+class MyClass
+  include ShopifyApp::AdminAPI::WithTokenRefetch
+
+  def do_things(session, shopify_id_token)
+    with_token_refetch(session, shopify_id_token) do
+      # Unauthorized errors raised within this block will initiate token exchange.
+      # `with_token_refetch` will store the new access token and use it
+      # to execute this block again.
+      # Any subsequent calls using the same session instance will have the new token.
+      client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+      client.query(options)
+    end
+  rescue => error
+    # app's specific error handling
+  end
+end
+```
+
+If the retried block raises an `Unauthorized` error again, `with_token_refetch` will delete the current `session` from the database and raise the error again.
+
+```ruby
+class MyController < ApplicationController
+  include ShopifyApp::EnsureHasSession
+
+  def index
+    client = ShopifyAPI::Clients::Graphql::Admin.new(session: current_shopify_session)
+    with_token_refetch(current_shopify_session, shopify_id_token) do
+      # When this call raises Unauthorized a second time during retry,
+      # the `session` will be deleted from the database and the error raised
+      client.query(options)
+    end
+  rescue => error
+    # The Unauthorized error will reach this rescue
+  end
+end
+```
+
 ## Access scopes
 If you want to customize how access scopes are stored for shops and users, you can implement the `access_scopes` getters and setters in the models that include `ShopifyApp::ShopSessionStorageWithScopes` and `ShopifyApp::UserSessionStorageWithScopes` as shown:
 
@@ -240,6 +334,8 @@ When the configuration flag `check_session_expiry_date` is set to true, the user
 ## Migrating from shop-based to user-based token strategy
 
 1. Run the `user_model` generator as [mentioned above](#user-online-token-storage).
+  - The generator will ask whether you want to migrate the User model to include `access_scopes` and `expires_at` columns. `expires_at` field is useful for detecting when the user session has expired and trigger a re-auth before an operation. It can reduce
+   API failures for invalid access tokens. Configure the [expiry date check](#expiry-date) to complete this feature.
 2. Ensure that both your `Shop` model and `User` model includes the [necessary concerns](#available-activesupportconcerns-that-contains-implementation-of-the-above-methods)
 3. Update the configuration file to use the new session storage.
 
@@ -255,5 +351,5 @@ config.user_session_repository = {YOUR_USER_MODEL_CLASS}
 - Sessions storage are now handled with [ShopifyApp::SessionRepository](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/session_repository.rb)
 - To migrate and specify your shop or user session storage method:
   1. Remove `session_storage` configuration from `config/initializers/shopify_app.rb`
-  2. Follow ["Session Token Storage" instructions](#session-token-storage) to specify the storage repository for shop and user sessions.
+  2. Follow ["Access Token Storage" instructions](#access-token-storage-session) to specify the storage repository for shop and user sessions.
      - [Customizing session storage](#customizing-session-storage-with-shopifyappsessionrepository)

data/lib/generators/shopify_app/install/templates/shopify_app.rb.tt

@@ -4,6 +4,8 @@ ShopifyApp.configure do |config|
   config.scope = "<%= @scope %>" # Consult this page for more scope options:
                                   # https://help.shopify.com/en/api/getting-started/authentication/oauth/scopes
   config.embedded_app = <%= embedded_app? %>
+  config.new_embedded_auth_strategy = <%= embedded_app? %>
+
   config.after_authenticate_job = false
   config.api_version = "<%= @api_version %>"
   config.shop_session_repository = 'Shop'

data/lib/shopify_app/admin_api/with_token_refetch.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ShopifyApp
+  module AdminAPI
+    module WithTokenRefetch
+      def with_token_refetch(session, shopify_id_token)
+        retrying = false if retrying.nil?
+        yield
+      rescue ShopifyAPI::Errors::HttpResponseError => error
+        if error.code != 401
+          ShopifyApp::Logger.debug("Encountered error: #{error.code} - #{error.response.inspect}, re-raising")
+        elsif retrying
+          ShopifyApp::Logger.debug("Shopify API returned a 401 Unauthorized error that was not corrected " \
+            "with token exchange, deleting current session and re-raising")
+          ShopifyApp::SessionRepository.delete_session(session.id)
+        else
+          retrying = true
+          ShopifyApp::Logger.debug("Shopify API returned a 401 Unauthorized error, exchanging token and " \
+            "retrying with new session")
+          new_session = ShopifyApp::Auth::TokenExchange.perform(shopify_id_token)
+          session.copy_attributes_from(new_session)
+          retry
+        end
+        raise
+      end
+    end
+  end
+end

data/lib/shopify_app/auth/token_exchange.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ShopifyApp
+  module Auth
+    class TokenExchange
+      attr_reader :id_token
+
+      def self.perform(id_token)
+        new(id_token).perform
+      end
+
+      def initialize(id_token)
+        @id_token = id_token
+      end
+
+      def perform
+        domain = ShopifyAPI::Auth::JwtPayload.new(id_token).shopify_domain
+
+        Logger.info("Performing Token Exchange for [#{domain}] - (Offline)")
+        session = exchange_token(
+          shop: domain,
+          id_token: id_token,
+          requested_token_type: ShopifyAPI::Auth::TokenExchange::RequestedTokenType::OFFLINE_ACCESS_TOKEN,
+        )
+
+        if online_token_configured?
+          Logger.info("Performing Token Exchange for [#{domain}] - (Online)")
+          session = exchange_token(
+            shop: domain,
+            id_token: id_token,
+            requested_token_type: ShopifyAPI::Auth::TokenExchange::RequestedTokenType::ONLINE_ACCESS_TOKEN,
+          )
+        end
+
+        ShopifyApp.configuration.post_authenticate_tasks.perform(session)
+
+        session
+      end
+
+      private
+
+      def exchange_token(shop:, id_token:, requested_token_type:)
+        session = ShopifyAPI::Auth::TokenExchange.exchange_token(
+          shop: shop,
+          session_token: id_token,
+          requested_token_type: requested_token_type,
+        )
+
+        SessionRepository.store_session(session)
+
+        session
+      rescue ShopifyAPI::Errors::InvalidJwtTokenError
+        Logger.error("Invalid id token '#{id_token}' during token exchange")
+        raise
+      rescue ShopifyAPI::Errors::HttpResponseError => error
+        Logger.error(
+          "A #{error.code} error (#{error.class}) occurred during the token exchange. Response: #{error.response.body}",
+        )
+        raise
+      rescue ActiveRecord::RecordNotUnique
+        Logger.debug("Session not stored due to concurrent token exchange calls")
+        session
+      rescue => error
+        Logger.error("An error occurred during the token exchange: [#{error.class}] #{error.message}")
+        raise
+      end
+
+      def online_token_configured?
+        ShopifyApp.configuration.online_token_configured?
+      end
+    end
+  end
+end