Awsume CLI tool and Testfully Vault

Awsume(awsu.me) is a convenient way to manage session tokens and assume role credentials. If you are using Awsume as part of your workflow, this article will guide you through the process of integrating it with Testfully Vault for secure credential management.

When to use this guide

This guide is intended for users who are already using awsume in their workflow and want to integrate it with Testfully Vault for secure credential management. If you are not using awsume or are new to AWS credential management, awsume can be a great tool if you have one of the following use cases:

You want to access AWS resouces programmatically (e.g. AWS CLI, SDKs, Testfully Vault). Your account is configured to enforce MFA authentication, so you need to acquire temporary credentials that are valid for a specific duration. awsume can help you acquire these temporary credentials and manage them efficiently.
You have an AWS account with multiple roles and you want to easily switch between them. awsume allows you to assume different roles and manage the corresponding credentials without the need to manually update your AWS credentials file or environment variables.

Awsume <> Testfully Vault relationship

To fetch secrets from AWS Secrets Manager, Testfully Vault needs to authenticate with AWS first. One of the ways to authenticate is by using a set of AWS Access Key ID and Secret Access Key. However, these credentials can be temporary and may expire after a certain period of time. This is where Awsume comes in handy. By using Awsume, you can acquire temporary credentials that are valid for a specific duration. Testfully Vault can then use these temporary credentials to fetch secrets from AWS Secrets Manager without the need to manage long-term credentials.

Testfully Vault uses official AWS SDK in Rust to interact with AWS services. To authorize with AWS, the SDK looks for credentials in the ~/.aws/credentials file. Awsume can tap into this workflow by writing the temporary credentials it generates to the ~/.aws/credentials file, allowing Testfully Vault to seamlessly access the necessary credentials for authentication.

Configuring Awsume to write credentials to `~/.aws/credentials`

Writing credentials to the ~/.aws/credentials is not the default behaviour of Awsume, as it is designed to store credentials in a set of environment variables. However, you can configure Awsume to write the temporary credentials to the ~/.aws/credentials file by using the -o or --output-profile option. This option allows you to specify a profile name under which the temporary credentials will be stored in the ~/.aws/credentials file. For example, you can run the following command to assume a role and write the credentials to a profile named "testfully":

awsume myprofile -o testfully

This command will assume the role specified in the "myprofile" profile and write the temporary credentials to the "testfully" profile in the ~/.aws/credentials file. Testfully Vault can then use the "testfully" profile to authenticate with AWS and fetch secrets from AWS Secrets Manager. The "testfully" profile is just an example, and you can choose any profile name that suits your needs.

Awsume CLI tool and MFA authentication

If your AWS account requires Multi-Factor Authentication (MFA), Awsume can handle MFA authentication as well. When you run the Awsume command to assume a role, it will prompt you for the MFA token if MFA is required for the role you are trying to assume. Once you provide the MFA token, Awsume will generate temporary credentials that are valid for a specific duration. These temporary credentials will then be written to the ~/.aws/credentials file under the specified profile, allowing Testfully Vault to authenticate with AWS and fetch secrets from AWS Secrets Manager without any issues.

Examples workflows and use cases

Here we go through some example workflows and use cases to illustrate how Awsume and Testfully Vault can work together to manage AWS credentials and fetch secrets from AWS Secrets Manager.

Example 1: Fetching secrets with MFA authentication

In this example, we have an AWS account that requires MFA authentication for accessing AWS resources. We want to use Testfully Vault to fetch secrets from AWS Secrets Manager, but we need to acquire temporary credentials that are valid for a specific duration. We can use Awsume to assume a role and acquire temporary credentials that are valid for a specific duration, and then configure Testfully Vault to use those credentials to fetch secrets from AWS Secrets Manager.

Step 1: Configuring your AWS profile with MFA

First, you need to configure your AWS profile to require MFA authentication. You can do this by adding the following lines to your ~/.aws/config file:

[profile myprofile]
mfa_serial = arn:aws:iam::XXXXXXXXXX:mfa/XXXXXXX

Replace myprofile with a name of your choice for the profile, and replace the mfa_serial value with the ARN of your MFA device. This configuration tells AWS that when you use the myprofile profile, MFA authentication is required.

Step 2: Using Awsume to acquire temporary credentials

Next, you can use awsume to get a set of temporary credentials that are valid for a specific duration. To do this, run the following command:

awsume myprofile

awsume will prompt you for the MFA token, and once you provide it, it will generate temporary credentials that are valid for a specific duration. By default, these credentials will be stored in environment variables.

Step 3: Configuring Awsume to write credentials to `~/.aws/credentials`

As mentioned earlier, Testfully Vault looks for credentials in the ~/.aws/credentials file. To allow Testfully Vault to access the temporary credentials generated by Awsume, you can configure Awsume to write the credentials to the ~/.aws/credentials file under a specific profile. You can do this by running the following command:

awsume myprofile -o testfully

This command will assume the role specified in the "myprofile" profile and write the temporary credentials to the "testfully" profile in the ~/.aws/credentials file.

Step 4: Configuring Testfully Vault to use the temporary credentials

Finally, you can configure Testfully Vault to use the "testfully" profile to authenticate with AWS and fetch secrets from AWS Secrets Manager.

Example 2: Assuming roles

In this example, we will set up a workflow where we have a base AWS profile that holds the long-term credentials, and we want to use it within a different profile that assumes a role with specific permission. We have included the MFA authentication in this workflow as well, but you can skip it if your account does not require MFA authentication.

Step 1: Configuring the base profile with long-term credentials

First, you need to configure your base AWS profile with long-term credentials. You can do this by adding the following lines to your ~/.aws/credentials file:

[long-term-creds]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Replace long-term-creds with a name of your choice for the profile, and replace the aws_access_key_id and aws_secret_access_key values with your actual AWS access key ID and secret access key.

Step 2: Configuring the role profile with role assumption and MFA

Next, you need to configure a role profile that assumes a role with specific permissions. You can do this by adding the following lines to your ~/.aws/config file:

[profile role-profile]
source_profile = long-term-creds
role_arn = arn:aws:iam::XXXXXXXXXX:role/YourRoleName
mfa_serial = arn:aws:iam::XXXXXXXXXX:mfa/XXXXXXX

Replace role-profile with a name of your choice for your profile.
Replace long-term-creds with the name of the base profile you configured in Step 1.
Replace role_arn value with the ARN of the role you want to assume.
Replace mfa_serial value with the ARN of your MFA device.

This configuration tells AWS that when you use the role-profile profile, it should assume the role specified in the role_arn using the credentials from the long-term-creds profile, and that MFA authentication is required.

Step 3: Using Awsume to acquire temporary credentials for the role

Now, you can use awsume to acquire temporary credentials for the role specified in the role-profile. To do this, run the following command:

awsume role-profile -o testfully

This command will assume the role specified in the "role-profile" profile, prompt you for the MFA token, and once you provide it, it will generate temporary credentials that are valid for a specific duration. These credentials will be written to the "testfully" profile in the ~/.aws/credentials file.