### Authenticate with Okta AWS CLI on Windows

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Provides examples for using `okta-aws-cli web` on Windows to perform OIDC authentication. It shows how to launch various browsers (e.g., msedge, chrome) with specific arguments like incognito mode or custom profiles via `cmd.exe /C start`, which spawns the browser installed on the host OS.

```shell
okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "cmd.exe /C start msedge"

okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "cmd.exe /C start chrome"

okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "cmd.exe /C start chrome --incognito"

okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "cmd.exe /C start chrome --profile-directory=\"Profile\ 1\""
```

--------------------------------

### Install okta-aws-cli via Chocolatey on Windows

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This command installs the okta-aws-cli tool on Windows using the Chocolatey package manager. Chocolatey provides a convenient way to manage software installations on Windows.

```shell
> choco install okta-aws-cli
```

--------------------------------

### Okta AWS CLI .env File Configuration Example

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Illustrates how to define `OKTA_AWSCLI_ORG_DOMAIN` and `OKTA_AWSCLI_OIDC_CLIENT_ID` within a `.env` file for the Okta AWS CLI.

```dotenv
OKTA_AWSCLI_ORG_DOMAIN=my-org.okta.com
OKTA_AWSCLI_OIDC_CLIENT_ID=0oa5wyqjk6Wm148fE1d7
```

--------------------------------

### Install okta-aws-cli via Homebrew on macOS

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This command installs the okta-aws-cli tool on macOS using the Homebrew package manager. Homebrew simplifies the process of installing command-line tools.

```shell
$ brew install okta-aws-cli
```

--------------------------------

### Build okta-aws-cli from Source using Make

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This command builds the okta-aws-cli tool from its source code using a Makefile. The compiled binary will be installed into the Go binary directory, making it available in your system's PATH.

```shell
$ make build
```

--------------------------------

### Example Output of Okta AWS CLI List Profiles

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This text block shows the expected output format when running `okta-aws-cli list-profiles`. It lists each profile name, often accompanied by additional descriptive information like environment details, for user convenience.

```text
Profiles:

 sample-account X(Non-Prod)
 sample-account X (Prod)
 another-sample-account Y (Non-Prod)
```

--------------------------------

### Okta AWS CLI Global Configuration Parameters

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This section details the global configuration parameters for the `okta-aws-cli` tool. It lists each parameter's name, description, corresponding command-line flag, and environment variable/`.env` file value. It also indicates whether a parameter is optional or required, and provides examples where applicable.

