Front-End Web & Mobile

Override Amplify-generated backend resources using CDK

AWS Amplify announces the ability for developers to override Amplify-generated IAM, Cognito, S3, and DynamoDB resource configurations to best meet app requirements. With the new override capability, developers can easily configure their backend with Amplify-provided defaults but still customize fine-grained resource settings.

AWS Amplify is the fastest and easiest way to build cloud-powered mobile and web apps on AWS. Amplify comprises a set of tools and services that enables frontend web and mobile developers to leverage the power of AWS services to build innovative and feature-rich applications. The AWS Amplify CLI is a command line toolchain that helps frontend developers create app backends in the cloud.

What we’ll learn:

  • How to override Amplify-generated project-level IAM roles
  • How to override Amplify-generated auth (Cognito) resources
  • How to override Amplify-generated storage (S3) resources

Pre-requisites:

  • Install the latest Amplify CLI; version 7 and above required.
    • Open terminal and run npm i -g @aws-amplify/cli
  • Amplify CLI is already configured
    • If you haven’t configured the Amplify CLI yet, follow this guide on our documentation page.

1. Set up your Amplify project

First, create a new directory and initialize your Amplify project. Run the following commands in your Terminal:

mkdir override-demo
cd override-demo
amplify init -y

An Amplify project is your starting point to develop your app backend. After an Amplify project is initialized, you can easily add backend resources such as auth via amplify add auth or storage resources such as amplify add storage.

2. Modify Amplify-generated IAM roles for authenticated and unauthenticated user access

An Amplify project contains two “IAM roles” that delegates access to backend resources for authenticated and unauthenticated users. Organizations often have specific requirements for these roles to meet DevOps guidelines. While Amplify CLI provides some customizations such as using an IAM permissions boundary built-in, there are some additional settings such as the role name or role paths that can now also be modified using an “override”.

To apply overrides on these project-level IAM roles, run:

amplify override project

This command generates a “overrides.ts” Typescript file which provides the Amplify-generated IAM roles as CDK constructs. Apply any changes that you require such as changing the role name and path by modifying the resources parameter.

For our example, let’s assume we need to change our IAM role name and add a path that has the pattern of “/my-organization/myteam/”.

Edit your the file to apply the resource customizations in the override function:

import { AmplifyRootStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyRootStackTemplate) {
   resources.authRole.roleName = "AmplifyProjectAuthRole"
   resources.authRole.path = "/myorganization/myteam/"
   resources.unauthRole.roleName = "AmplifyProjectUnauthRole"
   resources.unauthRole.path = "/myorganization/myteam/"
}

Once the overrides.ts file is correctly configured, you can deploy the changes:

amplify push -y

When the deployment completes, visit the IAM console to verify that the roles exist:

Screenshot of IAM console

Warning: Due to the deep dependencies on the authenticated and unauthenticated user roles, it is recommended to ONLY modify these resources at the beginning of your project, when no other resources are added yet.

3. Modify Amplify-generated auth (Cognito) resources

First, add the Amplify auth category, which enables developers to configure a user sign-up and sign-in experience with minimal cloud expertise.

amplify add auth

(For the purposes of this demo, you can just accept all defaults.)

Amplify provides a range of simple to advanced auth features, from email sign-up, multi-factor authentication, to custom authorization challenges. There are some infrastructure-level settings that aren’t exposed as a built-in Amplify CLI workflow such as configuring “the validity days for temporary passwords” when users are initially invited to join an app. To customize these and many more settings run:

amplify override auth

Similar to the project overrides, this command generates a “overrides.ts” Typescript file which provides the Amplify-generated Cognito resources as CDK constructs. Let’s try to change the temporary password validity days and make usernames case sensitive. Apply the changes you need via the resources parameter. (Hint: as you type “resource.” you’ll get code completion for the available options with links to documentation in your IDE.)

import { AmplifyAuthCognitoStackTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyAuthCognitoStackTemplate) {
  resources.userPool.policies = {
    passwordPolicy: {
      ...resources.userPool.policies["passwordPolicy"], // Retain current settings
      temporaryPasswordValidityDays: 2 // Override "temporary password validity days" setting
    }
  }
  
  resources.userPool.usernameConfiguration = {
    caseSensitive: true
  } 
}

(Note: Cognito restricts some settings to be changed after its initial deployment. Make sure to validate which settings are allowed to be modified after initial deployment to prevent deployment errors.)

Once the overrides.ts file is correctly configured, you can deploy the changes:

amplify push -y

When the deployment completes, visit the Cognito user pool console to verify that the policy is applied and the username is case sensitive exist:

Screenshot of Cognito user pool consoleScreenshot of Cognito user pool console

While this blog post is solely focused on changing the backend configuration of these resource, be sure to check out the Amplify Library documentation on how to connect your web or mobile app to the Amplify-generated resources.

4. Modify Amplify-generated S3 bucket configuration

First, add the Amplify storage category, which enables customers to set up file storage backed by Amazon S3.

amplify add storage
❯ Content (Images, audio, video, etc.)

(For the purposes of this demo, you can just accept all defaults.)

Amplify CLI provides a configuration experience that only requires you to provide 1/ a bucket name and 2/ access permissions for authenticated and unauthenticated users. To fine-tune your S3 bucket settings, such as enabling versioning, run:

amplify override storage

Same story as with auth and project overrides, this command generates a “overrides.ts” Typescript file which provides the Amplify-generated S3 bucket and related policies as CDK constructs.

import { AmplifyS3ResourceTemplate } from '@aws-amplify/cli-extensibility-helper';

export function override(resources: AmplifyS3ResourceTemplate) {
   resources.s3Bucket.versioningConfiguration = {
     status: "Enabled"
   } 
}

Once the overrides.ts file is correctly configured, you can deploy the changes:

amplify push -y

When the deployment completes, visit the Amazon S3 console to verify that bucket versioning is enabled:

Screenshot of S3 console

🥳 Success

In this blog post, you’ve learned how to customize Amplify-generated project-level IAM roles, auth (Cognito) resources, and storage (S3) resources. Amplify CLI also supports resource overrides for DynamoDB tables added via amplify add storage. Which category do you want us to support next? Let us know on our GitHub repository.

Review our documentation for more details:

Have fun extending your Amplify project!