Skip to content
SST
Blog Docs Console Examples
22K

IAM Credentials

Configure the IAM credentials that's used to deploy your app.

SST deploys your AWS resources using your AWS credentials. In this guide we’ll look at how to set these credentials, the basic set of permissions it needs, and how to customize it.

Credentials

There are a couple of different ways to set the credentials that your app will use. The simplest is using a credentials file.

However, if you’re still figuring out how to configure your AWS account, we recommend following our guide on it.

From a file

By default, your AWS credentials are in a file:

  • ~/.aws/credentials on Linux, Unix, macOS
  • C:\Users\USER_NAME\.aws\credentials on Windows

If the credentials file does not exist on your machine.

  1. Follow this to create an IAM user
  2. And then use this to configure the credentials

Below we’ll look at how to customize the permissions that are granted to this user.

Your credentials file might look like:

~/.aws/credentials
[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>

Where default is the name of the credentials profile.

And if you have multiple credentials, it might look like:

~/.aws/credentials
[default]
aws_access_key_id = <DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <DEFAULT_SECRET_ACCESS_KEY>


[staging]
aws_access_key_id = <STAGING_ACCESS_KEY_ID>
aws_secret_access_key = <STAGING_SECRET_ACCESS_KEY>


[production]
aws_access_key_id = <PRODUCTION_ACCESS_KEY_ID>
aws_secret_access_key = <PRODUCTION_SECRET_ACCESS_KEY>

By default, SST uses the credentials for the default profile. To use one of the other profiles, set the profile in your sst.config.ts.

sst.config.ts
{
  providers: {
    aws: {
      profile: "staging"
    }
  }
}

You can customize this for the stage your app is being deployed to.

sst.config.ts
app(input) {
  return {
    // ...
    providers: {
      aws: {
        profile: input?.stage === "staging" ? "staging" : "default"
      }
    }
  };
},

If you’ve configured AWS credentials previously through the AWS_PROFILE environment variable or through a .env file, it will override the profile set in your sst.config.ts. So make sure to remove any references to AWS_PROFILE.

From environment variables

SST can also detect AWS credentials in your environment and use them to deploy.

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

If you are using temporary credentials, you can also set the AWS_SESSION_TOKEN.

This is useful when you are deploying through a CI environment and there are no credential files around.

Precedence

If you have AWS credentials set in multiple places, SST will first look at:

  1. Environment variables

    This includes AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN, and AWS_PROFILE. This also includes environment variables set in a .env file.

  2. SST config

    Then it’ll check for the credentials or profile in your sst.config.ts.

  3. AWS config

    It’ll then check for the [default] profile in your ~/.aws/config or C:\Users\USER_NAME\.aws\config.

  4. Credential files

    Finally, it’ll look for any static credentials in your ~/.aws/credentials or C:\Users\USER_NAME\.aws\credentials.

IAM permissions

The credentials above are for an IAM user and it comes with an IAM policy. This defines what resources the given user has access to. By default, we are using AdministratorAccess. This gives your user complete access.

However, if you are using SST at your company, you want to secure these permissions. Here we’ll look at exactly what SST needs and how you can go about customizing it.

Let’s start with an IAM policy you can copy and paste.

Copy IAM Policy
iam-policy.json
{
    "Version": "2012-10-17",
    "Statement": [
      {
          "Sid": "ManageBootstrapStateBucket",
          "Effect": "Allow",
          "Action": [
              "s3:CreateBucket",
              "s3:PutBucketVersioning",
              "s3:PutBucketNotification",
              "s3:PutBucketPolicy",
              "s3:DeleteObject",
              "s3:GetObject",
              "s3:ListBucket",
              "s3:PutObject"
          ],
          "Resource": [
              "arn:aws:s3:::sst-state-*"
          ]
      },
      {
          "Sid": "ManageBootstrapAssetBucket",
          "Effect": "Allow",
          "Action": [
              "s3:CreateBucket",
              "s3:PutBucketVersioning",
              "s3:PutBucketNotification",
              "s3:PutBucketPolicy",
              "s3:DeleteObject",
              "s3:GetObject",
              "s3:ListBucket",
              "s3:PutObject"
          ],
          "Resource": [
              "arn:aws:s3:::sst-asset-*"
          ]
      },
      {
          "Sid": "ManageBootstrapECRRepo",
          "Effect": "Allow",
          "Action": [
              "ecr:CreateRepository",
              "ecr:DescribeRepositories"
          ],
          "Resource": [
              "arn:aws:ecr:REGION:ACCOUNT:repository/sst-asset"
          ]
      },
      {
          "Sid": "ManageBootstrapSSMParameter",
          "Effect": "Allow",
          "Action": [
              "ssm:GetParameters",
              "ssm:PutParameter"
          ],
          "Resource": [
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/passphrase/*",
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/bootstrap"
          ]
      },
      {
          "Sid": "Deployments",
          "Effect": "Allow",
          "Action": [
              "*"
          ],
          "Resource": [
              "*"
          ]
      },
      {
          "Sid": "ManageSecrets",
          "Effect": "Allow",
          "Action": [
              "ssm:DeleteParameter",
              "ssm:GetParameter",
              "ssm:GetParameters",
              "ssm:GetParametersByPath",
              "ssm:PutParameter"
          ],
          "Resource": [
              "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/*"
          ]
      },
      {
          "Sid": "LiveLambdaSocketConnection",
          "Effect": "Allow",
          "Action": [
              "iot:DescribeEndpoint",
              "iot:Connect",
              "iot:Subscribe",
              "iot:Publish",
              "iot:Receive"
          ],
          "Resource": [
              "*"
          ]
      }
    ]
}

This list roughly breaks down into the following:

  1. Permissions needed to bootstrap SST in your AWS account
  2. Permissions needed to deploy your app
  3. Permissions needed by the CLI

Let’s look at them in detail.

Bootstrap

SST needs to bootstrap each AWS account, in each region, once. This happens automatically when you run sst deploy or sst dev.

There are a couple of different things being bootstrapped and these are the permissions they need:

  • Permissions to create the bootstrap bucket for storing state.

    {
      "Sid": "ManageBootstrapStateBucket",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:PutBucketVersioning",
        "s3:PutBucketNotification",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::sst-state-*"
      ]
    }

  • Permissions to create the bootstrap bucket for storing the assets in your app. These include the Lambda function bundles and static assets in your frontends.

    {
      "Sid": "ManageBootstrapAssetBucket",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:PutBucketVersioning",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::sst-asset-*"
      ]
    }

  • Permissions to create the bootstrap ECR repository for hosting the Docker images in your app.

    {
        "Sid": "ManageBootstrapECRRepo",
        "Effect": "Allow",
        "Action": [
          "ecr:CreateRepository",
          "ecr:DescribeRepositories"
        ],
        "Resource": [
          "arn:aws:ecr:REGION:ACCOUNT:repository/sst-asset"
        ]
    }

  • Permissions to create the bootstrap SSM parameter. This parameter stores information about the deployed bootstrap resources.

    {
      "Sid": "ManageBootstrapSSMParameter",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters",
        "ssm:PutParameter"
      ],
      "Resource": [
        "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/passphrase/*",
        "arn:aws:ssm:REGION:ACCOUNT:parameter/sst/bootstrap"
      ]
    }

Deploy

The permissions that SST needs to deploy the resources in your app, depends on what you have in your app.

The following block is placed as a template in the IAM policy above for you to customize.

{
  "Sid": "Deployments",
  "Effect": "Allow",
  "Action": [
    "*"
  ],
  "Resource": [
    "*"
  ]
}

Below we’ll look at how you can try customizing this.

CLI

The SST CLI also makes some AWS SDK calls to your account. Here are the IAM permissions it needs.

  • Permissions to manage your secrets.

    {
      "Sid": "ManageSecrets",
      "Effect": "Allow",
      "Action": [
        "ssm:DeleteParameter",
        "ssm:GetParameter",
        "ssm:GetParameters",
        "ssm:GetParametersByPath",
        "ssm:PutParameter"
      ],
      "Resource": [
        "arn:aws:ssm:us-east-1:112233445566:parameter/sst/*"
      ]
    }

  • And permissions to connect to the IoT endpoint in sst dev to run your functions Live.

    {
      "Sid": "LiveLambdaSocketConnection",
      "Effect": "Allow",
      "Action": [
        "iot:DescribeEndpoint",
        "iot:Connect",
        "iot:Subscribe",
        "iot:Publish",
        "iot:Receive"
      ],
      "Resource": [
        "*"
      ]
    }

Minimize permissions

Editing the above policy based on the resources you are adding to your app can be tedious. Here’s an approach to consider.

  • Sandbox accounts

    Start by creating separate AWS accounts for your teammates for their dev usage. In these sandbox accounts, you can grant AdministratorAccess. This avoids having to modify their permissions every time they make some changes.

  • IAM Access Analyzer

    For your staging accounts, you can start by granting a broad permissions policy. Then after deploying your app and allowing it to run for a period of time. You can use your CloudTrail events to identify the actions and services used by that IAM user. The IAM Access Analyzer can then generate an IAM policy based on this activity, which you can use to replace the original policy.

    You can now use this for your production accounts. Learn more about how to use the IAM Access Analyzer.

In general, you want to make sure you audit the IAM permissions you are granting on a regular basis.