```APIDOC
Parameter: AWS Region
  Description: AWS region (will override ENV VAR `AWS_REGION` and `AWS_DEFAULT_REGION`) e.g. `us-east-2`
  Optional: Yes
  Command Line Flag: --aws-region [value]
  Environment Variable: OKTA_AWSCLI_AWS_REGION

Parameter: Okta Org Domain
  Description: Full host and domain name of the Okta org e.g. `my-org.okta.com` or the custom domain value
  Required: Yes
  Command Line Flag: --org-domain [value]
  Environment Variable: OKTA_AWSCLI_ORG_DOMAIN

Parameter: OIDC Client ID
  Description: For `web` the OIDC native application / [Allowed Web SSO Client ID](#allowed-web-sso-client-id), for `m2m` and `direct` the API services app ID
  Required: Yes
  Command Line Flag: --oidc-client-id [value]
  Environment Variable: OKTA_AWSCLI_OIDC_CLIENT_ID

Parameter: AWS IAM Role ARN
  Description: For web preselects the role list to this preferred IAM role for the given IAM Identity Provider. For `m2m` and `direct`
  Optional: Yes (for `web`), Required: Yes (for `m2m` and `direct`)
  Command Line Flag: --aws-iam-role [value]
  Environment Variable: OKTA_AWSCLI_IAM_ROLE

Parameter: AWS Session Duration
  Description: The lifetime, in seconds, of the AWS credentials. Must be between 60 and 43200.
  Optional: Yes
  Command Line Flag: --aws-session-duration [value]
  Environment Variable: OKTA_AWSCLI_SESSION_DURATION

Parameter: Output format
  Description: Default is `env-var`. Options: `env-var` for output to environment variables, `aws-credentials` for output to AWS credentials file, `process-credentials` for credentials as JSON, or `noop` for no output which can be useful with `--exec`
  Optional: Yes
  Command Line Flag: --format [value]
  Environment Variable: OKTA_AWSCLI_FORMAT

Parameter: Profile
  Description: Default is `default`
  Optional: Yes
  Command Line Flag: --profile [value]
  Environment Variable: OKTA_AWSCLI_PROFILE

Parameter: Cache Okta access token
  Description: Cache Okta access token at `$HOME/.okta/awscli-access-token.json` to reduce need to open device authorization URL. Okta access token has an expiry of 60 minutes and can not be configured otherwise. Further, attempt to read token will only occur when flag is enabled.
  Optional: Yes (`true` if flag is present)
  Command Line Flag: --cache-access-token
  Environment Variable: OKTA_AWSCLI_CACHE_ACCESS_TOKEN=true

Parameter: Alternate AWS credentials file path
  Description: Path to alternative credentials file other than AWS CLI default
  Optional: Yes
  Command Line Flag: --aws-credentials
  Environment Variable: OKTA_AWSCLI_AWS_CREDENTIALS

Parameter: Overwrite AWS credentials file
  Description: (Over)write the given profile to the AWS credentials file. WARNING: When enabled, overwriting can inadvertently remove dangling comments and extraneous formatting from the creds file.
  Optional: Yes (`true` if flag is present)
  Command Line Flag: --write-aws-credentials
  Environment Variable: OKTA_AWSCLI_WRITE_AWS_CREDENTIALS=true

Parameter: Emit deprecated AWS variable `aws_security_token`
  Description: Emit deprecated AWS variable `aws_security_token` with duplicated value from `aws_session_token`. AWS CLI removed any reference and documentation for `aws_security_token` in November 2014.
  Optional: Yes (`true` if flag is present)
  Command Line Flag: --legacy-aws-variables
  Environment Variable: OKTA_AWSCLI_LEGACY_AWS_VARIABLES=true

Parameter: Emit expiry timestamp `x_security_token_expires`
  Description: Emit expiry timestamp `x_security_token_expires` in RFC3339 format for the session/security token (AWS credentials file only). This is a non-standard profile variable.
  Optional: Yes (`true` if flag is present)
  Command Line Flag: --expiry-aws-variables
  Environment Variable: OKTA_AWSCLI_EXPIRY_AWS_VARIABLES=true
```

--------------------------------

### Run okta-aws-cli Directly from Go Source

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This command allows running the okta-aws-cli tool directly from its Go source code without a prior build or installation. It's useful for development or quick testing.

```shell
$ go run cmd/okta-aws-cli/main.go --help
```

--------------------------------

### Run Okta AWS CLI with a Specific Configuration Profile

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Provides an example command-line invocation of `okta-aws-cli` using the `--profile` flag to specify a named configuration profile defined in the `okta.yaml` file.

```Shell
$ okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com --profile staging
```

--------------------------------

### Display Okta AWS CLI Version

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Shows the command to retrieve and display the current version of the `okta-aws-cli` tool installed on the system. This helps in verifying the installed client version for compatibility or debugging purposes.

```shell
okta-aws-cli --version
```

--------------------------------

### Authenticate with Okta AWS CLI on macOS

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Demonstrates how to use `okta-aws-cli web` on macOS to initiate an OIDC authentication flow. It includes examples for opening specific browser profiles or incognito windows using the `--open-browser-command` flag, which appends the device authorization URL to the browser arguments.

```shell
okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --profile-directory=\"Profile\ 1\""

okta-aws-cli web \
  --oidc-client-id 0oabc \
  --org-domain my-org.okta.com \
  --open-browser-command "open -na \"Google\ Chrome\" --args --incognito"
```

--------------------------------

### Okta AWS CLI Web Command with OIDC Client Grant

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Example command-line usage of `okta-aws-cli web` when the OIDC client has the `okta.users.read.self` grant, specifying the organization domain and OIDC client ID.

```shell
$ okta-aws-cli web --org-domain my-org.okta.com \
    --oidc-client-id 0oa5wyqjk6Wm148fE1d7 \
```

--------------------------------

