Please note: If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.
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.
We recommend using homebrew:
brew tap chanzuckerberg/tap
brew install aws-oidc
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
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"
}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>
}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 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
Prints the OIDC tokens to stdout in JSON format. Useful for debugging or piping into other tools.
$ aws-oidc token --issuer-url=<issuer url> --client-id=<client ID>
{"version":1,"id_token":"...","access_token":"...","expiry":"2026-02-25T15:38:01Z"}Checks whether the cached OIDC token is present and valid. Prints valid or invalid to stdout and exits with a non-zero status if the token is missing or expired. This does not trigger a refresh flow.
$ aws-oidc check-token-valid --issuer-url=<issuer url> --client-id=<client ID>
validPrints the remaining time-to-live of the cached refresh token by calling the issuer's introspection endpoint. Useful for monitoring when a user will need to re-authenticate.
$ aws-oidc check-refresh-ttl --issuer-url=<issuer url> --client-id=<client ID>
2159h59m57.088655sPrints the version of aws-oidc to stdout.
In environments where many hosts share a home directory over NFS (e.g. HPC clusters, shared compute nodes), the default OIDC token cache at ~/.cache/oidc-cli/ can cause problems:
O_APPENDwrites are not atomic on NFS, so concurrent processes on different hosts can overwrite each other's data.flock-based file locking is unreliable across NFS clients.- Atomic
renamemay not be safe across NFS server frontends.
Use the --node-local-cache flag (or the AWS_OIDC_NODE_LOCAL_CACHE environment variable) to store the OIDC token cache and lock files on node-local disk instead. The value should be a directory that is not on an NFS mount and unique per user (e.g. /tmp/oidc-cache-$(id -u) or a path on a local SSD):
$ aws-oidc creds-process --node-local-cache "/tmp/oidc-cache-$(id -u)" \
--issuer-url=<issuer url> --client-id=<client ID> --aws-role-arn=<role ARN>Or equivalently, via the environment variable:
$ export AWS_OIDC_NODE_LOCAL_CACHE="/tmp/oidc-cache-$(id -u)"
$ aws-oidc creds-process --issuer-url=<issuer url> --client-id=<client ID> --aws-role-arn=<role ARN>$ aws-oidc exec --node-local-cache "/tmp/oidc-cache-$(id -u)" --profile <your profile> -- aws sts get-caller-identityThe environment variable is useful for setting this once in your shell profile (e.g. .bashrc, .zshrc) so every invocation uses node-local storage automatically. If both the flag and the environment variable are set, the flag takes precedence.
On first use, the local cache is bootstrapped by copying the existing token from the default (NFS) cache. All subsequent reads, writes, and lock operations use the local directory, avoiding cross-host contention entirely.
This flag is available on all subcommands (token, exec, creds-process, configure, check-token-valid, check-refresh-ttl).
See docs for more docs.
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.
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 2019-2021, Chan Zuckerberg Initiative, LLC
For our license, see LICENSE.
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.