DOCSEARCHbyAlgolia
Submit Docs

gimme-aws-creds

repository·master·Indexed 21 days ago

https://github.com/nike-inc/gimme-aws-creds

A CLI tool that automates the acquisition of short-lived AWS and Alibaba Cloud credentials using Okta SAML via an Identity Provider. It supports Okta Identity Engine (OIE) Device Authorization Flow, FIDO/WebAuthn authenticators, and an optional Lambda Service to act as a proxy to Okta APIs, removing the need for local Okta API keys.

Tokens
10.9K
Snippets
26
Records
53
Agent score
74%

What's inside gimme-aws-creds

  1. What is gimme-aws-creds and how does it work?

    master

    gimme-aws-creds is a Python CLI tool designed to acquire temporary AWS credentials via AWS STS using Okta as a SAML Identity Provider (IdP).

    Core Workflow

    1. Authentication: Authenticates the user via Okta (supporting both Okta Classic and Okta Identity Engine).
    2. MFA: Handles various Multi-Factor Authentication flows (Push, TOTP, SMS, Email, Voice, DUO, WebAuthn, etc.).
    3. SAML Exchange: Retrieves SAML assertions from Okta and exchanges them for temporary AWS STS credentials (or Alibaba Cloud RAM credentials).
    4. Credential Delivery:
      • Automatically writes credentials to ~/.aws/credentials (or ~/.aliyun/config.json for Alibaba Cloud).
      • Can output credentials to stdout in various formats like shell exports (export), JSON, or Windows PowerShell (windows).

    Key Capabilities

    • Multi-Cloud: Supports AWS (standard, GovCloud, China partitions) and Alibaba Cloud RAM.
    • Profile Management: Supports multiple configuration profiles with inheritance using the inherits = parent_profile syntax.
    • Account Resolution: Automatically resolves AWS account IDs to friendly aliases by scraping the AWS sign-in page.

  2. What is gimme-aws-creds?

    master

    gimme-aws-creds is a CLI tool that uses Okta as a SAML Identity Provider (IdP) to acquire temporary AWS credentials via AWS STS.

    Unlike other tools that require extensive configuration, gimme-aws-creds only requires your Okta username, password, Okta URL, and an MFA token (if enabled). It provides an interactive way to select which Okta AWS application and role you want to assume.

  3. Use the Lambda Service for gimme-aws-creds

    master
    The Lambda Service acts as an intermediary between the gimme-aws-creds CLI client and the Okta User and App APIs. Its primary purpose is to remove the requirement for an Okta API key to be stored locally on the CLI client and to filter Okta API results to only include the data necessary for requesting AWS credentials.

  4. How to use gimme-aws-creds with Okta Identity Engine (OIE)

    master

    When using an Okta Identity Engine (OIE) domain, the recommended method is the Device Authorization Flow. This flow uses your browser for authentication. Note that storing credentials in a keychain or passing MFA codes via the CLI is not possible with this method.

    Setup Steps for Device Authorization Flow:

    1. Create an OIDC Native Application in Okta with the following Grant Types: Authorization Code, Device Authorization, and Token Exchange.
    2. Pair the OIDC app with AWS Federation Apps: In the Okta Admin UI, go to Applications > [Your AWS Fed app] > Sign On and set Allowed Web SSO Client to the Client ID of your new OIDC Native Application.
    3. Configure the Client ID: Run gimme-aws-creds --action-configure or manually update the client_id in your configuration file with the OIDC app's Client ID.

    Important: Ensure the authentication policy for both the AWS Federation Application and the OIDC application are equivalent to avoid errors when requesting the Web SSO token.

  5. How gimme-aws-creds works (Architecture Overview)

    master

    The gimme-aws-creds tool acts as an orchestrator that automates the process of obtaining temporary cloud credentials from Okta.

    Core Workflow

    1. Configuration: It loads settings from CLI arguments, environment variables, or a configuration file (~/.okta_aws_login_config).
    2. Platform Detection: It detects whether your Okta instance is Classic or uses the Identity Engine (OIE).
    3. Authentication:
      • Classic: Uses username/password and handles MFA challenges via /api/v1/authn.
      • Identity Engine: Uses the OAuth 2.0 Device Authorization flow, often opening a browser for user interaction.
    4. Credential Exchange: It retrieves a SAML assertion from Okta and exchanges it for temporary credentials from AWS STS or Alibaba Cloud RAM.
    5. Output: Credentials can be written to a file, printed to stdout, or formatted as export commands or JSON.

  6. Use Alibaba Cloud credentials

    master

    Once configured, run the tool with the specific profile:

    gimme-aws-creds --profile alicloud-profile

    Output Formats:

    • Environment Variables: The export format emits:
      • ALIBABA_CLOUD_ACCESS_KEY_ID
      • ALIBABA_CLOUD_ACCESS_KEY_SECRET
      • ALIBABA_CLOUD_SECURITY_TOKEN
    • JSON Config: When write_aws_creds is enabled, it writes to ~/.aliyun/config.json in the format used by the official aliyun CLI (mode: StsToken).

    Note: You cannot mix AWS and Alibaba Cloud roles in a single invocation. A profile is strictly one or the other based on the enable_alicloud setting.

  7. Debug and diagnose credential acquisition

    master

    If you encounter issues during the authentication or credential retrieval process, use the --debug flag.

    This flag provides:

    • Structured Logs: Detailed request and response logs.
    • Resolved Configuration Report: A report showing exactly how your configuration was constructed, including source attribution (identifying if a setting came from a CLI flag, environment variable, profile setting, inherited profile, or default).
    • Security: The debug output automatically redacts sensitive payloads such as SAML responses, OAuth tokens, passwords, and authorization headers.

  8. Configure Alibaba Cloud (AliCloud) support

    master

    gimme-aws-creds supports Alibaba Cloud RAM credentials via the Okta Identity Engine (OIE) Native-to-Web SSO flow.

    Prerequisites:

    1. Okta Identity Engine: Requires OIE Device Authorization flow (Classic flow is not supported).
    2. Install SDK: You must install the optional dependency: pip install "gimme-aws-creds[alicloud]".
    3. Okta Configuration: Configure an Alibaba Cloud SAML app with appropriate RAM role mappings and enable Native-to-Web SSO / interclient token exchange.

    Setup via CLI:

    gimme-aws-creds --action-configure --enable-alicloud --profile alicloud-profile

    Setup via Config File (~/.okta_aws_login_config):

    [alicloud-profile]