### Set Okta AWS CLI Environment Variables

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Example demonstrating how to set `OKTA_AWSCLI_ORG_DOMAIN` and `OKTA_AWSCLI_OIDC_CLIENT_ID` using `export` commands in a shell environment for the Okta AWS CLI.

```shell
export OKTA_AWSCLI_ORG_DOMAIN=my-org.okta.com
export OKTA_AWSCLI_OIDC_CLIENT_ID=0oa5wyqjk6Wm148fE1d7
```

--------------------------------

### Okta AWS CLI Development Commands

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Provides essential commands for local development of the `okta-aws-cli` project. This includes running the application from source, installing necessary development tools, building the executable, running tests, and performing code quality checks using `make` commands.

```shell
go run cmd/okta-aws-cli/main.go
```

```shell
make tools
```

```shell
make build
```

```shell
make test
```

```shell
make qc
```

--------------------------------

### Example AWS STS Get Caller Identity JSON Output

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This JSON snippet illustrates the typical output from the `aws sts get-caller-identity` command after a successful `okta-aws-cli direct` authentication. It provides the User ID, AWS Account ID, and the ARN of the assumed IAM role, confirming the identity used for AWS API calls.

```json
{
    "UserId": "ZYZ789:okta-aws-cli",
    "Account": "1234567890",
    "Arn": "arn:aws:sts::1234567890:assumed-role/my-role"
}
```

--------------------------------

### Okta API: Get User App Links Endpoint

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This API documentation describes the `GET /api/v1/users/me/appLinks` endpoint, which is referenced by `okta-aws-cli` to discover Okta AWS Federation applications assigned to the current user. This endpoint requires the `okta.users.read.self` OAuth 2.0 scope.

```APIDOC
Endpoint: GET /api/v1/users/me/appLinks
Description: Retrieves a list of Okta AWS Federation applications assigned to the current user.
Required Scope: okta.users.read.self
Usage: Referenced by okta-aws-cli to discover assigned applications.
```

--------------------------------

### Execute Commands with Injected AWS Credentials

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Demonstrates how `okta-aws-cli` can execute a follow-on process, injecting temporary AWS credentials as environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`). It shows examples of printing environment variables, listing S3 buckets, and handling errors from the executed process.

```shell
$ okta-aws-cli m2m --format noop --oidc-client-id 0oabc --org-domain my-org.okta.com --exec -- printenv
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=ASIAUJHVCS6UYRTRTSQE
AWS_SECRET_ACCESS_KEY=TmvLOM/doSWfmIMK...
AWS_SESSION_TOKEN=FwoGZXIvYXdzEF8aDKrf...
```

```shell
$ okta-aws-cli m2m --format noop --oidc-client-id 0oabc --org-domain my-org.okta.com --exec -- aws s3 ls s3://example
                           PRE aaa/
2023-03-08 16:01:01          4 a.log
```

```shell
$ okta-aws-cli m2m --format noop --oidc-client-id 0oabc --org-domain my-org.okta.com --exec -- aws s3 mb s3://no-access-example
error running process
aws s3 mb s3://yz-nomad-og
make_bucket failed: s3://no-access-example An error occurred (AccessDenied) when calling the CreateBucket operation: Access Denied

Error: exit status 1
```

--------------------------------

### Basic Usage of okta-aws-cli for Credential Acquisition

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This example demonstrates the plain usage of okta-aws-cli to obtain temporary AWS credentials. It initiates an Okta device authorization flow, prompts the user to choose an IdP and Role, and then outputs the AWS credentials as environment variables (export for Linux/macOS, setx for Windows). These credentials can then be used by the AWS CLI.

```shell
$ okta-aws-cli
Open the following URL to begin Okta device authorization for the AWS CLI.

https://test-org.okta.com/activate?user_code=ZNQZQXQQ

? Choose an IdP: arn:aws:iam::123456789012:saml-provider/My_IdP
? Choose a Role: arn:aws:iam::456789012345:role/My_Role

export AWS_ACCESS_KEY_ID=ASIAUJHVCS6UQC52NOL7
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5T...

