Please note: If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.
Introduction
AWS-OIDC is a command-line utility tool for generating temporary AWS STS credentials from an OIDC application. This works by:
- opening a browser window with the Identity Provider URL. this helps offboard the heavy logic around authentication + MFA to browser
- doing a local redirection to a temporary server on localhost to return the credentials back to our process
- Verifying flow with PKCE/public client
- Redeeming an id_token with the appropriate scopes
- Exchanging that token for temporary STS credentials
We also included a config generation web service that displays an AWS-OIDC-based Configuration file for authorized clients. The authorization requires an Okta Identity Provider, an AWS organizations role, and AWS worker roles for the accounts needed in the Config file.
Install (Linux, macOS)
We recommend using homebrew:
brew tap chanzuckerberg/tap
brew install aws-oidc
WSL2
We have tested on WSL2 Ubuntu-18. Make sure you've upgraded to WSL2. A couple extra steps are required:
sudo apt update && sudo apt install xdg-utils
brew tap chanzuckerberg/tap
brew install aws-oidc
creds-process
Authenticates into AWS and prints structured AWS credentials to stdout. The stdout output is based on AWS Configuration for External Processes.
$ aws-oidc creds-process --issuer-url=<issuer url> --client-id=<client ID> --aws-role-arn=<AWS role you want credentials for>
{
"Version": 1,
"AccessKeyId": "an AWS access key",
"SecretAccessKey": "your AWS secret access key",
"SessionToken": "the AWS session token for temporary credentials",
"Expiration": "ISO8601 timestamp when the credentials expire"
}
exec
Executes a command with AWS credentials loaded in the environment. Requires your ~/.aws/config
to be managed through aws-oidc configure
.
$ aws-oidc exec --profile <your profile> -- aws sts get-caller-identity
{
“UserId”: <...>
“Account”: <Account from that role-arn flag>
“Arn:”: <AWS STS ARN for the role-arn flag>
}
serve-config
Sets up the webserver that clients ping to set up their AWS Config.
Will query the aws config service (serve-config command) to help populate your ~/.aws/config
. It will guide you through the process of setting this up.
env
Env is primarily here to assist when running docker locally. It requires your ~/.aws/config
to be configured through aws-oidc configure
. You can run the following to test it out:
docker run -it --env-file <(aws-oidc env --profile <your aws profile>) amazon/aws-cli sts get-caller-identity
version
Prints the version of aws-oidc to stdout.
More docs
See docs for more docs.
Contributing
We use standard go tools + makefiles to build aws-oidc. Getting started should be as simple as-
- install go
- Clone this repo from
git@github.com:chanzuckerberg/aws-oidc.git
make setup && make
We follow the Contributor Conduct.
Releases
Each time a change gets merged to main, GitHub Actions triggers a release process. The build gets pushed to our chanzuckerberg/homebrew-tap repo so you can pull the latest version using brew
.
Copyright
Copyright 2019-2021, Chan Zuckerberg Initiative, LLC
For our license, see LICENSE.