Step 1: Configure AWS credentials

Prerequisites

• An AWS account with an admin role

tip

You can skip this step if you prefer to manage AWS credentials without using AWS Vault, but it is recommended to follow this guide for improved security.

Store AWS credentials in secure place

Keeping your AWS credentials in plain text in ~/.aws/config/ or ~/.aws/credentials is not very secure. We recommend using aws-vault – "A vault for securely storing and accessing AWS credentials in development environments".

AWS Vault is a command-line tool that securely manages AWS access credentials using an encrypted local file on your computer. It allows you to manage multiple AWS accounts and roles, switch between them without entering credentials repeatedly, and rotate access keys for improved security. It also integrates with other AWS command-line tools and supports MFA for added protection.

Visit official aws-vault documentation for installation instructions.

Create base profile

First you need to create a profile for your AWS credentials. Just using this is a great security improvement because you no longer store them in plain text.

aws-vault add my-profile

From now on you can just set environmental variable AWS_PROFILE=my-profile and all AWS commands should be able to pick up your credentials automatically.

info

You should find your Enter Access Key Id and Enter Secret Key in
the My security credentials section of your AWS web panel.

Create profile for your project

You will use this profile to execute any CLI commands that interact with AWS: AWS CLI, Serverless, REST API, etc.

Generally, it is considered a best practice to use temporary security credentials when working on an assumed IAM role, rather than relying on your permanent ones. To achieve this, you will need to create a new IAM role with the appropriate permissions. In this guide, we will create a full-access admin role for demonstration purposes.

Create IAM Role

Create the new IAM role with following permissions and give it a name, for example SaaSBoilerplateAdminRole:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": "*"
        }
    ]
}

You also need to edit the trust policy, available in "Trust relationships" tab in the AWS web panel.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID>:root"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

• <AWS_ACCOUNT_ID> is the ID of your AWS account that you want to use for deployment. It is a 12-digit number you can get from the account settings page.

You will need the arn of the IAM role you just created in the next step. It is visible on the role's details page in aws web panel.

Modify configuration file

Next, create a new entry in ~/.aws/config file:

• set the name of the profile,
• set source_profile to the name of the base profile you created few steps before,
• set role_arn to the arn of the IAM role you created in previous step,
• set region to the AWS region you'd like to use for deployment of ShipFast.

~/.aws/config

[profile my-profile]
region=eu-west-1

[profile saas]
source_profile = my-profile
role_arn = arn:aws:iam::<AWS_ACCOUNT_ID>:role/SaaSBoilerplateAdminRole
region=eu-west-1

Update .env file

Now you can use that profile name in .env file in root of your project

.env

PROJECT_NAME=saas
ENV_STAGE=local
AWS_VAULT_PROFILE=saas
...

AWS vault usage

From now on you can use aws-vault for secure connection with AWS platform. Always make sure you are in a proper aws-vault context when you run commands that use AWS CLI.

We created a CLI command that will automatically use aws-vault if it is detected in your system:

pnpm shipfast aws set-env [STAGE_NAME]

After this you'll have proper AWS credentials available in environmental variables and any command will be run against a specific environment stage (qa in the example above).

info

Check out the usage docs for more info about how you can utilize aws-vault.

[optional] Multi-factor authentication

You may be also be required to configure MFA for your AWS user and AWS Vault profile.

If during the deployment you encounter similar error:

…
3:25:45 PM | UPDATE_FAILED        | AWS::CodeBuild::Project     | PipelineConfigWebA...ildProject04B4719B
AccessDenied. User doesn't have permission to call iam:GetRole

consider configuring MFA, as documented in the official docs.

Copy the serial MFA device serial number

And paste it into the ~/.aws/config as mfa_serial property (example below) and save the file.

[profile saas]
source_profile = your-personal-user-name
role_arn = arn:aws:iam::123456789:role/SaaSBoilerplateAdminRole
mfa_serial=arn:aws:iam::123456789:mfa/[email protected]

note

Unfortunately, from now on, you will have to enter MFA every time you log into the AWS console or run aws-vault