gimme-aws-creds: short-lived AWS credentials from an Okta SAML login

Federated credentials without the Okta API key dance

The problem this tool solves comes from a specific corner of enterprise AWS. When a company federates AWS through Okta, the developer needs temporary credentials for a role, and the role is chosen inside the Okta application. The supported path for that is the SAML assertion flow: authenticate to Okta, get a SAML assertion, and hand it to AWS STS AssumeRoleWithSAML, which returns temporary credentials scoped to the role.

gimme-aws-creds is a CLI that uses an Okta identity provider via SAML to acquire short-lived cloud credentials, and it supports two clouds from the same authentication flow. For AWS the credentials are temporary credentials via AWS STS AssumeRoleWithSAML. For Alibaba Cloud they are temporary RAM credentials via the Alibaba Cloud STS AssumeRoleWithSAML, using the same Okta authentication, which is a genuinely useful addition for anyone running in both.

What you need is short enough to state in one sentence: your Okta username, password, org URL, and an MFA factor if MFA is enabled. The tool then prompts you to pick the Okta application and the role, or you can pre-configure both per profile, which is what turns it from a one-off into something a team can use daily.

The project positions itself against the alternative explicitly. Okta offers an open source Java CLI for the same purpose, and the README says it requires more configuration than the average Okta user has and does not scale well across multiple Okta applications. gimme-aws-creds is, in its own framing, designed to be friendlier for everyday use. That is a real difference in approach rather than a cosmetic one, at least in the project's own account.

There is a disclaimer worth repeating because it matters for anyone auditing the tool: Okta is a registered trademark of Okta, Inc., and this tool has no affiliation with or sponsorship by Okta, Inc.

Installing it: pip, Homebrew, git, Nix and a container

The recommended install is from PyPI, and the quick start shows the three commands that get a working profile and your first credentials:

pip3 install --upgrade gimme-aws-creds
gimme-aws-creds --action-configure
gimme-aws-creds

The configure action prompts for the Okta org URL, the app, the role and the rest, and the plain invocation afterwards gets the credentials. The upgrade flag on the pip command is there because the tool moves fast enough that an older version is a common cause of a confusing failure.

For macOS users there is a Homebrew package:

brew install gimme-aws-creds

The other routes exist for people who cannot use PyPI or who need reproducibility. Installing straight from the GitHub repository uses the git URL form, and installing from a local checkout uses the module form of pip. Both are in the README behind collapsible sections, alongside two Nix options, a flake for nix develop and a shell.nix for nix-shell, each of which pulls the package from the GitHub repository and produces a shell with the tool in it.

Alibaba Cloud support is an optional extra, installed with the extra name in brackets and enabled at configuration time:

pip3 install --upgrade "gimme-aws-creds[alicloud]"
gimme-aws-creds --action-configure --enable-alicloud --profile alicloud

The container route builds a small image from the repository:

docker build -t gimme-aws-creds .

The Dockerfile is a python:3.10-alpine base that installs the package, adds the build toolchain and then removes it again in the same layer sequence, leaving a runtime image whose entry point is the gimme-aws-creds binary. The README also suggests a shell alias that runs the tool in a container, and it is instructive to read what that alias mounts: the local AWS credentials file and the local Okta login configuration are both bind-mounted into the container. The alias comment even tells you to make sure the config file exists locally first, which is a hint that the containerised flow expects the same local state the native one does.

The lambda proxy and the OKTA_API_KEY alternative

There is one optional component that changes the security shape of the tool, and it is described in the prerequisites rather than buried.

The problem it solves is the Okta API key. A tool that wants to enumerate the applications and roles available to a user has to ask the Okta API, and the simplest way to do that is with an API key. Handing every developer an Okta API key is not something most security teams want, and a key that does not expire is a key that eventually leaks.

gimme-creds-lambda is offered as an optional proxy to the Okta APIs the tool needs. It removes the requirement of an Okta API key, because gimme-aws-creds authenticates to the lambda with OpenID Connect and the lambda handles all the interactions with the Okta APIs. The lambda lives in the same repository, under a lambda directory.

The alternative is direct access. Set the OKTA_API_KEY environment variable and the gimme_creds_server configuration value to internal, and the tool calls the Okta APIs itself rather than going through the proxy. So there are two operating modes, and the choice is between a credential that is short-lived and scoped to your identity, and an API key that is not.

The rest of the prerequisites are the usual ones. Python 3.10 or newer, and an Okta SAML integration to AWS set up through the AWS App. The README flags platform caveats, including a note about Python 3.10 and newer on Windows, and the packaging metadata agrees with the 3.10 floor, which is worth checking on a machine that is still on an older interpreter.

Profiles, reserved words and the MFA options

The configuration system is where a tool like this either becomes usable in a team or stays a personal script, and the README documents profiles, a configuration file format, a list of configuration parameters and a set of reserved words.

The configuration file lives at ~/.okta_aws_login_config, which is the path the Docker alias mounts into the container, so the same file works for the native and the containerised flow. A profile holds the settings for one Okta application and role combination, which is what lets a developer who has access to several roles switch between them without retyping the org URL every time. The reserved words in cred_profile are the parameters that the tool manages rather than the user, and knowing which ones are reserved matters when you write a profile by hand rather than through --action-configure.