$ export AWS_ACCESS_KEY_ID=ASIAUJHVCS6UQC52NOL7
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ export AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5T...
$ aws s3 ls
2018-04-04 11:56:00 test-bucket
2021-06-10 12:47:11 mah-bucket
```

--------------------------------

### Okta AWS CLI Web Command without OIDC Client Grant

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Example command-line usage of `okta-aws-cli web` when the OIDC client lacks the `okta.users.read.self` grant, requiring the additional `aws-acct-fed-app-id`.

```shell
$ okta-aws-cli web --org-domain my-org.okta.com \
    --oidc-client-id 0oa5wyqjk6Wm148fE1d7 \
    --aws-acct-fed-app-id 0oa9x1rifa2H6Q5d8325
```

--------------------------------

### Configure AWS CLI Credential Process

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Explains how to configure the AWS CLI `credential_process` to use `okta-aws-cli` for dynamic credential retrieval. It provides examples for both machine-to-machine (M2M) and web-based authentication flows, showing how to embed `okta-aws-cli` commands directly into the `~/.aws/config` file.

```text
credential_process = okta-aws-cli m2m --format process-credentials --oidc-client-id 0oabc --org-domain my-org.okta.com
```

```text
credential_process = okta-aws-cli web --format process-credentials --oidc-client-id 0oabc --org-domain my-org.okta.com --aws-iam-idp arn:aws:iam::123:saml-provider/my-idp --aws-iam-role arn:aws:iam::294719231913:role/s3 --open-browser
```

--------------------------------

### Debug okta.yaml Configuration File

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This snippet demonstrates how to use the 'debug' option of okta-aws-cli to validate the 'okta.yaml' configuration file. It checks for readability, valid YAML format, and correct section structure (awscli, idps, roles). An example 'okta.yaml' template is provided for reference.

```shell
$ okta-aws-cli debug

Given this YAML as an example template of okta.yaml for reference:

---
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::123456789012:role/admin": "Prod Admin"
    "arn:aws:iam::123456789012:role/operator": "Prod Ops"
    "arn:aws:iam::012345678901:role/admin": "Dev Admin"
    "arn:aws:iam::012345678901:role/operator": "Dev Ops"

found home directory "/Users/person"
okta.yaml is readable "/Users/person/.okta/okta.yaml"
okta.yaml is valid yaml
okta.yaml has root "awscli" section
okta.yaml "awscli.idps" section is a map of 2 ARN string keys to friendly string label values
okta.yaml "awscli.roles" section is a map of 4 ARN string keys to friendly string label values
okta.yaml is OK
debugging okta-aws-cli config $HOME/.okta/okta.yaml is complete
```

--------------------------------

### Scripted Usage of okta-aws-cli for AWS Credential Management

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

These examples illustrate how to integrate okta-aws-cli into scripts for automated credential management. Using 'eval' allows the output (environment variables) to be directly applied to the current shell. The '--exec' flag provides a convenient way to run an AWS command immediately after credential acquisition.

```shell
$ eval `okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com` && aws s3 ls
2018-04-04 11:56:00 test-bucket
2021-06-10 12:47:11 mah-bucket

$ eval `okta-aws-cli`

$ aws s3 ls
2018-04-04 11:56:00 test-bucket
2021-06-10 12:47:11 mah-bucket

$ okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com --exec -- aws s3 ls s3://example
                           PRE aaa/
2023-03-08 16:01:01          4 a.log
```

--------------------------------

### Retrieve AWS IAM Temporary Credentials via Okta Web Flow

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Demonstrates how to use the `okta-aws-cli web` command to obtain temporary AWS IAM credentials. The command initiates an Okta authentication flow and outputs the credentials as environment variables for use in subsequent AWS operations. Examples are provided for both Unix-like shells and Windows command prompt.

```shell
 # *nix, export statements