okta_org_url = https://companyname.okta.com
okta_auth_server = your_auth_server
gimme_creds_server = appurl
app_url = https://companyname.okta.com/app/china_alibabacloud/app_instance_id/embed_url
client_id = your_client_id
enable_alicloud = True
alicloud_saml_url = https://companyname.okta.com/app/china_alibabacloud/app_instance_id/sso/saml
alicloud_region = cn-hangzhou

  9. Get AWS credentials

    master

    After configuring your profile, run gimme-aws-creds to authenticate. You will be prompted for your Okta username and password, then asked to select an application and a role. If MFA is required, you will be prompted to select an MFA factor.

    By default, credentials are written to your AWS credentials file. If you want to use them in your current shell session, you can automate the export of environment variables.

    Note: If you are not using gimme-creds-lambda or the appurl setting, you must set the OKTA_API_KEY environment variable.

    # Linux/macOS: Automatically export credentials to your current shell
$(gimme-aws-creds)

# Windows PowerShell
gimme-aws-creds | iex

# Run with a specific profile
gimme-aws-creds --profile profileName

# Specify username via flag
gimme-aws-creds -u user@domain.com

  10. Use Alibaba Cloud RAM with gimme-aws-creds

    master

    For Okta Identity Engine (OIE) users, gimme-aws-creds supports retrieving Alibaba Cloud RAM credentials via AssumeRoleWithSAML.

    Requirements

    • You must be using an Okta Identity Engine domain.
    • You must install the Alibaba Cloud dependencies via pip:
    pip install "gimme-aws-creds[alicloud]"

    Configuration

    To use Alibaba Cloud, ensure the following are configured:

    • enable_alicloud: Set to true.
    • alicloud_saml_url: The SAML URL for the Alibaba Cloud app.
    • alicloud_region: The target region (defaults to cn-hangzhou).

    Behavior

    • The tool performs a Native-to-Web SSO interclient OAuth token exchange with Okta.
    • Credentials are output to ~/.aliyun/config.json in the standard aliyun CLI format.
    • Note that Alibaba Cloud STS sessions are capped at 3600 seconds; the tool automatically clamps aws_default_duration to match this limit.

  11. Debug gimme-aws-creds with the --debug flag

    master

    When troubleshooting, use the --debug CLI flag to enable structured, human-readable diagnostics.

    Debug Features

    • Request/Response Logging: Logs all HTTP requests and responses with colorized status codes.
    • Resolved Configuration Report: Emits a report showing the effective configuration, including the source of every value (cli, env, profile, inherited from <parent>, or default).
    • Security Redaction: To prevent leaking secrets in logs, the debugger automatically redacts sensitive fields such as:
      • access_token, id_token, sessionToken, stateToken
      • password, client_secret
      • SAMLResponse, SAMLAssertion
      • Authorization and Cookie headers

  12. Deploy an OAuth Token Authorizer for the Lambda Service

    master

    The development of the OAuth Token authorizer and the deployment process for the Lambda is not provided by this repository. Developers are responsible for implementing their own authorizer.

    For a reference implementation on how to write an Authorizer and deploy an API using the Serverless framework, you can refer to the following external repository: https://github.com/pmcdowell-okta/oauth-jwt-serverless-aws-apigateway.