The MFA configuration is a first-class section, with a documented list of preferred MFA types, and the requirements file shows the machinery behind it. The okta library, fido2 and a package called ctap-keyring-device are present, and the README has a section on MFA security keys support. ctap-keyring-device is pinned to an exact version and is installed conditionally, with the condition excluding Windows on Python 3.10 and newer.

The rest of the dependency list is ordinary and informative. boto3 for the STS call, keyring for storing secrets where the platform allows it, requests and urllib3 for the HTTP layer, beautifulsoup4 and html5lib for parsing the Okta pages the browser flow returns, furl for URL handling and pyjwt for token work. The presence of beautifulsoup4 and html5lib is the detail that explains the design: the tool does not only speak a protocol, it also parses the HTML that the Okta login flow returns.

What ends up on disk, and the trust that requires

It is worth being explicit about where the secrets go, because that is where the risk in a tool like this lives.

The credentials are written to the AWS credentials file, ~/.aws/credentials, in the standard shared credentials format, which is what the container alias bind-mounts. They are temporary, so the window is short, but they are still sitting in a plaintext file on the machine afterwards, and the same applies to the Okta login configuration, which holds the org URL, the app and the role selection and, depending on the configuration, a token of some kind.

The keyring dependency is the mitigation the tool offers for at least some of it.. The OKTA_API_KEY environment variable is the other credential to think about, since an environment variable ends up in shell history, in process listings and in whatever CI logs the command runs in.

The other structural risk is the browser login. Because the tool drives a real Okta login and parses the pages it returns, it sits on the credential path of your identity provider, and it does so on a machine where a second person might be able to observe the session. The MFA section and the security key support are there to make that flow as close to the real Okta flow as possible, which is the right instinct.

None of this makes the tool unsuitable. It makes it a tool for developer workstations that are treated as sensitive, and it means the deployment question is not only about the CLI but also about where the session token ends up and for how long. A team that answers those questions deliberately will find the tool fits; a team that copies the quick start onto a shared machine will not have thought about them.

The commands, the JSON mode and the Python API

The usage section of the README is organised around the questions a user actually asks at the terminal. There is a command for viewing profiles and a command for viewing roles, which is the practical answer to the question of which role you are about to assume, and a command for showing credential expiration time, which is what you check when a job fails with an expired token halfway through.

There is also a pair of commands for handling credentials as JSON, one to generate them and one to store them from JSON. That pairing is the interesting part, because it is the seam where this tool meets an automated system. Generating JSON lets a script capture the credentials as structured data, and storing from JSON lets a script write them into the credentials file without a human in the loop. A pipeline that needs to assume a role on a schedule can use those two commands without ever opening a browser, provided the session is still valid.

The README also documents a Python API, which means the credential acquisition can be called as a library from your own code rather than shelled out to. For a team that wants to build the flow into an internal tool, that is the more maintainable surface, and it also means the browser interaction is something you can wrap and report on rather than something a user has to trigger by hand.

Command auto completion is provided as well, through a setup_autocomplete.sh script and a gimme-aws-creds-autocomplete.sh entry point listed in the packaging metadata, which matters more than it sounds for a CLI with as many flags and profile names as this one has.

Licence, maintenance and the gap in the release history

The licence is Apache-2.0. The packaging metadata records it as Apache License, v2.0, and the repository has a LICENSE file, a NOTICE file and a LONG_DESCRIPTION.md used as the long description for the package index. This describes the published terms rather than legal advice.

The maintenance picture needs a careful look, because two different version numbers appear. The released tags are v2.8.2 from 2024-05-13, v2.8.1.1 from 2024-04-24 and v2.8.1 from 2024-04-23, while the version in setup.py is 2.9.0-pre, which is a pre-release marker for a version that has never been published as a tag. The repository is not archived and the last push was on 2026-06-02, so work has continued after the last release, and the code on the master branch is ahead of what pip install gives you.

That gap has a practical consequence. The dependency ranges in requirements.txt are tight and modern, with boto3 at 1.42 or newer, keyring at 25.6 or newer, okta at 3.4.2 or newer and fido2 at 0.9.1 or newer, and the alibabacloud_sts20150401 extra is pinned to a narrow range as well. Those floors sit well past the 2024 release date, which suggests the range was adjusted after the tag, and it means the code on master has a different dependency profile from the published package.

The project has a Makefile, a tests directory, a requirements_dev.txt, a Dockerfile, a lambda directory and a default.nix alongside the flake, and a CONTRIBUTING.md. For an internal tool that many organisations will fork rather than depend on, the practical question is which version you adopt: the published 2.8.2, or the master branch with the newer dependency floors. Reading the changelog and the diff between them is the sensible first step, and pinning the result in your own tooling is the safe conclusion.

Editorial conclusion

Adopt gimme-aws-creds when your organisation already federates AWS through Okta SAML and your developers need short-lived role credentials without an Okta API key in every laptop, since the lambda proxy removes that requirement. It is the wrong tool for a team that does not use Okta, for an environment where the SAML app and role must be chosen automatically rather than by a person, and for a machine where writing credentials to a shared file is unacceptable. Before rolling it out, confirm the Python 3.10 floor on your platform, decide whether the proxy or a direct API call with OKTA_API_KEY suits your policy, and read the stored credentials out of the AWS credentials file only through a mechanism that does not leave them on disk longer than the session needs them.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Nike-Inc/gimme-aws-creds on GitHub
4. README
5. Releases