assume

saml-to assume

The assume command is the primary command that can be used to open a Web Browser to start the SAML authentication process for role assumption

If no arguments are provided, it will prompt for available roles to assume.

The list-roles command will also show available Service Providers for login.

Examples:

• saml-to assume

  • Interactively display and allow selection of a Service Provider and roles for which to assume.

  • Then opens a browser window and begins the SAML authentication process.

• saml-to assume arn:aws:iam::874599868815:role/iam-readonly

  • Opens a browser window and begins the SAML authentication process.

  • No interactive prompts and requires an exact match of a provider name.

Suffix Matching

As an added convenience, the suffix of a role can be provided instead of the full role name, if it is distinct.

For example:

List Roles:

➜  ~ saml-to list-roles
npx: installed 1 in 3.244s
┌─────────┬───────────────────────────────────────────────┬───────────┬───────────────────────┐
│ (index) │                     role                      │ provider  │          org          │
├─────────┼───────────────────────────────────────────────┼───────────┼───────────────────────┤
│    0    │    'arn:aws:iam::874599868815:role/admin'     │ 'aws-iam' │ 'stark-international' │
│    1    │ 'arn:aws:iam::874599868815:role/iam-readonly' │ 'aws-iam' │ 'stark-international' │
└─────────┴───────────────────────────────────────────────┴───────────┴───────────────────────┘

These commands are all functionally equivalent:

➜  ~ saml-to assume readonly
➜  ~ saml-to assume iam-readonly
➜  ~ saml-to assume role/iam-readonly
...
➜  ~ saml-to assume arn:aws:iam::874599868815:role/iam-readonly

Headless

For some providers that have a SDK that allows for Token Generation on the command line, the saml-to cli is also featured to output access credentials to the command line for headless interaction.

The following providers support Headless mode:

• AWS Federated Identity (Entity ID: https://signin.aws.amazon.com/saml)

To see the specific interaction with Headless mode, click the links in the aforementioned list.

Usage

saml-to assume [role]

Assume a role

Options:
  --help      Show help  [boolean]
  --version   Show version number  [boolean]
  --role      The role to assume  [string]
  --org       Specify an organization  [string]
  --headless  Output access credentials to the terminal  [boolean] [default: false]
  --save      Similar to headless, but saves the CLI configuration for a provider to the config file  [string]
  --provider  Specify the provider  [string]

Options

--org

In the event you're a member of multiple organizations, with providers of the same name, you can seed the command with a specific organization with this flag.

E.g. npx saml-to login aws --org stark-international

--headless

No prompts, and output vary based on the provider. See Headless above.

Example Output

Following these commands, a browser window would be opened to begin the SAML Authentication flow.

➜  ~ npx saml-to assume
npx: installed 1 in 3.035s
? Which role would you like to assume? (Use arrow keys)
  arn:aws:iam::874599868815:role/admin [aws-iam] (stark-international)
❯ arn:aws:iam::874599868815:role/iam-readonly [aws-iam] (stark-international)
Assuming arn:aws:iam::874599868815:role/iam-readonly
➜  ~ 

➜  ~ npx saml-to assume admin
npx: installed 1 in 1.592s
Assuming admin
➜  ~ 

➜  ~ npx -q saml-to assume readonly --headless
export AWS_ACCESS_KEY_ID="ASIA...AS"
export AWS_SECRET_ACCESS_KEY="X6Vo...AU"
export AWS_SESSION_TOKEN="IQoJb...=="