$ 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...
```

```powershell
rem Windows setx statements
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...
```

--------------------------------

### Execute Okta AWS CLI M2M Command with Environment Variables

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This example demonstrates how to run the `okta-aws-cli m2m` command. It assumes that required configuration parameters like `OKTA_AWSCLI_ORG_DOMAIN`, `OKTA_AWSCLI_OIDC_CLIENT_ID`, `OKTA_AWSCLI_IAM_ROLE`, `OKTA_AWSCLI_CUSTOM_SCOPE`, `OKTA_AWSCLI_KEY_ID`, `OKTA_AWSCLI_PRIVATE_KEY`, and `OKTA_AWSCLI_AUTHZ_ID` are set as environment variables. The command outputs temporary AWS credentials (Access Key ID, Secret Access Key, and Session Token) as environment variables.

```shell
# This example presumes its arguments are set as environment variables such as
# one may find in a headless CI environment.
# e.g.
# export OKTA_AWSCLI_ORG_DOMAIN="my-org.oka.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
export AWS_ACCESS_KEY_ID=ASIAUJHVCS6UQC52NOL7
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5T...
```

--------------------------------

### Display Okta AWS CLI Help

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Illustrates the command to display the comprehensive help documentation for the `okta-aws-cli` tool directly in the terminal. This is useful for understanding all available commands, options, and their usage.

```shell
okta-aws-cli --help
```

--------------------------------

### Clone and Set Up Local Repository for Okta AWS CLI

Source: https://github.com/okta/okta-aws-cli/blob/master/CONTRIBUTING.md

This sequence of Git commands initializes your local development environment. It clones your forked repository, navigates into the directory, adds the original Okta repository as an 'upstream' remote, checks out the master branch, fetches the latest changes from upstream, and then rebases your local master branch to synchronize with the upstream's master.

```bash
$ git clone https://github.com/YOUR_ACCOUNT/okta-aws-cli.git
$ cd okta-aws-cli
$ git remote add upstream https://github.com/okta/okta-aws-cli.git
$ git checkout master
$ git fetch upstream
$ git rebase upstream/master
```

--------------------------------

### Generate AWS Credentials File and List S3 Buckets

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Demonstrates how to use `okta-aws-cli` to obtain AWS credentials and write them to the `~/.aws/credentials` file, then verifies by listing S3 buckets using the `aws` CLI. It includes interactive prompts for IdP and Role selection.

```shell
$ okta-aws-cli web --oidc-client-id 0oabc --org-domain my-org.okta.com --profile test --format aws-credentials && \
  aws --profile test s3 ls

Open the following URL to begin Okta device authorization for the AWS CLI.

https://test-org.okta.com/activate?user_code=ZNQZQXQQ

? Choose an IdP: arn:aws:iam::123456789012:saml-provider/My_IdP
? Choose a Role: arn:aws:iam::456789012345:role/My_Role
Wrote profile "test" to /Users/mikemondragon/.aws/credentials

2018-04-04 11:56:00 test-bucket
2021-06-10 12:47:11 mah-bucket
```

--------------------------------

### Okta AWS CLI IdP and Role Selection After Friendly Labels

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Shows the improved display of IdP and Role selection options in the Okta AWS CLI after applying friendly labels defined in the `okta.yaml` file, making the choices more intuitive.

```Console Output
? Choose an IdP:  [Use arrows to move, type to filter]
> Data Production
  Data Development
  Marketing Production
  Marketing Development

? Choose a Role:  [Use arrows to move, type to filter]
> Admin
  Ops
```

--------------------------------

### Okta AWS Federation App Configuration Wizard URL Template

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This API documentation provides a template for constructing the URL to the Okta wizard, which assists in configuring SAML 2.0 for Amazon Web Services. It includes automatic generation of SAML certificates and settings for the Okta AWS Federation app. The template requires replacing placeholders for the Okta Admin Domain and the Okta AWS Federation app Client ID.

```APIDOC
URL Template:
https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Amazon-Web-Service.html?baseAdminUrl=https://[ADMIN_DOMAIN]&app=amazon_aws&instanceId=[CLIENT_ID]

Parameters:
- [ADMIN_DOMAIN]: Your Okta organization's admin domain.
  Example: myorg-admin.okta.com
- [CLIENT_ID]: The Client ID of your Okta AWS Federation application.
  Example: 0oa555555aaaaaaZZZZZ
