DOCSEARCHbyAlgolia
Submit Docs

okta-aws-cli

repository·master·Indexed 41 days ago

https://github.com/okta/okta-aws-cli

A CLI tool that uses Okta as an identity provider to retrieve AWS IAM temporary credentials. It supports three authorization modes: `web` for human users via browser-based device authorization, `m2m` for machine-to-machine headless authorization using private keys, and `direct` for human users via Okta's Direct Authentication with MFA. Credentials can be output as environment variables, JSON, or written directly to the AWS credentials file.

Tokens
10.6K
Snippets
31
Records
40
Agent score
45%

What's inside okta-aws-cli

  1. Overview of okta-aws-cli

    master

    okta-aws-cli is a CLI tool that uses Okta as an identity provider to retrieve AWS IAM temporary credentials. These credentials can be used with the AWS CLI, AWS SDKs, and other tools that interface with the AWS API.

    It supports three primary authorization modes:

    • web: Human-oriented authorization using device authorization (browser-based).
    • m2m: Machine-to-machine/headless authorization using a private key (intended for CI/CD, not human use).
    • direct: Authorization via Okta's Direct Authentication (out-of-bounds MFA).

    The tool can output credentials in three formats: environment variables, the AWS credentials file, or JSON for AWS process credentials.

  2. Key differences between Okta AWS CLI and other tools

    master

    Compared to tools like Nike's gimme-aws-creds or Versent's saml2aws, the Okta AWS CLI has the following characteristics:

    • Native OIE Support: It is built for the Okta Identity Engine (OIE) and naturally respects all authentication flows (MFA, assigned users, etc.) applied to the Native OIDC application. It does not work with Classic orgs.
    • Browser-based Authentication: Instead of prompting for passwords in the terminal, the CLI provides a URL for the user to open in a browser to initiate authentication and authorization. It does not store user credentials in a desktop keychain.
    • Minimal Configuration: Requires only two values: the Okta org domain name and the OIDC app ID.
    • Output and Credential Management: The CLI is oriented around flags and environment variables. Its default output is environment variables. It can write to the AWS credentials file, defaulting to an append operation. You can use the --write-aws-credentials flag to explicitly overwrite previous values for a profile.

  3. Use friendly labels for IdPs and Roles via `okta.yaml`

    master

    To avoid reading long ARN strings in the interactive picker, you can create a configuration file at $HOME/.okta/okta.yaml. This file allows you to map ARN values to human-readable alias labels. Supports regular expressions for roles.

    Example $HOME/.okta/okta.yaml:

    ---
awscli:
  idps:
    "arn:aws:iam::123456789012:saml-provider/company-okta-idp": "Data Production"
    "arn:aws:iam::012345678901:saml-provider/company-okta-idp": "Data Development"
  roles:
    "arn:aws:iam::.*:role/admin": "Admin"
    "arn:aws:iam::.*:role/operator": "Ops"
    --- 
awscli:
  idps:
    "arn:aws:iam::123456789012:saml-provider/company-okta-idp": "Data Production"
  roles:
    "arn:aws:iam::.*:role/admin": "Admin"

  4. Okta AWS CLI Authentication Requirements

    master

    To ensure successful authentication, follow these configuration recommendations:

    1. Policy Parity: Ensure the AWS Federation Application and the OIDC native application have equivalent policies. If the AWS Federation app has more stringent assurance requirements than the OIDC app, you may encounter a 400 Bad Request API error.
    2. Device State: In the authentication policy rule for the AWS Federation app, Device State must be set to Any. Other options are currently unsupported.

  5. Build, test, and maintain okta-aws-cli

    master

    The project includes a Makefile to automate common development tasks. Use the following commands to build the binary, run tests, or manage development tools.

    • Build the project: make build
    • Run tests: make test
    • Install development tools (e.g., gofumpt, golint): make tools
    • Run code quality control (e.g., go vet, golint): make qc
    make build
make test
make tools
make qc

  6. Use okta-aws-cli for shell scripting (eval)

    master

    The CLI is designed to be shell-friendly. Human-oriented output is sent to STDERR, while machine-readable AWS credentials (export statements) are sent to STDOUT. This allows you to use eval to inject credentials directly into your current shell session.

    Example usage with web command:

    eval `okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com` && aws s3 ls
    eval `okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com` && aws s3 ls

  7. Use the direct command for human user authorization

    master

    The direct command implements a human-centric authorization flow using Okta's Direct Authorization (username/password grant). This flow supports multi-factor authentication (MFA) via push notifications to Okta Verify.

    Workflow:

    1. The user provides a username and password.
    2. A push notification is sent to Okta Verify.
    3. Once acknowledged, the Okta authorization server returns an access token.
    4. The token is exchanged via AWS STS AssumeRoleWithWebIdentity for AWS credentials.

    Output: The command provides AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN (60-minute default expiry).

    # Example of interactive usage with execution
