AWS CLI with 1Password MFA on macOS

A guide to configuring AWS CLI authentication using 1Password as your MFA provider

This guide walks helps you use 1Password to store your AWS access credentials and use that for securely using the AWS CLI. This allows you to securely authenticate using biometrics (Touch ID) instead of storing credentials in plaintext.

Prerequisites

• A 1Password subscription. This also works multiple accounts.
• 1Password desktop app installed
• Supported shell (Bash, Zsh, fish)

Installation Steps

1. Install 1Password CLI

On macOS using Homebrew:

brew install 1password-cli

Verify the installation:

op --version

2. Enable 1Password Desktop Integration

1. Open and unlock the 1Password app
2. Click your account/collection at the top of the sidebar
3. Go to Settings > Developer
4. Enable “Integrate with 1Password CLI”
5. For Touch ID authentication (Mac):
   • Go to Settings > Security
   • Enable “Touch ID”

3. Store AWS Credentials in 1Password

1. Create a new item in 1Password for your AWS credentials
2. Name it “AWS Access Key” (recommended for easier setup)
3. Add fields with label access key id and secret access key and add the corresponding values from AWS.

If 1Password does not allow generating a “generic” key, add a key of type Server and remove the unnecessary fields.

4. Set Up Multi-Factor Authentication (MFA)

1. Open the AWS credential item in 1Password
2. Click Edit
3. Add One-Time Password:
   • Click “Add More”
   • Choose “One-Time Password”
   • Copy the AWS MFA secret key into this field
4. Add MFA Serial:
   • Click “Add More”
   • Choose “Text”
   • Create a field titled exactly “mfa serial”
   • Paste your AWS MFA device ARN

5. Install AWS CLI

Install the AWS CLI following AWS’s official documentation.

6. Sign in to 1Password CLI

If you have multiple AWS accounts and the secrets are stored in multiple 1Password accounts, you can switch between which AWS Access Key by signing in to the correct 1Password account at this stage.

op signin

If you have multiple accounts, you can specify directly using

op signin --account <account-shorthand>

7. Initialize AWS Plugin

op plugin init aws

During setup:

• Select your AWS credentials item
• Choose when to use these credentials (session, directory, or global)

8. Configure Shell Integration

Add the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

source ~/.op/plugins.sh

9. Configure AWS Config

Create or edit ~/.aws/config:

[default]
output = json
region = <your-region>
mfa_serial = arn:aws:iam::<account-id>:mfa/<username>

[profile example-profile]
role_arn = arn:aws:iam::<account-id>:role/<role-name>
region = <region>

Important notes:

• The root profile must be named default
• The mfa_serial used for the OTP will be chosen directly from the AWS secret so there’s no need to specify it in the configuration.
• Additional role-based profiles can be added as needed.
• When defining role based profiles, make sure that the user (either directly or via a group) has the right (sts:AssumeRole) to assume that role.

Usage

Basic Usage

The next time you run an AWS command, you’ll be prompted for biometric authentication:

aws s3 ls

Using Profiles

To use a specific profile:

aws s3 ls --profile example-profile

Or set an environment variable:

export AWS_PROFILE=example-profile

Troubleshooting

Clear Credentials

To reset credentials:

op plugin clear aws

To clear all defaults:

op plugin clear aws --all

Inspect Configuration

To view your current AWS configuration:

op plugin inspect aws

Required Field Names

For manual credential setup in 1Password, ensure these exact field names:

• “Access Key ID” for AWS_ACCESS_KEY_ID
• “Secret Access Key” for AWS_SECRET_ACCESS_KEY
• “mfa serial” for MFA device ARN
• “one-time password” for MFA token generation