shopify_app 22.0.1 → 22.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ea486458223aad4ec68fd15a99a340d79ae306e95b8596ca7b9f447b0ac237c
-  data.tar.gz: 7cfc9f51c225a89a3aacf87fc6cd3724c3c69399c60588cab9ac821f32b9bde0
+  metadata.gz: 0e3a66e5b90c252c2d65a607911157a50a2d43ac799a70ef61bb5efaeab65013
+  data.tar.gz: 9c145d34b0c9a2f7f587ea2653d660ee7477f90f1348461e52c3dd84c6fc8c6a
 SHA512:
-  metadata.gz: 6c3c7f2426c24946ab299bb2499e5065c16828fe72ff8160f7d114c96ba7ff658d032494f418d58668ff0ad2fc53288a237fa92f35950e8028aeb0cd551b9d4d
-  data.tar.gz: e86005c3bde23478adc4444ff93274f3c6e4646f063399eb80f9165ab2a0b56765209038d49174889d2e026519296f4b44a929ce0201be5bc25c2c98470f3258
+  metadata.gz: ca6a9990ca94f975da2139e2e9ca4d85a9e967959e12cb08c2419d5614001b1245f292bff1916f2dfd45002a421a0a65b337148b917e4b56d6406e344c27e456
+  data.tar.gz: 2475faa54148b72d0764e29f101c4f6829f47d049cfcd2b800730a4fa1e6bfe35cf3e26f806366174b9e7a589e7a09143b0a4f9ef20cdbceb2e007b357bc63f3

data/.github/workflows/rubocop.yml

@@ -8,10 +8,9 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Ruby 3.2
+    - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.2
         bundler-cache: true
     - name: Install gems
       run: |

data/.rubocop.yml

@@ -2,7 +2,6 @@ inherit_gem:
     rubocop-shopify: rubocop.yml
 
 AllCops:
-  TargetRubyVersion: 2.7
   Exclude:
     - 'test/tmp/**/*'
     - 'vendor/bundle/**/*'

data/CHANGELOG.md

@@ -1,6 +1,36 @@
 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)
+* Bumps shopify_api dependency to 14.1.0 [1826](https://github.com/Shopify/shopify_app/pull/1826)
+
 22.0.1 (March 12, 2024)
 ----------
 * Bumps `shopify_api` to `14.0.1` [1813](https://github.com/Shopify/shopify_app/pull/1813)

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    shopify_app (22.0.1)
+    shopify_app (22.2.0)
       activeresource
       addressable (~> 2.7)
       jwt (>= 2.2.3)
       rails (> 5.2.1)
       redirect_safely (~> 1.0)
-      shopify_api (>= 14.0.1, < 15.0)
+      shopify_api (>= 14.3.0, < 15.0)
       sprockets-rails (>= 2.0.0)
 
 GEM
@@ -104,7 +104,7 @@ GEM
       multi_xml (>= 0.5.2)
     i18n (1.13.0)
       concurrent-ruby (~> 1.0)
-    json (2.6.3)
+    json (2.7.2)
     jwt (2.7.0)
     language_server-protocol (3.17.0.3)
     loofah (2.21.3)
@@ -140,9 +140,10 @@ GEM
       racc (~> 1.4)
     oj (3.14.3)
     openssl (3.1.0)
-    parallel (1.23.0)
-    parser (3.2.2.1)
+    parallel (1.24.0)
+    parser (3.3.0.5)
       ast (~> 2.4.1)
+      racc
     prettier_print (1.2.1)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -192,20 +193,21 @@ GEM
     rb-readline (0.5.5)
     redirect_safely (1.0.0)
       activemodel
-    regexp_parser (2.8.0)
-    rexml (3.2.5)
-    rubocop (1.51.0)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rubocop (1.62.1)
       json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.28.1)
-      parser (>= 3.2.1.0)
+    rubocop-ast (1.31.2)
+      parser (>= 3.3.0.4)
     rubocop-shopify (2.13.0)
       rubocop (~> 1.50)
     ruby-lsp (0.5.1)
@@ -215,7 +217,7 @@ GEM
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
     securerandom (0.2.2)
-    shopify_api (14.0.1)
+    shopify_api (14.3.0)
       activesupport
       concurrent-ruby
       hash_diff
@@ -234,16 +236,16 @@ GEM
       actionpack (>= 5.2)
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
-    sqlite3 (1.6.3-arm64-darwin)
-    sqlite3 (1.6.3-x86_64-darwin)
-    sqlite3 (1.6.3-x86_64-linux)
+    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86_64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
     syntax_tree (6.1.1)
       prettier_print (>= 1.2.0)
     thor (1.2.2)
     timeout (0.3.2)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.4.2)