$ read -p "Okta Username: " myusername && read -s -p "Okta Password: " mypassword && echo 

Okta Username: test@example.com
Okta Password:

$ okta-aws-cli direct \
  --format noop \
  --org-domain test.okta.com \
  --oidc-client-id 0oa123 \
  --authz-id aus456 \
  --aws-iam-role arn:aws:iam::1234567890:role/my-role \
  --username "${myusername}" \
  --password "${mypassword}" \
  --exec -- aws sts get-caller-identity

  8. Configure okta-aws-cli global settings

    master

    The okta-aws-cli can be configured using command line flags, environment variables, or an .env file. The evaluation order is: command line flags > environment variables > .env file.

    At a minimum, the CLI requires the Okta Org Domain, the OIDC Client ID, and the AWS Federation integration app ID (though the app ID is optional for the web command if multiple environments are already configured).

    Note on AWS Regions: If using a non-commercial region like GovCloud, ensure AWS_REGION is set. If AWS_REGION is set in an .env file, it will be promoted to the CLI runtime even if not set as a system environment variable.

    export OKTA_AWSCLI_ORG_DOMAIN="my-org.okta.com"
export OKTA_AWSCLI_OIDC_CLIENT_ID="0oaa4htg72TNrkTDr1d7"

  10. Use the web command to retrieve AWS credentials

    master

    The web command is designed for human users. It initiates a device authorization flow where the user completes authentication in a web browser (via a URL or QR code) and then returns to the CLI to receive AWS credentials.

    Note: The AWS Federation App and associated web SSO token used by this command do not support device security posture.

    To use the web command, provide the OIDC client ID, the AWS account federation app ID, and your Okta organization domain. The command will output export statements (on *nix) or SETX statements (on Windows) to set the following environment variables:

    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_SESSION_TOKEN

    The AWS_SESSION_TOKEN has a default expiry of 60 minutes, which can be adjusted using the AWS Session Duration CLI flag.

    # *nix example
$ okta-aws-cli web --oidc-client-id 0oabc --aws-acct-fed-app-id 0oaxy --org-domain my-org.okta.com
export AWS_ACCESS_KEY_ID=ASIAUJHVCS6UQC52NOL7
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5T...

# Windows example
C:\> okta-aws-cli web --oidc-client-id 0oabc --aws-acct-fed-app-id 0oaxy --org-domain my-org.okta.com
SETX AWS_ACCESS_KEY_ID ASIAUJHVCS6UQC52NOL7
SETX AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
SETX AWS_SESSION_TOKEN AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5T...

  11. Install okta-aws-cli

    master

    You can install okta-aws-cli using several methods depending on your operating system and environment:

    macOS (Homebrew)

    brew install okta-aws-cli

    Windows (Chocolatey)

    choco install okta-aws-cli

    Go (Direct Install)

    Requires Go 1.21 or later. This installs the binary to your $GOPATH/bin (typically ~/go/bin).

    # Install the latest version
go install github.com/okta/okta-aws-cli/v2@latest

# Install a specific version
go install github.com/okta/okta-aws-cli/v2@v2.5.1

    Binaries

    Manual binary releases for various OS/architectures are available on the GitHub releases page.

    brew install okta-aws-cli

  12. Use the m2m command for machine-to-machine authorization

    master

    The m2m command enables headless machine-to-machine (M2M) authorization. It uses an Okta OIDC app and a private key to request an Okta access token, which is then exchanged via AWS STS AssumeRoleWithWebIdentity for AWS credentials.

    Important Security Note: This feature is not intended for human use. Use industry-standard secrets management for the private key.

    Output: Upon success, the command exports AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN as environment variables. The AWS_SESSION_TOKEN has a default expiry of 60 minutes.

    Requirements:

    • An Okta API service app configured with "Public key / Private key" client authentication.
    • An Okta authorization server (default or custom) with a custom scope (defaults to okta-m2m-access).
    • An Okta access policy associated with the service app that allows the Client Credentials grant type and the required scope.
    • An AWS IAM OpenID Connect (OIDC) identity provider configured with the Okta authorization server's issuer URL and Audience.
    # Example using environment variables for a headless CI environment
export OKTA_AWSCLI_ORG_DOMAIN="my-org.okta.com"
export OKTA_AWSCLI_OIDC_CLIENT_ID="0oaa4htg72TNrkTDr1d7"
export OKTA_AWSCLI_IAM_ROLE="arn:aws:iam::1234:role/Circle-CI-ops"
export OKTA_AWSCLI_CUSTOM_SCOPE="okta-m2m-access"
export OKTA_AWSCLI_KEY_ID="kid-rock"
export OKTA_AWSCLI_PRIVATE_KEY="... long string with new lines ..."
export OKTA_AWSCLI_AUTHZ_ID="aus8w23r13NvyUwln1d7"

$ okta-aws-cli m2m