DEV Community

Cover image for Configuring AWS Named Profiles
Lucas de Camargo
Lucas de Camargo

Posted on

Configuring AWS Named Profiles

#devops #terraform #cloud #aws

Following up with our series of engineering an IaC Startup on AWS, there's this one addendum I must talk about.

When working with multiple AWS accounts you need a way to tell the AWS CLI and Terraform which account to use for each operation. This is where named profiles come in.

A named profile is a collection of credentials and configuration settings that represents a specific identity in a specific AWS account. Instead of constantly switching credentials or passing them as command-line arguments, you define profiles once in your local AWS configuration files and reference them by name.

For example, you might have:

  • management-admin - Administrator access to your management account
  • backend-dev-admin - Administrator access to your development account
  • backend-prod-developer - Limited developer access to production

Named profiles are essential when working with Terraform and Terragrunt. Each stack may need to deploy resources to a different AWS account or assume different roles. By using named profiles in your Terraform provider configuration, you explicitly declare which identity should be used:

provider "aws" {
  region  = "us-east-1"
  profile = "backend-dev-admin"
}
Enter fullscreen mode Exit fullscreen mode

When Terraform runs, it looks for this profile in your local AWS configuration files and authenticates accordingly.

AWS profiles are configured in two files in your home directory:

~/.aws/credentials - Stores authentication credentials (access keys or SSO configuration)

~/.aws/config - Stores regional and output preferences

There are two primary ways to authenticate a profile.

Single Sign-On (SSO) - Recommended

This is the secure, modern approach that aligns with AWS best practices and the governance foundation we established. Instead of long-lived access keys, SSO provides temporary credentials that automatically expire:

# ~/.aws/credentials
[profile management-admin]
sso_start_url = https://mycorp.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
Enter fullscreen mode Exit fullscreen mode

It is recommended to explicitly define the configuration values for each profile:

# ~/.aws/config
[profile management-admin]
region = us-east-1
output = json
Enter fullscreen mode Exit fullscreen mode

To use an SSO profile, you need to login with the AWS CLI before running Terraform or any CLI command, which opens a browser for authentication and caches temporary credentials.

aws sso login --profile management-admin

# Test it with
aws sts get-caller-identity --profile management-admin
Enter fullscreen mode Exit fullscreen mode

Access Keys

Long-lived access keys can be stored directly in ~/.aws/credentials, but this approach is discouraged by AWS security best practices because:

  • Keys don't expire automatically
  • If accidentally committed to Git or exposed, they remain valid until manually rotated
  • They don't provide the same audit trail as SSO 
# ~/.aws/credentials (avoid this approach if possible)
[management-admin]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Enter fullscreen mode Exit fullscreen mode

Important: The default profile (with no profile prefix) is the profile used when no specific profile is specified. For safety, leave it unconfigured.

Testing Profiles

Once you've configured your profiles, it's essential to verify they're working correctly before attempting to deploy infrastructure.

For SSO profiles, start by logging in:

# Login to the SSO profile
aws sso login --profile management-admin
Enter fullscreen mode Exit fullscreen mode

This opens your browser for authentication. After successfully logging in, the credentials are cached locally (typically for 8-12 hours, depending on your SSO configuration).

For access key profiles, the test is simpler since no login is required.

Test your profiles by retrieving your caller identity:

aws sts get-caller-identity --profile management-admin
Enter fullscreen mode Exit fullscreen mode

You should see output like:

{
    "UserId": "AROA...:user@example.com",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AdministratorAccess/user@example.com"
}
Enter fullscreen mode Exit fullscreen mode

You can also list resources to verify permissions:

# List S3 buckets
aws s3 ls --profile management-admin

# List EC2 instances in a specific region
aws ec2 describe-instances --region us-east-1 --profile management-admin
Enter fullscreen mode Exit fullscreen mode

If you see "UnauthorizedOperation" or "AccessDenied" errors, check that your IAM user or role has the necessary permissions attached.

Deploying Governance before SSO

Here's the chicken and the egg! The problem with the first and recommended approach is that we need to first enable SSO in AWS and define an account for each user with the right accesss permissions. Without SSO, we're left with no choice rather using a temporary access key to work with IaC on AWS.

If creating an admin user in IAM with no restrictions feels too much and not a good governance approach for you, I have written a set of granular permissions that are needed for deploying our organization resources until we configure SSO.

Check out the permissions in my GitHub repository for the Terragrunt Live Environment example.

  • In your AWS Console, go to IAM -> Policies, and create a new policy for each of the JSON documents I have under the policies folder in my repository.
  • Next, go again to IAM -> Users, create a new terragrunt-root user, and attach these policies to it.
  • Generate a new pair o acess keys, and add it your AWS credentials file, as we discussed, with some name of acme-root, for example.

What's Next?

Now that we've configured AWS named profiles for secure authentication across multiple accounts, we have everything we need to actually deploy our governance infrastructure.

Follow me to get updates about my series IaC Startup on AWS. I'm writing new posts about deploying governance infrastructure with Terragrunt and Terraform.

Also, make sure to check my GitHub profile for new projects and updates.

Buy me a coffee if you like this post! :)

Buy Me A Coffee

Top comments (0)