```

--------------------------------

### okta-aws-cli Command Reference

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

A comprehensive list of available commands for `okta-aws-cli`, detailing their purpose and usage. This includes commands for human-oriented, machine-to-machine, and direct authentication flows, as well as utility commands for profile management and debugging.

```APIDOC
Commands:
  (empty):
    Description: When executed without a subcommand AND without arguments okta-aws-cli will print the online help and exit. With arguments it defaults to the web command.
  web:
    Description: Human oriented retrieval of temporary IAM credentials through Okta authentication and device authorization.
  m2m:
    Description: Machine/headless oriented retrieval of temporary IAM credentials through Okta authentication with a private key. IMPORTANT! This a not a feature intended for a human use case. Be sure to use industry state of the art secrets management techniques with the private key.
  direct:
    Description: Human or machine/headless oriented retrieval of temporary IAM credentials through out-of-bounds MFA Direct Authentication.
  list-profiles:
    Description: Lists profile names in ~/.okta/okta.yaml.
  debug:
    Description: Debug okta.yaml config file and exit.
```

--------------------------------

### List Configured Okta AWS CLI Profiles

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This command is used to display a human-readable list of all profiles configured in the `~/.okta/okta.yaml` file. It provides a quick overview of available authentication profiles for the `okta-aws-cli` tool.

```shell
$ okta-aws-cli list-profiles
```

--------------------------------

### Create Feature Branch and Commit Changes

Source: https://github.com/okta/okta-aws-cli/blob/master/CONTRIBUTING.md

These Git commands demonstrate the process of creating a new feature branch for your contributions, making modifications, staging the changed files, and committing them with a descriptive, signed commit message. The `-b` flag is used to create a new branch, and `-S` ensures the commit is signed.

```bash
$ git checkout master
$ git checkout -b feature_x
   (make your changes)
$ git status
$ git add <files>
$ git commit -S -m "descriptive commit message for your changes"
```

--------------------------------

### Okta AWS CLI Web Command Configuration Settings

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Outlines optional settings for the `web` command, including Okta AWS Account Federation app ID, AWS IAM Identity Provider ARN, QR code display, automatic browser opening, and profile gathering.

```APIDOC
Property: Okta AWS Account Federation integration app ID
  Description: See AWS Account Federation integration app. This value is only required if the CLI is not running for multiple AWS environments
  Command Line Flag: --aws-acct-fed-app-id [value]
  Environment Variable: OKTA_AWSCLI_AWS_ACCOUNT_FEDERATION_APP_ID

Property: AWS IAM Identity Provider ARN
  Description: Preselects the IdP list to this preferred IAM Identity Provider. If there are other IdPs available they will not be listed.
  Command Line Flag: --aws-iam-idp [value]
  Environment Variable: OKTA_AWSCLI_IAM_IDP

Property: Display QR Code
  Description: true if flag is present
  Command Line Flag: --qr-code
  Environment Variable: OKTA_AWSCLI_QR_CODE=true

Property: Automatically open the activation URL with the system web browser
  Description: true if flag is present
  Command Line Flag: --open-browser
  Environment Variable: OKTA_AWSCLI_OPEN_BROWSER=true

Property: Automatically open the activation URL with the given web browser command
  Description: Shell escaped browser command
  Command Line Flag: --open-browser-command [command]
  Environment Variable: OKTA_AWSCLI_OPEN_BROWSER_COMMAND

Property: Gather all profiles for all IdPs and Roles associated with an AWS Fed App
  Description: (implies aws-credentials file output format) true if flag is present
  Command Line Flag: --all-profiles
  Environment Variable: OKTA_AWSCLI_OPEN_BROWSER=true
```

--------------------------------

### Configure Friendly Labels for Okta AWS CLI IdPs and Roles in YAML

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Demonstrates how to create an `okta.yaml` configuration file to define friendly alias labels for AWS IAM IdP and Role ARNs. This improves readability in the Okta AWS CLI selection menus and supports regular expressions for role matching.

```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"
    "arn:aws:iam::901234567890:saml-provider/company-okta-idp": "Marketing Production"
    "arn:aws:iam::890123456789:saml-provider/company-okta-idp": "Marketing Development"
  roles:
    "arn:aws:iam::.*:role/admin": "Admin"
    "arn:aws:iam::.*:role/operator": "Ops"
```

--------------------------------

### Execute Okta AWS CLI Direct Command with User Input

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This snippet demonstrates how to use the `direct` command of `okta-aws-cli`. It highlights methods for securely prompting for username and password using shell commands (specifically zsh style), which can also be provided directly via CLI flags for headless operations. Note that this command is specifically for Okta OIDC apps, not Okta AWS Federation apps.

```shell
# use the shell to read in username/password, both can be set directly as CLI
# flags for the headless use case

