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.
  • 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


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:
To see the specific interaction with Headless mode, click the links in the aforementioned list.


saml-to assume [role]
Assume a role
--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]



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


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_SESSION_TOKEN="IQoJb...=="
Last modified 26d ago