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
- Open and unlock the 1Password app
- Click your account/collection at the top of the sidebar
- Go to Settings > Developer
- Enable “Integrate with 1Password CLI”
- For Touch ID authentication (Mac):
- Go to Settings > Security
- Enable “Touch ID”
3. Store AWS Credentials in 1Password
- Create a new item in 1Password for your AWS credentials
- Name it “AWS Access Key” (recommended for easier setup)
- Add fields with label
access key id
andsecret access key
and add the corresponding values from AWS.
If
1Password
does not allow generating a “generic” key, add a key of typeServer
and remove the unnecessary fields.
4. Set Up Multi-Factor Authentication (MFA)
- Open the AWS credential item in 1Password
- Click Edit
- Add One-Time Password:
- Click “Add More”
- Choose “One-Time Password”
- Copy the AWS MFA secret key into this field
- 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 whichAWS Access Key
by signing in to the correct1Password
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