# zsh style
# read "myusername?Okta Username: " && read -s "mypassword?Okta Password: " && echo
```

--------------------------------

### Push Local Branches to Origin for Pull Request

Source: https://github.com/okta/okta-aws-cli/blob/master/CONTRIBUTING.md

These Git commands are used to push your local master and feature branches to your forked repository on GitHub (typically referred to as 'origin'). This action makes your changes visible on GitHub, which is a prerequisite for initiating a pull request to contribute your changes to the main project.

```bash
$ git push origin master
$ git push origin feature_x
```

--------------------------------

### Okta AWS CLI IdP and Role Selection Before Friendly Labels

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Illustrates the default display of IdP and Role selection options in the Okta AWS CLI, showing raw ARN values which can be difficult to read when many options are present.

```Console Output
? Choose an IdP:  [Use arrows to move, type to filter]
> Fed App 1 Label
  Fed App 2 Label
  Fed App 3 Label
  Fed App 4 Label

? Choose a Role:  [Use arrows to move, type to filter]
> arn:aws:iam::123456789012:role/admin
  arn:aws:iam::123456789012:role/ops
```

--------------------------------

### Okta AWS CLI Operational Debugging and Execution Flags

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Details various command-line flags and corresponding environment variables for debugging, API call logging, proxy settings, command execution, and user agent configuration in the Okta AWS CLI.

```APIDOC
Property: debug
  Description: Print operational information to the screen for debugging purposes
  Value: true if flag is present
  Command Line Flag: --debug
  Environment Variable: OKTA_AWSCLI_DEBUG=true

Property: debug-api-calls
  Description: Verbosely print all API calls/responses to the screen
  Value: true if flag is present
  Command Line Flag: --debug-api-calls
  Environment Variable: OKTA_AWSCLI_DEBUG_API_CALLS=true

Property: http-https-proxy
  Description: HTTP/HTTPS Proxy support (based on golang net/http/httpproxy package)
  Value: HTTP/HTTPS URL of proxy service
  Command Line Flag: n/a
  Environment Variable: HTTP_PROXY or HTTPS_PROXY

Property: exec
  Description: Execute arguments after CLI arg terminator -- as a separate process. Process will be executed with AWS cred values as AWS env vars AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN.
  Value: true if flag is present
  Command Line Flag: --exec
  Environment Variable: OKTA_AWSCLI_EXEC=true

Property: short-user-agent
  Description: Short user agent. HTTP requests made to the Okta API have user-agent set to okta-aws-cli allowing for a simple UA value in a policy rule.
  Value: true if flag is present
  Command Line Flag: --short-user-agent
  Environment Variable: OKTA_AWSCLI_SHORT_USER_AGENT=true
```

--------------------------------

### Direct Authentication Command Line and Environment Variable Settings for Okta AWS CLI

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Outlines the configuration parameters for direct user authentication with the Okta AWS CLI. These settings, including Username, Password, Authorization Server ID, and Custom STS Role Session Name, can be provided via command-line flags or environment variables.

```APIDOC
Direct Command Settings:
  Username:
    Description: The username of the operator
    Required: true
    Command Line Flag: --username [value]
    Environment Variable: OKTA_AWSCLI_USERNAME
  Password:
    Description: The password of the operator
    Required: true
    Command Line Flag: --password [value]
    Environment Variable: OKTA_AWSCLI_PASSWORD
  Authorization Server ID:
    Description: The ID of the Okta authorization server, set ID for a custom authorization server, will use default otherwise. Default `default`
    Required: false
    Command Line Flag: --authz-id [value]
    Environment Variable: OKTA_AWSCLI_AUTHZ_ID
  Custom STS Role Session Name:
    Description: Customize STS Role Session Name. Default `okta-aws-cli`
    Required: false
    Command Line Flag: --aws-sts-role-session-name [value]
    Environment Variable: OKTA_AWSCLI_STS_ROLE_SESSION_NAME
