DOCSEARCHbyAlgolia
Submit Docs

saml2aws

repository·master·Indexed 24 days ago

https://github.com/versent/saml2aws

A CLI tool that automates logging into an Identity Provider (IdP) via SAML 2.0 to retrieve temporary AWS credentials for use with the AWS CLI. It supports multiple providers including Azure AD, JumpCloud, Akamai EAA, Auth0, F5 Access Policy Manager (F5APM), Google Apps, NetIQ, and Okta, with various MFA scenario support depending on the provider.

Tokens
13.9K
Snippets
25
Records
92
Agent score
78%

What's inside saml2aws

  1. Overview of saml2aws

    master

    saml2aws is a CLI tool that enables you to log in to an Identity Provider (IdP) and retrieve temporary AWS credentials. It supports various IdPs including ADFS, AzureAD, PingFederate, Okta, KeyCloak, Google Apps, Shibboleth, F5APM, Akamai, OneLogin, NetIQ, Auth0, and JumpCloud.

    The workflow follows these steps:

    1. Setup an account alias.
    2. Prompt user for credentials.
    3. Log in to the Identity Provider using form-based authentication (utilizing playwright-go to run a sandbox chromium window).
    4. Build a SAML assertion containing AWS roles.
    5. Optionally cache the SAML assertion (unencrypted).
    6. Exchange the role and SAML assertion with the AWS STS service to get temporary credentials.
    7. Save these credentials to an AWS profile named saml.

  2. F5 Access Policy Manager Provider features

    master

    The F5APM provider includes the following automated capabilities:

    • Automatic detection of MFA: The provider can detect if Multi-Factor Authentication is required.
    • Automatic detection of MFA options: The provider can automatically identify available MFA methods, such as push notifications or tokens.

  4. Enable SigV4A support for temporary credentials

    master
    By default, the temporary security credentials returned by saml2aws do not support SigV4A. To enable SigV4A support, you must set the AWS_STS_REGIONAL_ENDPOINTS environment variable to regional when calling saml2aws. This ensures the aws-sdk-go uses a regional STS endpoint instead of the global one.

  5. Cache SAML assertions for immediate reuse

    master

    To avoid repeated MFA prompts when authenticating to multiple roles, use the --cache-saml flag. This caches the SAML assertion for a short validity period (approximately 5 minutes).

    • You can use the flag during login or list-roles commands.
    • You can set it permanently during configure.
    • The cache is stored in a directory named saml2aws within your .aws directory in your user home directory.

  7. Manage Duo MFA with the Shibboleth provider

    master

    The Shibboleth provider supports Duo Multi-Factor Authentication (MFA) with the following behaviors:

    • Auto Mode: When mfa is set to Auto, the provider prompts for Duo MFA. Supported Duo methods include Duo Push, Phone Call, and Passcode.
    • Bypass: 2-factor authentication is automatically skipped if the request is invoked from a Duo MFA authorized network.
    • Disable MFA: To disable MFA entirely, set the mfa option to None instead of Auto.

  8. Configure MFA options for NetIQ provider

    master

    The NetIQ provider supports two Multi-Factor Authentication (MFA) modes:

    1. Auto: The default mode for NetIQ. It follows the standard MFA flow.
    2. Privileged: Used for privileged account authentication. This mode skips MFA on the server side by using a different login URL on the client side.

  9. Manage Okta sessions and MFA behavior

    master

    Okta sessions allow saml2aws to store the Okta session locally (using the system keychain) to save your device for MFA. This is enabled by default.

    Important: If you use --disable-keychain, Okta sessions will also be disabled.

    Configuration Options:

    • Disable remembering device: Use --disable-remember-device during login or configure.
    • Disable Okta sessions: Use --disable-sessions during login or configure. This also disables the Okta MFA remember device feature.
    • Force role selection: Use the --force flag during the login command to manually prompt for an AWS role selection.

  11. Configure saml2aws for Azure Active Directory

    master

    Use the saml2aws configure command to set up your Azure AD profile. This command creates or modifies the ${HOME}/.saml2aws configuration file.

    Required/Common flags for Azure AD:

    • --idp-provider='AzureAD': Specifies the identity provider.
    • --url='https://account.activedirectory.windowsazure.com': The Azure AD endpoint.
    • --app-id: The Enterprise App Id acquired from the Azure portal.
    • --username: Your Azure AD username.
    • --profile: The name of the profile to create/use.
    • --mfa: Set to 'Auto' to handle MFA automatically.
    • --skip-prompt: Skips the interactive prompt for configuration details.
    saml2aws configure \
  --idp-provider='AzureAD' \
  --mfa='Auto' \
  --profile='saml' \
  --url='https://account.activedirectory.windowsazure.com' \
  --username='road.runner@the-acme-corporation.com' \
  --app-id='2784b9b1-53ed-4883-95a8-56bf94ad4f5f' \
  --skip-prompt

  12. Configure IDP accounts with `saml2aws configure`

    master

    Use the configure command to set up Identity Provider (IDP) accounts. This allows you to have multiple named accounts with different settings. If you do not specify an account name, it will be saved as default and used when the --idp-account flag is omitted during login.

    To configure a default account, run the command and follow the interactive prompts. To configure a named account without interactive prompts, use the -a or --idp-account flag along with other configuration flags.