+    unicode-display_width (2.5.0)
     webmock (3.18.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -256,6 +258,7 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  arm64-darwin-23
   x86_64-darwin-19
   x86_64-darwin-20
   x86_64-darwin-21

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_has_session.rb

@@ -6,14 +6,20 @@ module ShopifyApp
 
     included do
       include ShopifyApp::Localization
-      include ShopifyApp::LoginProtection
+
+      if ShopifyApp.configuration.use_new_embedded_auth_strategy?
+        include ShopifyApp::TokenExchange
+        around_action :activate_shopify_session
+      else
+        include ShopifyApp::LoginProtection
+        before_action :login_again_if_different_user_or_shop
+        around_action :activate_shopify_session
+        after_action :add_top_level_redirection_headers
+      end
+
       include ShopifyApp::CsrfProtection
       include ShopifyApp::EmbeddedApp
       include ShopifyApp::EnsureBilling
-
-      before_action :login_again_if_different_user_or_shop
-      around_action :activate_shopify_session
-      after_action :add_top_level_redirection_headers
     end
   end
 end

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

@@ -16,8 +16,14 @@ module ShopifyApp
       end
 
       before_action :check_shop_domain
-      before_action :check_shop_known
-      before_action :validate_non_embedded_session
+
+      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
     end
 
     def current_shopify_domain

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

@@ -6,7 +6,11 @@ module ShopifyApp
     include ShopifyApp::RedirectForEmbedded
 
     included do
-      before_action :login_on_scope_changes
+      # Embedded auth strategy uses Shopify managed install to ensure latest access scopes,
+      # This will be handled automatically through token exchange
+      unless ShopifyApp.configuration.use_new_embedded_auth_strategy?
+        before_action :login_on_scope_changes
+      end
     end
 
     protected

data/app/controllers/shopify_app/callback_controller.rb

@@ -23,7 +23,16 @@ module ShopifyApp
 
       return respond_with_user_token_flow if start_user_token_flow?(api_session)
 
-      perform_post_authenticate_jobs(api_session)
+      if ShopifyApp::VERSION < "23.0"
+        # deprecated in 23.0
+        if ShopifyApp.configuration.custom_post_authenticate_tasks.present?
+          ShopifyApp.configuration.post_authenticate_tasks.perform(api_session)
+        else
+          perform_post_authenticate_jobs(api_session)
+        end
+      else
+        ShopifyApp.configuration.post_authenticate_tasks.perform(api_session)
+      end
       redirect_to_app if check_billing(api_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
@@ -37,6 +41,22 @@ module ShopifyApp
     def authenticate
       return render_invalid_shop_error unless sanitized_shop_name.present?
 
+      if ShopifyApp.configuration.use_new_embedded_auth_strategy?
+        ShopifyApp::Logger.debug("Starting OAuth - Redirecting to Shopify managed install")
+        start_install
+      else
+        ShopifyApp::Logger.debug("Starting OAuth - Redirecting to begin auth")
+        start_oauth
+      end
+    end
+
+    def start_install
+      shop_name = sanitized_shop_name.split(".").first
+      install_path = "https://admin.shopify.com/store/#{shop_name}/oauth/install?client_id=#{ShopifyApp.configuration.api_key}"
+      redirect_to(install_path, allow_other_host: true)
+    end
+
+    def start_oauth
       copy_return_to_param_to_session
 
       if embedded_redirect_url?
@@ -44,16 +64,16 @@ module ShopifyApp
         if embedded_param?
           redirect_for_embedded
         else
-          start_oauth
+          redirect_to_begin_oauth
         end
       elsif top_level?
-        start_oauth
+        redirect_to_begin_oauth
       else
         redirect_auth_to_top_level
       end
     end
 
-    def start_oauth
+    def redirect_to_begin_oauth
       callback_url = ShopifyApp.configuration.login_callback_url.gsub(%r{^/}, "")
       ShopifyApp::Logger.debug("Starting OAuth with the following callback URL: #{callback_url}")
 

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)
@@ -40,6 +42,29 @@ We also recommend the use of a staging site which matches your production enviro
 
 If you do run into issues, we recommend looking at our [debugging tips.](https://github.com/Shopify/shopify_app/blob/main/docs/Troubleshooting.md#debugging-tips)
 
+## Unreleased
+#### (v23.0.0) - Deprecated methods in CallbackController
+The following methods from `ShopifyApp::CallbackController` have been deprecated in `v23.0.0`
+- `perform_after_authenticate_job`
+- `install_webhooks`
+- `perform_post_authenticate_jobs`
+
+If you have overwritten these methods in your callback controller to modify the behavior of the inherited `CallbackController`, you will need to
+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,31 +10,83 @@ See [*Getting started with session token authentication*](https://shopify.dev/do
 
 #### Table of contents
 
-* [OAuth callback](#oauth-callback)
-  * [Customizing callback controller](#customizing-callback-controller)
-* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+* [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:
 
 1. Logging into the shop and resetting the session
 2. Storing the session to the `SessionRepository`
-3. [Installing Webhooks](/docs/shopify_app/webhooks.md)
-4. [Setting Scripttags](/docs/shopify_app/script-tags.md)
-5. [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
-6. Redirecting to the return address
-
+3. [Post authenticate tasks](#post-authenticate-tasks)
+4. Redirecting to the return address
 
 #### Customizing callback controller
-If the app needs to do some extra work, it can define and configure the route to a custom callback controller.
-Inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods.
+If you need to define a custom callback controller to handle your app's use case, you can configure the callback route to your controller.
 
 Example:
 
@@ -42,11 +94,9 @@ Example:
 ```ruby
 # web/app/controllers/my_custom_callback_controller.rb
 
-class MyCustomCallbackController < ShopifyApp::CallbackController
-  private
-
-  def install_webhooks(session)
-    # My custom override/definition to install webhooks
+class MyCustomCallbackController
+  def callback
+    # My custom callback logic
   end
 end
 ```
@@ -69,11 +119,46 @@ Rails.application.routes.draw do
 end
 ```
 
-### Run jobs after the OAuth flow
+### 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)
+
+The [PostAuthenticateTasks](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/auth/post_authenticate_tasks.rb)
+class is responsible for triggering the webhooks manager for webhooks registration, and enqueue jobs from [after_authenticate_job](#after_authenticate_job).
+
+If you simply need to enqueue more jobs to run after authenticate, use [after_authenticate_job](#after_authenticate_job) to define these jobs.
+
+If your post authentication tasks is more complex and is different than just installing webhooks and enqueuing jobs,
+you can customize the post authenticate tasks by creating a new class that has a `self.perform(session)` method,
+and configuring `custom_post_authenticate_tasks` in the initializer.
+
+```ruby
+# my_custom_post_authenticate_task.rb
+class MyCustomPostAuthenticateTask
+  def self.perform(session)
+    # This will be triggered after OAuth callback and token exchange completion
+  end
+end
+
+# config/initializers/shopify_app.rb
+ShopifyApp.configure do |config|
+  config.custom_post_authenticate_tasks = "MyCustomPostAuthenticateTask"
+end
+```
+
+#### after_authenticate_job
 
 See [`ShopifyApp::AfterAuthenticateJob`](/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb).
 
-If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing (note that we already provide support for automatically creating Webhooks and Scripttags). To configure the after authenticate job, update your initializer as follows:
+If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing. To configure the after authenticate job, update your initializer as follows:
 
 ```ruby
 ShopifyApp.configure do |config|