```

--------------------------------

### Execute Okta AWS CLI Web Command and Export Credentials

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This snippet demonstrates how to run the `okta-aws-cli web` command, specifying the OIDC client ID, AWS account federation app ID, and Okta organization domain. It then shows the resulting AWS temporary credentials (Access Key ID, Secret Access Key, and Session Token) exported as environment variables, which are typically used by the AWS CLI.

```shell
$ 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...
```

--------------------------------

### Rebase Feature Branch with Upstream Master

Source: https://github.com/okta/okta-aws-cli/blob/master/CONTRIBUTING.md

This set of Git commands is crucial for keeping your feature branch up-to-date with the latest changes from the upstream repository. It involves checking out your local master branch, fetching and rebasing it with the upstream master, then switching back to your feature branch and rebasing it onto your updated local master.

```bash
$ git checkout master
$ git fetch upstream
$ git rebase upstream/master
$ git checkout feature_x
$ git rebase master
```

--------------------------------

### M2M Command Line and Environment Variable Settings for Okta AWS CLI

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Documents the required and optional configuration parameters for machine-to-machine (M2M) authentication with the Okta AWS CLI. Parameters can be set via command-line flags or environment variables, including Key ID, Private Key, Authorization Server ID, Custom Scope, and STS Role Session Name.

```APIDOC
M2M Command Settings:
  Key ID (kid):
    Description: The ID of the key stored in the service app
    Required: true
    Command Line Flag: --key-id [value]
    Environment Variable: OKTA_AWSCLI_KEY_ID
  Private Key:
    Description: PEM (pkcs#1 or pkcs#9) private key whose public key is stored on the service app
    Required: true (in lieu of private key file)
    Command Line Flag: --private-key [value]
    Environment Variable: OKTA_AWSCLI_PRIVATE_KEY
  Private Key File:
    Description: File holding PEM (pkcs#1 or pkcs#9) private key whose public key is stored on the service app
    Required: true (in lieu of private key)
    Command Line Flag: --private-key-file [value]
    Environment Variable: OKTA_AWSCLI_PRIVATE_KEY_FILE
  Authorization Server ID:
    Description: The ID of the Okta authorization server, set ID for a custom authorization server, will use default otherwise. Default `default`
    Required: false
    Command Line Flag: --authz-id [value]
    Environment Variable: OKTA_AWSCLI_AUTHZ_ID
  Custom scope name:
    Description: The custom scope established in the custom authorization server. Default `okta-m2m-access`
    Required: false
    Command Line Flag: --custom-scope [value]
    Environment Variable: OKTA_AWSCLI_CUSTOM_SCOPE
  Custom STS Role Session Name:
    Description: Customize STS Role Session Name. Default `okta-aws-cli`
    Required: false
    Command Line Flag: --aws-sts-role-session-name [value]
    Environment Variable: OKTA_AWSCLI_STS_ROLE_SESSION_NAME
```

--------------------------------

### Securely Prompt for Okta Username and Password in Bash

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

This snippet demonstrates how to securely prompt a user for their Okta username and password using `read` commands in a bash shell. The username is displayed, while the password input is hidden for security.

```bash
$ read -p "Okta Username: " myusername && read -s -p "Okta Password: " mypassword && echo
```

--------------------------------

### Collect All AWS Roles from Okta Federation Apps

Source: https://github.com/okta/okta-aws-cli/blob/master/README.md

Illustrates how to use `okta-aws-cli` to automatically discover and write credentials for all available AWS IAM roles across multiple Okta AWS Federation applications to the `~/.aws/credentials` file. This streamlines access to various AWS accounts and roles.

```shell
# Two Okta "AWS Account Federation" apps, one on AWS alias "prod-org", the other
# on alias "dev-org". Includes short name for the actual IAM IdPs and IAM Roles
# on the Fed App.

$ okta-aws-cli web \
    --org-domain my-org.okta.com \
    --oidc-client-id 0oa5wyqjk6Wm148fE1d7 \
    --write-aws-credentials \
    --all-profiles

? Choose an IdP: AWS Account Federation
Updated profile "dev-org-s3ops-read" in credentials file "/Users/me/.aws/credentials".
Updated profile "dev-org-s3ops-write" in credentials file "/Users/me/.aws/credentials".
Updated profile "prod-org-containerops-ec2-full" in credentials file "/Users/me/.aws/credentials".
Updated profile "prod-org-containerops-eks-full" in credentials file "/Users/me/.aws/credentials".
```