From 70194f15ab2ba9c9180efbb5156c77dd818481cf Mon Sep 17 00:00:00 2001 From: Zoey Lan Date: Fri, 26 Apr 2024 14:33:13 -0600 Subject: [PATCH] Add README introduction to new embedded app auth strategy --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 9488f4ab3..3705f1dab 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,52 @@ 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 + +> [!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 + +> [!NOTE] +> Newly created Rails apps from the template after May ZL-TODO 2024 has this feature enabled by default. + +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.unstable_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. + +###### 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) + ### 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).