Skip to main content

Setting up AWS

Set up your AWS account and manage your environments and credentials in a simple and secure way.

Overview​

If you go through the default onboarding for AWS you'll likely miss a few features that will make your team's lives a whole lot easier. If you're currently using IAM users or have api keys in credentials files, that's a sign you should read this guide.

tip

If you are using IAM users or have credential files, you should follow this guide.

The ideal setup is multiple AWS accounts grouped under a single AWS Organization while human users authenticate through SSO for both Console and CLI access.

Setup​

All this sounds complicated but it is a one time process and you'll never have to think about it again.

Let's get started.

Create a management account​

  1. The first step is to create a management account.

    • Ideally use a work email alias - for example aws@acme.com that forwards to your real email. This allows you to give other people access in the future.
    • The account name should just be your company name - for example acme
    • These credentials are overly powerful - you should rarely ever need them again. Feel free to throw away the password after completing this guide. You can always do a password reset if it's needed.
    • Enter your billing info and confirm your identity
    • Choose basic support - can upgrade later if needed

  2. Once you're done you should be able to login and access the AWS Console. Search "AWS Organization" in the search bar to go to the organizations section and click Create an organization. That should be pretty immediate and you'll see the management account you're currently in is already in the organization.

  3. This management account won't have anything deployed to it besides IAM Identity Center which is how you'll manage your users. Search "IAM Identity Center" and go to its dashboard. Click Enable to set it up.

    • Note the region you're in in the top right. IAM Identity Center will be created in one region and you cannot change it. However, it doesn't matter too much which one it is.
    • Click Enable
    • This will give your organization a unique URL to login at. This is autogenerated but you can click Customize to select a unique name. You will want to bookmark this for later.
    • Click Users on the left and then Add user to create your first user - yourself. Make your username your work email - eg dax@acme.com and fill out the required fields.
    • Skip adding user to groups and finish creating the user.

  4. The user is created but doesn't actually have access to any AWS accounts. To add them, go to the left panel and click AWS Accounts.

    • Select your management account (should be tagged management account) and click Assign users or groups.
    • Select the Users tab, make sure your user is selected and hit Next
    • We'll need to create a new permission set - this is a one time task. Click Create permission set
    • In the new tab select "Predefined permission set" and "AdministratorAccess". Click Next
    • Increase session duration to 12 hours (this is most convenient). Click Next and then Create.
    • Close the tab, return to the previous one and hit the refresh icon. Select AdministratorAccess and click Next and then Submit
    • Although this was complicated, all we did was grant the user to assume an "AdministratorAccess role" into the management account. You can add more users in the future by following these same steps but you can reuse the AdministratorAccess role you created.
tip

If you already have an SSO provider (eg Google) you can allow your team to "Login with Google" instead of managing separate passwords. We haven't documented this yet but join our Discord and ask about it.

  1. Now you're ready to login. Check your email and you should have an invitation to login.

    • Accept the invite and create a new password. Be sure to save it in your password manager - this one is important.
    • Sign in and you should see your organization with a list of accounts below.
    • You'll currently only have access to the management account we setup so click it and you should see the AdministratorAccess role.
    • Click Management Console to login to the AWS Console

You're now done setting up the root account!

Create dev and prod accounts​

As mentioned earlier, your management account isn't meant to actually host any resources. A good initial setup is to create separate dev and production accounts to create some isolation. The dev account will be shared between your team while the production account is just for production. You can get fancier with a staging account or an account per dev but we'll start simple.

  1. Navigation back to "AWS Organizations" by searching it in the console.

    • Click Add an AWS account
    • For the account name append -dev to whatever you called your management account. For example acme-dev
    • For the email address choose a new email alias - if you're using Google for email you can simply do aws+dev@acme.com and it'll still go to your aws@acme.com email.
    • Click Create AWS account
    • Repeat this step for -production as well.

  2. It'll take a few seconds to finish creating but once it's done head over to "IAM Identity Center" to grant your user access.

    • Select the "AWS Accounts" tab on the left
    • Select your newly created acme-dev and acme-production accounts and click Assign users or groups
    • In the "Users" tab select your user and click Next
    • Select the "AdministratorAccess" permission set and click Next and Submit

  3. Once that's complete go back to your SSO url (if you forgot to bookmark this you can click "Dashboard" to see the URL on the right). You should now see three different accounts and you'll be able to login to whichever one you want.

Setup the AWS CLI​

What's great about this setup is you no longer need to generate API keys for your local machine - you can just use SSO. A single configuration file will work for the AWS CLI, SST, and any random scripts you want to run and there will never be any long lived credentials stored on disk.

  1. Create a file at ~/.aws/config and add an [sso-session] block like this

    ~/.aws/config
    [sso-session acme]
    sso_start_url = https://acme.awsapps.com/start
    sso_region = us-east-1

Be sure to update the URL with your SSO url that you bookmarked and the region where you created IAM Identity Center.

  1. Then add an entry for each environment - dev and production.

    ~/.aws/config
    [profile acme-dev]
    sso_session = acme
    sso_account_id = <account-id>
    sso_role_name = AdministratorAccess
    region = us-east-1

    [profile acme-production]
    sso_session = acme
    sso_account_id = <account-id>
    sso_role_name = AdministratorAccess
    region = us-east-1

You can find the account ID from your SSO login url. If you expand the account you will see it listed with a # sign. The region specified in the config is the default region the CLI will use when one isn't specified.

  1. Now you can login by running aws sso login --sso-session=acme. This will open your browser and prompt you to allow access. The sessions will last 12 hours as configured in previous steps so you will have to run this once a day. It can be helpful to add this to a package.json script so people can just run pnpm sso to login.

  2. Test that everything is working with a simple cli command targeted at your dev account

    aws sts get-caller-identity --profile=acme-dev

Configure SST​

If you have an SST project there's some useful configuration you can add to make everything work smoothly.

  1. In your sst.config.ts file you can conditionally choose the right profile depending on the stage you are deploying to.

    sst.config.ts
    config(input) {
      return {
        name: "my-sst-app",
        region: "us-east-1",
        profile: input.stage === "production" ? "acme-production" : "acme-dev",
      };
    }

This will use the acme-production profile just for production and use acme-dev for everything else.

  1. Do a production deploy

    sst deploy --stage=production