From 43396533d5f9a4aacfd38468dace87765557c73c Mon Sep 17 00:00:00 2001 From: 9pace Date: Wed, 6 May 2026 16:11:51 -0400 Subject: [PATCH 1/7] docs: oauth migration guide updates --- .../migrate-existing-app/index.mdx | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index c6416a439f9..7736d01451b 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -500,6 +500,23 @@ See [Secrets](https://docs.amplify.aws/react/build-a-backend/functions/environme +#### External Identity Providers + +If your Gen 1 app uses social sign-in (Facebook, Google, Apple, Amazon, or OIDC/SAML), the generated `callbackUrls` and `logoutUrls` in `./amplify/auth/resource.ts` are inherited from Gen 1 and reference the Gen 1 Amplify Hosting URLs only. The Gen 2 hosting URL must be added before the Hosted UI will accept sign-ins from the Gen 2 frontend. + +The generator emits a comment above each URL list as a reminder. Add the Gen 2 URL to both locations: + +```diff + callbackUrls: [ + 'https://main..amplifyapp.com/', ++ 'https://gen2-main..amplifyapp.com/', + ], +``` + +The top-level `externalProviders.callbackUrls`/`logoutUrls` configure the web client used by the frontend. The `oAuth.callbackUrls`/`logoutUrls` inside `applyEscapeHatches` configure a separate native app client — update both if present. + +The corresponding redirect URIs in the external provider's developer console must also be updated, but only after the Gen 2 environment is deployed (see [Configure external identity providers](#configure-external-identity-providers) below). + ### Step 5: Deploy Push the generated Gen 2 code to your repository: @@ -546,6 +563,14 @@ By default, sandbox creates its own DynamoDB tables and does not share Gen 1 mod +#### Configure external identity providers + +If your app uses social sign-in, the Gen 2 deployment creates a new Cognito User Pool Domain distinct from the Gen 1 one. The external provider's developer console must be updated to accept redirects from the new domain before Hosted UI sign-in will work on the Gen 2 frontend. + +Open the [Cognito console](https://console.aws.amazon.com/cognito/), select the user pool owned by your Gen 2 branch, and note the domain under _App integration → Domain_. + +Then, add the domain to each external provider's console following the standard [External identity providers](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) guide. You do not need to replace the existing Gen 1 entries — add the Gen 2 domain alongside them so both environments work during the transition. + ### Step 6: Functional Tests (CRITICAL) @@ -628,6 +653,8 @@ amplify gen2-migration lock --rollback amplify push ``` +If you had already completed [Step 8: Post-Refactor](#step-8-post-refactor-critical) before rolling back, re-comment `postRefactor();` in `./amplify/backend.ts` on the `gen2-main` branch and push. The function targets resources that the Gen 2 stack no longer owns after rollback and will fail at synth otherwise. + ### Step 8: Post-Refactor (CRITICAL) @@ -651,7 +678,7 @@ Edit `./amplify/backend.ts`: -This function must remain uncommented permanently — even after migration is complete. Commenting it out or removing it will cause deployment failures. +This function must remain uncommented after the refactor is complete. Commenting it out or removing it will cause deployment failures. The only exception is if you subsequently run `refactor --rollback` — see [Step 7](#step-7-refactor). From 3ef7a358876d15a00fd99513f143c218739b1198 Mon Sep 17 00:00:00 2001 From: 9pace Date: Wed, 6 May 2026 16:18:39 -0400 Subject: [PATCH 2/7] docs: remove untested providers --- .../start/migrate-to-gen2/migrate-existing-app/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index 7736d01451b..a75938ecbd5 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -502,7 +502,7 @@ See [Secrets](https://docs.amplify.aws/react/build-a-backend/functions/environme #### External Identity Providers -If your Gen 1 app uses social sign-in (Facebook, Google, Apple, Amazon, or OIDC/SAML), the generated `callbackUrls` and `logoutUrls` in `./amplify/auth/resource.ts` are inherited from Gen 1 and reference the Gen 1 Amplify Hosting URLs only. The Gen 2 hosting URL must be added before the Hosted UI will accept sign-ins from the Gen 2 frontend. +If your Gen 1 app uses social sign-in (Facebook, Google), the generated `callbackUrls` and `logoutUrls` in `./amplify/auth/resource.ts` are inherited from Gen 1 and reference the Gen 1 Amplify Hosting URLs only. The Gen 2 hosting URL must be added before the Hosted UI will accept sign-ins from the Gen 2 frontend. The generator emits a comment above each URL list as a reminder. Add the Gen 2 URL to both locations: From d386690968522df799d5d99df488b7822d936fae Mon Sep 17 00:00:00 2001 From: 9pace Date: Wed, 6 May 2026 16:23:22 -0400 Subject: [PATCH 3/7] docs: tighten language --- .../start/migrate-to-gen2/migrate-existing-app/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index a75938ecbd5..f042f259db5 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -515,7 +515,7 @@ The generator emits a comment above each URL list as a reminder. Add the Gen 2 U The top-level `externalProviders.callbackUrls`/`logoutUrls` configure the web client used by the frontend. The `oAuth.callbackUrls`/`logoutUrls` inside `applyEscapeHatches` configure a separate native app client — update both if present. -The corresponding redirect URIs in the external provider's developer console must also be updated, but only after the Gen 2 environment is deployed (see [Configure external identity providers](#configure-external-identity-providers) below). +The corresponding redirect URIs in the external provider's developer console must also be updated, after the Gen 2 environment is deployed (see [Configure external identity providers](#configure-external-identity-providers) below). ### Step 5: Deploy @@ -646,6 +646,8 @@ If the refactor fails or produces undesired results, roll it back: amplify gen2-migration refactor --to --rollback ``` +If you had already completed [Step 8: Post-Refactor](#step-8-post-refactor-critical) before rolling back, re-comment `postRefactor();` in `./amplify/backend.ts` on the `gen2-main` branch and push. The function targets resources that the Gen 2 stack no longer owns after rollback and will fail at synth otherwise. + After rolling back, you will need to unlock the Gen 1 environment and redeploy it to restore normal operation: ```bash @@ -653,8 +655,6 @@ amplify gen2-migration lock --rollback amplify push ``` -If you had already completed [Step 8: Post-Refactor](#step-8-post-refactor-critical) before rolling back, re-comment `postRefactor();` in `./amplify/backend.ts` on the `gen2-main` branch and push. The function targets resources that the Gen 2 stack no longer owns after rollback and will fail at synth otherwise. - ### Step 8: Post-Refactor (CRITICAL) From 80a29ad2c4e0e312d83d755888684ff9bc8c3e3f Mon Sep 17 00:00:00 2001 From: Eli Polonsky Date: Wed, 13 May 2026 11:54:44 -0400 Subject: [PATCH 4/7] docs(migration): add custom resource support and --additional-stateful-resource-types option - Update feature matrix: Custom (CDK) now shows migration tool support - Document --additional-stateful-resource-types option in lock, generate, and refactor steps of the migration guide --- .../migrate-to-gen2/feature-matrix/index.mdx | 14 +-- .../migrate-existing-app/index.mdx | 88 ++++++++++++++++++- 2 files changed, 94 insertions(+), 8 deletions(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx index 38e83f8df08..0be63118063 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx @@ -60,10 +60,10 @@ If a feature you need is not yet supported, [create a feature request](https://g | Configure username | Yes | [Yes with CDK](/[platform]/build-a-backend/auth/modify-resources-with-cdk/) | 🟢 | | Configure email | Yes | Yes | 🟢 | | Configure phone number | Yes | Yes | 🟢 | -| Facebook | Yes | Yes | 🟠 | -| Google | Yes | Yes | 🟠 | -| Amazon | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🔴 | -| Sign-in with Apple | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🔴 | +| Facebook | Yes | [Yes]([platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | +| Google | Yes | [Yes]([platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | +| Amazon | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | +| Sign-in with Apple | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | | Add user pool groups | Yes | Yes | 🟢 | | User pool group preference | Yes | Yes | 🟢 | | Sign-up attributes | Yes | Yes | 🟢 | @@ -278,7 +278,7 @@ If you host your frontend separately (S3 + CloudFront, on-prem, etc.), run `npx | Geo (GeofenceCollection) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/geo/) | 🟠 | | Predictions | Yes | No | 🔴 | | Interactions | Yes | No | 🔴 | -| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🔴 | +| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🟢 | | Custom (CFN) | Yes | [Yes with CfnInclude](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.cloudformation_include.CfnInclude.html) | 🔴 | @@ -292,7 +292,7 @@ If you host your frontend separately (S3 + CloudFront, on-prem, etc.), run `npx | Geo | No | No | - | | Predictions | No | No | - | | Interactions | No | No | - | -| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🔴 | +| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🟢 | | Custom (CFN) | Yes | [Yes with CfnInclude](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.cloudformation_include.CfnInclude.html) | 🔴 | @@ -309,7 +309,7 @@ If you host your frontend separately (S3 + CloudFront, on-prem, etc.), run `npx | Geo (GeofenceCollection) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/geo/) | 🟠 | | Predictions | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/predictions/) | 🔴 | | Interactions | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/interactions/) | 🔴 | -| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🔴 | +| Custom (CDK) | Yes | [Yes with custom CDK](/[platform]/build-a-backend/add-aws-services/custom-resources/) | 🟢 | | Custom (CFN) | Yes | [Yes with CfnInclude](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.cloudformation_include.CfnInclude.html) | 🔴 | diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index c6416a439f9..7e0eacf5691 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -188,6 +188,13 @@ The migration tool requires the following API actions in addition to the standar "s3:GetEncryptionConfiguration" ], "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "cloudformation:GetResource" + ], + "Resource": "*" } ] } @@ -347,6 +354,37 @@ During the migration period your Gen 1 environment should not undergo any change amplify gen2-migration lock ``` +The lock step also sets a `Retain` deletion policy on all stateful resources in your Gen 1 stacks to protect them during migration. + + + +The migration tool maintains a default list of CloudFormation resource types it considers stateful (e.g. `AWS::Cognito::UserPool`, `AWS::S3::Bucket`, `AWS::DynamoDB::Table`). During the lock step, only resources matching these types receive the `Retain` deletion policy. + +If your application includes custom resources that contain stateful CloudFormation types not in the default list, you can provide them using the `--additional-stateful-resource-types` option. Create a JSON file with an array of CloudFormation resource type strings: + +```json +[ + "AWS::Elasticsearch::Domain", + "AWS::RDS::DBInstance" +] +``` + +Then pass the file path to the lock command: + +```bash +amplify gen2-migration lock --additional-stateful-resource-types ./my-stateful-types.json +``` + +The types you provide are merged with the built-in defaults. This ensures the tool correctly identifies and protects your custom stateful resources. + + + +You will need to pass the same file to the `generate` and `refactor` commands later. + + + + + Once validated, the following restrictive IAM policy is attached to the root stack: ```json @@ -387,6 +425,29 @@ amplify gen2-migration generate This command introspects your deployed Gen 1 CloudFormation stacks and generates the equivalent Gen 2 TypeScript backend definition files, overriding your local `./amplify` directory. The generated code is a starting point — some features require manual edits before deploying (see below). + + +The migration tool maintains a default list of CloudFormation resource types it considers stateful (e.g. `AWS::Cognito::UserPool`, `AWS::S3::Bucket`, `AWS::DynamoDB::Table`). During code generation, the tool uses this list to produce a `Retain` deletion policy in the Gen 2 CDK code for these resources, ensuring they don't override the deletion policy of the Gen 1 resources after refactoring. + +If your application includes custom resources that contain stateful CloudFormation types not in the default list, you can provide them using the `--additional-stateful-resource-types` option. Create a JSON file with an array of CloudFormation resource type strings: + +```json +[ + "AWS::Elasticsearch::Domain", + "AWS::RDS::DBInstance" +] +``` + +Then pass the file path to the generate command: + +```bash +amplify gen2-migration generate --additional-stateful-resource-types ./my-stateful-types.json +``` + +The types you provide are merged with the built-in defaults. This ensures the generated Gen 2 code includes retention policies for your custom stateful resources. + + + Once successful, clean up and reinstall dependencies to avoid stale resolution artifacts from the Gen 1 dependency tree: ```bash @@ -437,6 +498,8 @@ If you use the standard `Amplify.configure(...)` call and access resources throu + apiName: '', ``` +In addition, follow these [instructions](https://docs.amplify.aws/react/build-a-backend/add-aws-services/rest-api/set-up-rest-api/#initialize-amplify-api) to reconfigure your `Amplify` instance based on the outputs structure of Gen2. + **Kinesis** — If your frontend sends analytics events to a Kinesis stream, update the stream name to point to the new Gen 2 stream: ```diff @@ -609,6 +672,29 @@ amplify pull --appId --envName main amplify gen2-migration refactor --to ``` + + +The migration tool maintains a default list of CloudFormation resource types it considers stateful (e.g. `AWS::Cognito::UserPool`, `AWS::S3::Bucket`, `AWS::DynamoDB::Table`). During refactoring, only resources matching these types are moved from your Gen 1 stacks into Gen 2. + +If your application includes custom resources that contain stateful CloudFormation types not in the default list, you can provide them using the `--additional-stateful-resource-types` option — the same file you used in the [lock step](#step-2-lock). Create a JSON file with an array of CloudFormation resource type strings: + +```json +[ + "AWS::Elasticsearch::Domain", + "AWS::RDS::DBInstance" +] +``` + +Then pass the file path to the refactor command: + +```bash +amplify gen2-migration refactor --to --additional-stateful-resource-types ./my-stateful-types.json +``` + +The types you provide are merged with the built-in defaults. This ensures the tool correctly identifies and transfers your custom stateful resources during the refactoring step. + + + After the refactor step, a `.amplify/gen2-migration/refactor.operations/` directory is created containing snapshots of every CloudFormation operation performed — templates, parameters, and resource mappings. These files can help with auditing or troubleshooting and are safe to delete once migration is confirmed successful. @@ -625,7 +711,7 @@ After rolling back, you will need to unlock the Gen 1 environment and redeploy i ```bash amplify gen2-migration lock --rollback -amplify push +amplify push --force ``` ### Step 8: Post-Refactor (CRITICAL) From f40eb0b0f4c9bfe678f93142b4b49a4c414a31a9 Mon Sep 17 00:00:00 2001 From: Eli Polonsky Date: Wed, 13 May 2026 12:03:50 -0400 Subject: [PATCH 5/7] docs(migration): add retain command and update decommissioning section Replace manual retain instructions with amplify gen2-migration retain command. Clarify that retain only applies to nested stack resources. --- .../migrate-to-gen2/migrate-existing-app/index.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index 7e0eacf5691..975be4efe30 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -775,15 +775,15 @@ The Gen 1 CloudFormation stacks may still contain resources (such as auth trigge To decommission the Gen 1 stacks: 1. Verify that no users or applications are still accessing the Gen 1 stateless resources by inspecting CloudWatch traffic metrics or your organizational tracking systems. -2. Apply the `Retain` [deletion policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html) to all resources in the Gen 1 CloudFormation stacks. This prevents CloudFormation from deleting any physical resources when the stack is removed. You can do this by updating each stack (including nested ones) to set `DeletionPolicy: Retain` on every resource and updating the stacks via the CLI or the CloudFormation console. -3. Manually delete individual stateless resources that are no longer needed (e.g. AppSync APIs, Lambda functions, IAM roles) — verifying each one is safe to remove. -4. Delete the Gen 1 root CloudFormation stack. Since all resources have the `Retain` policy, the stack deletion will only remove the stack metadata without affecting any underlying resources. +2. Apply the `Retain` deletion policy to resources in the Gen 1 nested CloudFormation stacks. This prevents CloudFormation from deleting the retained resources when the root stack is removed. Note that the `retain` command only applies to resources in the nested stacks — resources in the root stack itself are not retained. - +```bash +amplify gen2-migration retain +``` -We are working on a CLI command to automate the process of retaining all resources in your Gen 1 environment. This section will be updated when it is available. +3. Delete the Gen 1 root CloudFormation stack. Resources in the nested stacks will be retained (orphaned) thanks to the deletion policy applied in the previous step. Resources in the root stack itself will be deleted normally. +4. Manually delete individual orphaned resources that are no longer needed (e.g. AppSync APIs, Lambda functions, IAM roles) — verifying each one is safe to remove. - ## Troubleshooting From 1d896ccf2a30b655875c206b6bf9fdddc5c7e872 Mon Sep 17 00:00:00 2001 From: Eli Polonsky Date: Wed, 13 May 2026 14:43:55 -0400 Subject: [PATCH 6/7] docs(migration): restructure post-generate auth section heading --- .../start/migrate-to-gen2/migrate-existing-app/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx index 81064350225..d0e6f65df26 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/migrate-existing-app/index.mdx @@ -563,7 +563,9 @@ See [Secrets](https://docs.amplify.aws/react/build-a-backend/functions/environme -#### External Identity Providers +#### Auth + +##### External Identity Providers If your Gen 1 app uses social sign-in (Facebook, Google), the generated `callbackUrls` and `logoutUrls` in `./amplify/auth/resource.ts` are inherited from Gen 1 and reference the Gen 1 Amplify Hosting URLs only. The Gen 2 hosting URL must be added before the Hosted UI will accept sign-ins from the Gen 2 frontend. From bdd7230592dae6238cc1fdd3deee148b988428c5 Mon Sep 17 00:00:00 2001 From: Eli Polonsky Date: Wed, 13 May 2026 17:25:58 -0400 Subject: [PATCH 7/7] docs(migration): fix broken links --- .../[platform]/start/migrate-to-gen2/feature-matrix/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx b/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx index 0be63118063..98c46979cc3 100644 --- a/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx +++ b/src/pages/[platform]/start/migrate-to-gen2/feature-matrix/index.mdx @@ -60,8 +60,8 @@ If a feature you need is not yet supported, [create a feature request](https://g | Configure username | Yes | [Yes with CDK](/[platform]/build-a-backend/auth/modify-resources-with-cdk/) | 🟢 | | Configure email | Yes | Yes | 🟢 | | Configure phone number | Yes | Yes | 🟢 | -| Facebook | Yes | [Yes]([platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | -| Google | Yes | [Yes]([platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | +| Facebook | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | +| Google | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | | Amazon | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | | Sign-in with Apple | Yes | [Yes](/[platform]/build-a-backend/auth/concepts/external-identity-providers/) | 🟢 | | Add user pool groups | Yes | Yes | 🟢 |