diff --git a/packages/shopify-app-remix/CHANGELOG.md b/packages/shopify-app-remix/CHANGELOG.md index e1a656e257..33243d2eb7 100644 --- a/packages/shopify-app-remix/CHANGELOG.md +++ b/packages/shopify-app-remix/CHANGELOG.md @@ -4,9 +4,9 @@ ### Minor Changes -- 2473c85: Add new embedded authorization strategy relying on Shopify managed install and OAuth token +- 2473c85: Add new embedded authorization strategy relying on Shopify managed install and OAuth token exchange - :exclamation: For more information on how to enable this feature, see [Using the New Token Exchange OAuth Flow](./README.md#using-the-new-token-exchange-oauth-flow) + :exclamation: For more information on how to enable this feature, see ["New Embedded Authorization Strategy"](./README.md#new-embedded-authorization-strategy) ### Patch Changes diff --git a/packages/shopify-app-remix/README.md b/packages/shopify-app-remix/README.md index 422d703f53..bc400c2f57 100644 --- a/packages/shopify-app-remix/README.md +++ b/packages/shopify-app-remix/README.md @@ -174,25 +174,27 @@ Here are some guides to help you set up your app: You can also authenticate requests from surfaces other than the admin. To see all supported methods, see [the `shopify.authenticate` object documentation](https://shopify.dev/docs/api/shopify-app-remix/latest/authenticate). -### Using the New Token Exchange OAuth flow +### New embedded authorization strategy > [!TIP] -> If you are building an embedded app, we **strongly** recommend using [Shopify managed install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) -with [Token Exchange](#token-exchange) instead of the Authorization Code Grant Flow. +> 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/overview) instead of the legacy authorization code grant flow. -We've introduced a new installation and OAuth flow for **embedded apps** that eliminates the redirects used for installation and authorization. It -can replace the existing [Authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant). +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). -You can take advantage of [Shopify Managed Install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) -to handle automatic app installations and scope updates, while using -[Token Exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) to get an access token for the logged-in user. +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/overview) to retrieve an access token for +authenticated API access. -##### Enabling Token Exchange in your app +##### Enabling this new strategy in your app > [!NOTE] -> Newly created Remix apps from the template after February 1st 2024 will have token exchange enabled by default. +> Newly created Remix apps from the template after February 1st 2024 will have this feature enabled by default. -1. Turn on [Shopify Managed Install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) +1. Enable [Shopify managed install](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. Turn on the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file. +2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file. ```ts // my-app/app/shopify.server.ts @@ -205,7 +207,7 @@ const shopify = shopifyApp({ }) ``` -3. Enjoy painless no-redirect OAuth flow, and app installation process. +3. Enjoy no-redirect OAuth flow, and app installation process. ###### Learn more about: - [How Token Exchange Works](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) diff --git a/packages/shopify-app-remix/docs/generated/generated_docs_data.json b/packages/shopify-app-remix/docs/generated/generated_docs_data.json index 5e7796c012..56bd8d76e3 100644 --- a/packages/shopify-app-remix/docs/generated/generated_docs_data.json +++ b/packages/shopify-app-remix/docs/generated/generated_docs_data.json @@ -15355,12 +15355,12 @@ "syntaxKind": "PropertySignature", "name": "unstable_newEmbeddedAuthStrategy", "value": "boolean", - "description": "When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview). This assumes app are using declarative scopes with [Shopify managing installs](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).", + "description": "When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview). This assumes app are using declarative scopes with [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).", "isOptional": true, "defaultValue": "false" } ], - "value": "export interface FutureFlags {\n /**\n * When enabled, returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.\n *\n * @default false\n */\n v3_webhookAdminContext?: boolean;\n\n /**\n * When enabled authenticate.public() will not work. Use authenticate.public.checkout() instead.\n *\n * @default false\n */\n v3_authenticatePublic?: boolean;\n\n /**\n * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview).\n * This assumes app are using declarative scopes with [Shopify managing installs](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\n *\n * @default false\n */\n unstable_newEmbeddedAuthStrategy?: boolean;\n}" + "value": "export interface FutureFlags {\n /**\n * When enabled, returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.\n *\n * @default false\n */\n v3_webhookAdminContext?: boolean;\n\n /**\n * When enabled authenticate.public() will not work. Use authenticate.public.checkout() instead.\n *\n * @default false\n */\n v3_authenticatePublic?: boolean;\n\n /**\n * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview).\n * This assumes app are using declarative scopes with [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\n *\n * Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).\n *\n * @default false\n */\n unstable_newEmbeddedAuthStrategy?: boolean;\n}" } } } diff --git a/packages/shopify-app-remix/docs/generated/generated_static_pages.json b/packages/shopify-app-remix/docs/generated/generated_static_pages.json index 752a7afff7..1a779c2509 100644 --- a/packages/shopify-app-remix/docs/generated/generated_static_pages.json +++ b/packages/shopify-app-remix/docs/generated/generated_static_pages.json @@ -167,7 +167,7 @@ { "name": "unstable_newEmbeddedAuthStrategy", "value": "", - "description": "Embedded apps will fetch access tokens via token exchange. This assumes app are using declarative scopes with Shopify managing installs.\n\nSee [Token Exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) for more details.", + "description": "Embedded apps will fetch access tokens via token exchange. This assumes app are using declarative scopes with Shopify managing installs.\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).", "isOptional": true } ] @@ -422,7 +422,7 @@ "type": "Generic", "anchorLink": "auth-route", "title": "OAuth route", - "sectionContent": "> Note: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using [Token Exchange](#token-exchange) for OAuth and installation flow.\n\nTo install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`.\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.", + "sectionContent": "> Tip: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using the [new embedded authorization strategy](#embedded-auth-strategy) for OAuth and installation flow. If you're building an embedded app, we **strongly** recommend using the [new embedded authorization strategy](#embedded-auth-strategy)\n\nTo install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`.\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.", "codeblock": { "title": "Add OAuth route", "tabs": [ @@ -436,11 +436,11 @@ }, { "type": "Generic", - "anchorLink": "token-exchange", - "title": "Using Token exchange for OAuth", - "sectionContent": "> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\nIf you're building an embedded app, we **strongly** recommend using Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview)\n\n We have introduced a new installation and OAuth flow for **embedded apps** that eliminates the redirects used for installation and authorization. It can replace the legacy [Authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant) to eliminate app redirects and installation handling\n\nYou can take advantage of [Shopify Managed Install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) to handle automatic app installations and scope updates, while using [Token Exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) to get an access token for the logged-in user.\n\n > Note: Newly created Remix apps from the template after February 1st 2024 will have token exchange enabled by default.\n\n1. Turn on [Shopify Managed Install](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).\n2. Turn on the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file.\n3. Enjoy no-redirect OAuth flow, and app installation process.", + "anchorLink": "embedded-auth-strategy", + "title": "New embedded authorization strategy", + "sectionContent": "> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\n> If you're building an embedded app, we **strongly** recommend using this feature that utilizes Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview).\n\n We have introduced a new authorization and installation strategy for **embedded apps** that eliminates the redirects that were previously necessary. It replaces the legacy [authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant).\n\nIt takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) to handle automatic app installations and scope updates, while using [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) to get an access token for the logged-in user.\n\n > Note: Newly created Remix apps from the template after February 1st 2024 will have this feature enabled by default.\n\n1. 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).\n2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file.\n3. Enjoy no-redirect OAuth flow, and app installation process.", "codeblock": { - "title": "Enabling token exchange", + "title": "Enabling the new embedded auth strategy", "tabs": [ { "title": "/app/shopify.server.ts", diff --git a/packages/shopify-app-remix/docs/staticPages/examples/index/token-exchange-config.example.ts b/packages/shopify-app-remix/docs/staticPages/examples/index/embedded-app-auth-strategy-config.example.ts similarity index 100% rename from packages/shopify-app-remix/docs/staticPages/examples/index/token-exchange-config.example.ts rename to packages/shopify-app-remix/docs/staticPages/examples/index/embedded-app-auth-strategy-config.example.ts diff --git a/packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts b/packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts index 5f1de21598..d75ec76a89 100644 --- a/packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts +++ b/packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts @@ -75,7 +75,7 @@ const data: LandingTemplateSchema = { value: '', description: 'Embedded apps will fetch access tokens via token exchange. This assumes app are using declarative scopes with Shopify managing installs.' + - '\n\nSee [Token Exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) for more details.', + '\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).', isOptional: true, }, ], diff --git a/packages/shopify-app-remix/docs/staticPages/index.doc.ts b/packages/shopify-app-remix/docs/staticPages/index.doc.ts index 917c89932b..5b2b79a3da 100644 --- a/packages/shopify-app-remix/docs/staticPages/index.doc.ts +++ b/packages/shopify-app-remix/docs/staticPages/index.doc.ts @@ -138,7 +138,8 @@ const data: LandingTemplateSchema = { anchorLink: 'auth-route', title: 'OAuth route', sectionContent: - "> Note: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using [Token Exchange](#token-exchange) for OAuth and installation flow." + + "> Tip: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using the [new embedded authorization strategy](#embedded-auth-strategy) for OAuth and installation flow. If you're building an embedded app, we **strongly** recommend using the" + + " [new embedded authorization strategy](#embedded-auth-strategy)" + "\n\nTo install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`." + '\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.' + '\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.', @@ -155,28 +156,28 @@ const data: LandingTemplateSchema = { }, { type: 'Generic', - anchorLink: 'token-exchange', - title: 'Using Token exchange for OAuth', + anchorLink: 'embedded-auth-strategy', + title: 'New embedded authorization strategy', sectionContent: "> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)." + - "\nIf you're building an embedded app, we **strongly** recommend using Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview)" + - "\n\n We have introduced a new installation and OAuth flow for **embedded apps** that eliminates the redirects used for installation and authorization." + - " It can replace the legacy [Authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant) to eliminate app redirects and installation handling" + - "\n\nYou can take advantage of [Shopify Managed Install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" + + "\n> If you're building an embedded app, we **strongly** recommend using this feature that utilizes Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview)." + + "\n\n We have introduced a new authorization and installation strategy for **embedded apps** that eliminates the redirects that were previously necessary." + + " It replaces the legacy [authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant)." + + "\n\nIt takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" + " to handle automatic app installations and scope updates, while using" + - " [Token Exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) to get an access token for the logged-in user." + - "\n\n > Note: Newly created Remix apps from the template after February 1st 2024 will have token exchange enabled by default." + - "\n\n1. Turn on [Shopify Managed Install](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" + + " [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview) to get an access token for the logged-in user." + + "\n\n > Note: Newly created Remix apps from the template after February 1st 2024 will have this feature enabled by default." + + "\n\n1. 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)." + - "\n2. Turn on the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file." + + "\n2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file." + "\n3. Enjoy no-redirect OAuth flow, and app installation process.", codeblock: { - title: 'Enabling token exchange', + title: 'Enabling the new embedded auth strategy', tabs: [ { title: '/app/shopify.server.ts', language: 'ts', - code: './examples/index/token-exchange-config.example.ts', + code: './examples/index/embedded-app-auth-strategy-config.example.ts', } ], diff --git a/packages/shopify-app-remix/src/server/future/flags.ts b/packages/shopify-app-remix/src/server/future/flags.ts index a0b58430bf..ef2d431d9a 100644 --- a/packages/shopify-app-remix/src/server/future/flags.ts +++ b/packages/shopify-app-remix/src/server/future/flags.ts @@ -17,7 +17,9 @@ export interface FutureFlags { /** * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange/overview). - * This assumes app are using declarative scopes with [Shopify managing installs](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation). + * This assumes app are using declarative scopes with [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation). + * + * Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy). * * @default false */