{"id":13596139,"url":"https://github.com/Versent/saml2aws","last_synced_at":"2025-04-09T16:31:36.688Z","repository":{"id":37412711,"uuid":"67908757","full_name":"Versent/saml2aws","owner":"Versent","description":"CLI tool which enables you to login and retrieve AWS temporary credentials using a SAML IDP","archived":false,"fork":false,"pushed_at":"2025-03-31T20:27:08.000Z","size":10741,"stargazers_count":2124,"open_issues_count":242,"forks_count":574,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-04-08T23:05:44.819Z","etag":null,"topics":["adfs","aws","linux","macos","macosx","osx","saml","windows"],"latest_commit_sha":null,"homepage":"https://github.com/Versent/saml2aws","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Versent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-11T03:53:15.000Z","updated_at":"2025-04-04T12:09:36.000Z","dependencies_parsed_at":"2023-10-12T06:39:02.531Z","dependency_job_id":"c8546422-ae45-4264-b994-5779adbe4a48","html_url":"https://github.com/Versent/saml2aws","commit_stats":{"total_commits":971,"total_committers":240,"mean_commits":4.045833333333333,"dds":0.8516992790937178,"last_synced_commit":"07a7eb066b98a405fdb1b99a8297090042cdb07d"},"previous_names":[],"tags_count":91,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsaml2aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsaml2aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsaml2aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Fsaml2aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Versent","download_url":"https://codeload.github.com/Versent/saml2aws/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248067775,"owners_count":21042354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adfs","aws","linux","macos","macosx","osx","saml","windows"],"created_at":"2024-08-01T16:02:09.655Z","updated_at":"2025-04-09T16:31:36.680Z","avatar_url":"https://github.com/Versent.png","language":"Go","readme":"# saml2aws\n\n[![GitHub Actions status](https://github.com/Versent/saml2aws/workflows/Go/badge.svg?branch=master)](https://github.com/Versent/saml2aws/actions?query=workflow%3AGo) [![Build status - Windows](https://ci.appveyor.com/api/projects/status/ptpi18kci16o4i82/branch/master?svg=true)](https://ci.appveyor.com/project/davidobrien1985/saml2aws/branch/master)\n[![codecov](https://codecov.io/gh/Versent/saml2aws/branch/master/graph/badge.svg)](https://codecov.io/gh/Versent/saml2aws)\n\nCLI tool which enables you to login and retrieve [AWS](https://aws.amazon.com/) temporary credentials using\nwith [ADFS](https://msdn.microsoft.com/en-us/library/bb897402.aspx) or [PingFederate](https://www.pingidentity.com/en/products/pingfederate.html) Identity Providers.\n\nThis is based on python code from [\nHow to Implement a General Solution for Federated API/CLI Access Using SAML 2.0](https://blogs.aws.amazon.com/security/post/TxU0AVUS9J00FP/How-to-Implement-a-General-Solution-for-Federated-API-CLI-Access-Using-SAML-2-0).\n\nThe process goes something like this:\n\n* Setup an account alias, either using the default or given a name\n* Prompt user for credentials\n* Log in to Identity Provider using form based authentication\n* Build a SAML assertion containing AWS roles\n* Optionally cache the SAML assertion (the cache is not encrypted)\n* Exchange the role and SAML assertion with [AWS STS service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) to get a temporary set of credentials\n* Save these credentials to an aws profile named \"saml\"\n\n## Table of Contents\n\n- [saml2aws](#saml2aws)\n  - [Table of Contents](#table-of-contents)\n  - [Requirements](#requirements)\n  - [Caveats](#caveats)\n  - [Install](#install)\n    - [macOS](#macOS)\n    - [Windows](#windows)\n    - [Linux](#linux)\n      - [Ubuntu](#ubuntu)\n      - [Other](#other)\n      - [Using Make](#using-make)\n      - [Arch Linux and its derivatives](#arch-linux-and-its-derivatives)\n      - [Void Linux](#void-linux)\n  - [Autocomplete](#autocomplete)\n    - [Bash](#bash)\n    - [Zsh](#zsh)\n  - [Dependency Setup](#dependency-setup)\n  - [Usage](#usage)\n    - [`saml2aws script`](#saml2aws-script)\n    - [`saml2aws exec`](#saml2aws-exec)\n    - [Configuring IDP Accounts](#configuring-idp-accounts)\n  - [Example](#example)\n  - [Advanced Configuration](#advanced-configuration)\n    - [Windows Subsystem Linux (WSL) Configuration](#windows-subsystem-linux-wsl-configuration)\n      - [Option 1: Disable Keychain](#option-1-disable-keychain)\n      - [Option 2: Configure Pass to be the default keyring](#option-2-configure-pass-to-be-the-default-keyring)\n    - [Configuring Multiple Accounts](#configuring-multiple-accounts)\n      - [Dev Account Setup](#dev-account-setup)\n      - [Test Account Setup](#test-account-setup)\n  - [Advanced Configuration (Multiple AWS account access but SAML authenticate against a single 'SSO' AWS account)](#advanced-configuration-multiple-aws-account-access-but-saml-authenticate-against-a-single-sso-aws-account)\n  - [Advanced Configuration - additional parameters](#advanced-configuration---additional-parameters)\n  - [Building](#building)\n    - [macOS](#macos)\n    - [Linux](#linux-1)\n  - [Environment vars](#environment-vars)\n- [Dependencies](#dependencies)\n- [Releasing](#releasing)\n- [Debugging Issues with IDPs](#debugging-issues-with-idps)\n- [Using saml2aws as credential process](#using-saml2aws-as-credential-process)\n- [Caching the saml2aws SAML assertion for immediate reuse](#caching-the-saml2aws-saml-assertion-for-immediate-reuse)\n- [Okta Sessions](#okta-sessions)\n- [License](#license)\n\n## Requirements\n\n* One of the supported Identity Providers\n  * ADFS (2.x or 3.x)\n  * [AzureAD](doc/provider/aad/README.md)\n  * PingFederate + PingId\n  * [Okta](pkg/provider/okta/README.md)\n  * KeyCloak + (TOTP)\n  * [Google Apps](pkg/provider/googleapps/README.md)\n  * [Shibboleth](pkg/provider/shibboleth/README.md)\n  * [F5APM](pkg/provider/f5apm/README.md)\n  * [Akamai](pkg/provider/akamai/README.md)\n  * OneLogin\n  * NetIQ\n  * Browser, this uses [playwright-go](github.com/playwright-community/playwright-go) to run a sandbox chromium window.\n  * [Auth0](pkg/provider/auth0/README.md) NOTE: Currently, MFA not supported\n  * [JumpCloud](doc/provider/jumpcloud/README.md)\n* AWS SAML Provider configured\n\n## Caveats\n\nAside from Okta, most of the providers in this project are using screen scraping to log users into SAML, this isn't ideal and hopefully vendors make this easier in the future. In addition to this there are some things you need to know:\n\n1. AWS defaults to session tokens being issued with a duration of up to 3600 seconds (1 hour), this can now be configured as per [Enable Federated API Access to your AWS Resources for up to 12 hours Using IAM Roles](https://aws.amazon.com/blogs/security/enable-federated-api-access-to-your-aws-resources-for-up-to-12-hours-using-iam-roles/) and `--session-duration` flag.\n2. Every SAML provider is different, the login process, MFA support is pluggable and therefore some work may be needed to integrate with your identity server\n3. By default, the temporary security credentials returned **do not support SigV4A**. If you need SigV4A support then you must set the `AWS_STS_REGIONAL_ENDPOINTS` enviornment variable to `regional` when calling `saml2aws` so that [aws-sdk-go](https://github.com/aws/aws-sdk-go) uses a regional STS endpoint instead of the global one. See the note at the bottom of [Signing AWS API requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html#signature-versions) and [AWS STS Regionalized endpoints](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sts-regionalized-endpoints.html).\n\n## Install\n\n### macOS\n\nIf you're on macOS you can install saml2aws using homebrew!\n\n```\nbrew install saml2aws\nsaml2aws --version\n```\n\n### Windows\n\nIf you're on Windows you can [install saml2aws using chocolatey](https://chocolatey.org/packages?q=saml2aws)!\n\n```\nchoco install saml2aws\nsaml2aws --version\n```\n\n### Linux\n\nWhile brew is available for Linux you can also run the following without using a package manager.\n\n#### Ubuntu\n\nSome users of Ubuntu have reported issue with the [Others](#others) Install instruction and reported the following to work (may required using sudo command like for the \"mv\" function)\n\n```\nCURRENT_VERSION=$(curl -Ls https://api.github.com/repos/Versent/saml2aws/releases/latest | grep 'tag_name' | cut -d'v' -f2 | cut -d'\"' -f1)\nwget https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz\ntar -xzvf saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz\nmv saml2aws /usr/local/bin/\nchmod u+x /usr/local/bin/saml2aws\nsaml2aws --version\n```\n\nFor U2F support, replace wget line above with `wget https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws-u2f_${CURRENT_VERSION}_linux_amd64.tar.gz`\n\n#### Other\n\n```\nmkdir -p ~/.local/bin\nCURRENT_VERSION=$(curl -Ls https://api.github.com/repos/Versent/saml2aws/releases/latest | grep 'tag_name' | cut -d'v' -f2 | cut -d'\"' -f1)\nwget -c \"https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws_${CURRENT_VERSION}_linux_amd64.tar.gz\" -O - | tar -xzv -C ~/.local/bin\nchmod u+x ~/.local/bin/saml2aws\nhash -r\nsaml2aws --version\n```\nIf `saml2aws --version` does not work as intended, you may need to update your terminal configuration file (like ~/.bashrc, ~/.profile, ~/.zshrc) to include `export PATH=\"$PATH:$HOME/.local/bin/\"` at the end of the file.\n\nFor U2F support, replace wget line above with `wget -c \"https://github.com/Versent/saml2aws/releases/download/v${CURRENT_VERSION}/saml2aws-u2f_${CURRENT_VERSION}_linux_amd64.tar.gz\" -O - | tar -xzv -C ~/.local/bin`\n\n#### Using Make\n\nYou will need [Go Tools](https://golang.org/doc/install) (you can check your package maintainer as well) installed and the [Go Lint tool](https://github.com/alecthomas/gometalinter)\n\nClone this repo to your `$GOPATH/src` directory\n\nNow you can install by running\n\n```\nmake\nmake install\n```\n\n#### [Arch Linux](https://archlinux.org/) and its derivatives\n\nThe `saml2aws` tool is available in AUR ([saml2aws-bin](https://aur.archlinux.org/packages/saml2aws-bin/)), so you can install it using an available AUR helper:\n\n* Manjaro: `$ pamac build saml2aws-bin`\n\n#### [Void Linux](https://voidlinux.org/)\n\nIf you are on Void Linux you can use xbps to install the saml2aws package!\n\n```\nxbps-install saml2aws\n```\n\n## Autocomplete\n\n`saml2aws` can generate completion scripts.\n\n### Bash\n\nAdd the following line to your `.bash_profile` (or equivalent):\n```bash\neval \"$(saml2aws --completion-script-bash)\"\n```\n\n### Zsh\n\nAdd the following line to your `.zshrc` (or equivalent):\n```bash\neval \"$(saml2aws --completion-script-zsh)\"\n```\n\n## Dependency Setup\n\nInstall the AWS CLI [see](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), in our case we are using [homebrew](http://brew.sh/) on macOS.\n\n```\nbrew install awscli\n```\n\n## Usage\n\n```\nusage: saml2aws [\u003cflags\u003e] \u003ccommand\u003e [\u003cargs\u003e ...]\n\nA command line tool to help with SAML access to the AWS token service.\n\nFlags:\n      --help                   Show context-sensitive help (also try --help-long and --help-man).\n      --version                Show application version.\n      --verbose                Enable verbose logging\n      --quiet                  silences logs\n  -i, --provider=PROVIDER      This flag is obsolete. See: https://github.com/Versent/saml2aws#configuring-idp-accounts\n      --config=CONFIG          Path/filename of saml2aws config file (env: SAML2AWS_CONFIGFILE)\n  -a, --idp-account=\"default\"  The name of the configured IDP account. (env: SAML2AWS_IDP_ACCOUNT)\n      --idp-provider=IDP-PROVIDER\n                               The configured IDP provider. (env: SAML2AWS_IDP_PROVIDER)\n      --mfa=MFA                The name of the mfa. (env: SAML2AWS_MFA)\n  -s, --skip-verify            Skip verification of server certificate. (env: SAML2AWS_SKIP_VERIFY)\n      --url=URL                The URL of the SAML IDP server used to login. (env: SAML2AWS_URL)\n      --username=USERNAME      The username used to login. (env: SAML2AWS_USERNAME)\n      --password=PASSWORD      The password used to login. (env: SAML2AWS_PASSWORD)\n      --mfa-token=MFA-TOKEN    The current MFA token (supported in Keycloak, ADFS, GoogleApps). (env: SAML2AWS_MFA_TOKEN)\n      --role=ROLE              The ARN of the role to assume. (env: SAML2AWS_ROLE)\n      --aws-urn=AWS-URN        The URN used by SAML when you login. (env: SAML2AWS_AWS_URN)\n      --skip-prompt            Skip prompting for parameters during login.\n      --session-duration=SESSION-DURATION\n                               The duration of your AWS Session. (env: SAML2AWS_SESSION_DURATION)\n      --disable-keychain       Do not use keychain at all. This will also disable Okta sessions \u0026 remembering MFA device. (env: SAML2AWS_DISABLE_KEYCHAIN)\n  -r, --region=REGION          AWS region to use for API requests, e.g. us-east-1, us-gov-west-1, cn-north-1 (env: SAML2AWS_REGION)\n      --prompter=PROMPTER      The prompter to use for user input (default, pinentry)\n\nCommands:\n  help [\u003ccommand\u003e...]\n    Show help.\n\n\n  configure [\u003cflags\u003e]\n    Configure a new IDP account.\n\n        --app-id=APP-ID            OneLogin app id required for SAML assertion. (env: ONELOGIN_APP_ID)\n        --client-id=CLIENT-ID      OneLogin client id, used to generate API access token. (env: ONELOGIN_CLIENT_ID)\n        --client-secret=CLIENT-SECRET\n                                   OneLogin client secret, used to generate API access token. (env: ONELOGIN_CLIENT_SECRET)\n        --subdomain=SUBDOMAIN      OneLogin subdomain of your company account. (env: ONELOGIN_SUBDOMAIN)\n        --mfa-ip-address=MFA-IP-ADDRESS\n                                   IP address whitelisting defined in OneLogin MFA policies. (env: ONELOGIN_MFA_IP_ADDRESS)\n    -p, --profile=PROFILE          The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)\n        --resource-id=RESOURCE-ID  F5APM SAML resource ID of your company account. (env: SAML2AWS_F5APM_RESOURCE_ID)\n        --credentials-file=CREDENTIALS-FILE\n                                   The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)\n        --cache-saml               Caches the SAML response (env: SAML2AWS_CACHE_SAML)\n        --cache-file=CACHE-FILE    The location of the SAML cache file (env: SAML2AWS_SAML_CACHE_FILE)\n        --disable-sessions         Do not use Okta sessions. Uses Okta sessions by default. (env: SAML2AWS_OKTA_DISABLE_SESSIONS)\n        --disable-remember-device  Do not remember Okta MFA device. Remembers MFA device by default. (env: SAML2AWS_OKTA_DISABLE_REMEMBER_DEVICE)\n\n  login [\u003cflags\u003e]\n    Login to a SAML 2.0 IDP and convert the SAML assertion to an STS token.\n\n    -p, --profile=PROFILE        The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)\n        --duo-mfa-option=DUO-MFA-OPTION\n                                 The MFA option you want to use to authenticate with (supported providers: okta). (env: SAML2AWS_DUO_MFA_OPTION)\n        --client-id=CLIENT-ID    OneLogin client id, used to generate API access token. (env: ONELOGIN_CLIENT_ID)\n        --client-secret=CLIENT-SECRET\n                                 OneLogin client secret, used to generate API access token. (env: ONELOGIN_CLIENT_SECRET)\n        --mfa-ip-address=MFA-IP-ADDRESS\n                                 IP address whitelisting defined in OneLogin MFA policies. (env: ONELOGIN_MFA_IP_ADDRESS)\n        --force                  Refresh credentials even if not expired.\n        --credential-process     Enables AWS Credential Process support by outputting credentials to STDOUT in a JSON message.\n        --credentials-file=CREDENTIALS-FILE\n                                 The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)\n        --cache-saml             Caches the SAML response (env: SAML2AWS_CACHE_SAML)\n        --cache-file=CACHE-FILE  The location of the SAML cache file (env: SAML2AWS_SAML_CACHE_FILE)\n        --download-browser-driver  Automatically download browsers for Browser IDP. (env: SAML2AWS_AUTO_BROWSER_DOWNLOAD)\n        --disable-sessions         Do not use Okta sessions. Uses Okta sessions by default. (env: SAML2AWS_OKTA_DISABLE_SESSIONS)\n        --disable-remember-device  Do not remember Okta MFA device. Remembers MFA device by default. (env: SAML2AWS_OKTA_DISABLE_REMEMBER_DEVICE)\n\n  exec [\u003cflags\u003e] [\u003ccommand\u003e...]\n    Exec the supplied command with env vars from STS token.\n\n    -p, --profile=PROFILE      The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)\n        --exec-profile=EXEC-PROFILE\n                               The AWS profile to utilize for command execution. Useful to allow the aws cli to perform secondary role assumption. (env: SAML2AWS_EXEC_PROFILE)\n        --credentials-file=CREDENTIALS-FILE\n                               The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)\n\n  console [\u003cflags\u003e]\n    Console will open the aws console after logging in.\n\n        --exec-profile=EXEC-PROFILE\n                               The AWS profile to utilize for console execution. (env: SAML2AWS_EXEC_PROFILE)\n    -p, --profile=PROFILE      The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)\n        --force                Refresh credentials even if not expired.\n        --link                 Present link to AWS console instead of opening browser\n        --credentials-file=CREDENTIALS-FILE\n                               The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)\n\n  list-roles\n    List available role ARNs.\n        --cache-saml             Caches the SAML response (env: SAML2AWS_CACHE_SAML)\n        --cache-file=CACHE-FILE  The location of the SAML cache file (env: SAML2AWS_SAML_CACHE_FILE)\n\n\n  script [\u003cflags\u003e]\n    Emit a script that will export environment variables.\n\n    -p, --profile=PROFILE      The AWS profile to save the temporary credentials. (env: SAML2AWS_PROFILE)\n        --credentials-file=CREDENTIALS-FILE\n                               The file that will cache the credentials retrieved from AWS. When not specified, will use the default AWS credentials file location. (env: SAML2AWS_CREDENTIALS_FILE)\n        --shell=bash           Type of shell environment. Options include: bash, /bin/sh, powershell, fish, env\n\n\n```\n\n\n### `saml2aws script`\n\nIf the `script` sub-command is called, `saml2aws` will output the following temporary security credentials:\n```\nexport AWS_ACCESS_KEY_ID=\"ASIAI....UOCA\"\nexport AWS_SECRET_ACCESS_KEY=\"DuH...G1d\"\nexport AWS_SESSION_TOKEN=\"AQ...1BQ==\"\nexport AWS_SECURITY_TOKEN=\"AQ...1BQ==\"\nexport AWS_CREDENTIAL_EXPIRATION=\"2016-09-04T38:27:00Z00:00\"\nSAML2AWS_PROFILE=saml\n```\n\nPowershell, sh and fish shells are supported as well.\nEnv is useful for all AWS SDK compatible tools that can source an env file. It is a powerful combo with docker and the `--env-file` parameter.\n\nIf you use `eval $(saml2aws script)` frequently, you may want to create a alias for it:\n\nzsh:\n```\nalias s2a=\"function(){eval $( $(command saml2aws) script --shell=bash --profile=$@);}\"\n```\n\nbash:\n```\nfunction s2a { eval $( $(which saml2aws) script --shell=bash --profile=$@); }\n```\n\nenv:\n```\ndocker run -ti --env-file \u003c(saml2aws script --shell=env) amazon/aws-cli s3 ls\n```\n\n### `saml2aws exec`\n\nIf the `exec` sub-command is called, `saml2aws` will execute the command given as an argument:\nBy default saml2aws will execute the command with temp credentials generated via `saml2aws login`.\n\nThe `--exec-profile` flag allows for a command to execute using an aws profile which may have chained\n\"assume role\" actions. (via 'source_profile' in ~/.aws/config)\n\n```\noptions:\n--exec-profile           Execute the given command utilizing a specific profile from your ~/.aws/config file\n```\n\n### Configuring IDP Accounts\n\nThis is the *new* way of adding IDP provider accounts, it enables you to have named accounts with whatever settings you like and supports having one *default* account which is used if you omit the account flag. This replaces the --provider flag and old configuration file in 1.x.\n\nTo add a default IdP account to saml2aws just run the following command and follow the prompts.\n\n```\n$ saml2aws configure\n? Please choose a provider: Ping\n? AWS Profile myaccount\n\n? URL https://example.com\n? Username me@example.com\n\n? Password\nNo password supplied\n\naccount {\n  URL: https://example.com\n  Username: me@example.com\n  Provider: Ping\n  MFA: Auto\n  SkipVerify: false\n  AmazonWebservicesURN: urn:amazon:webservices\n  SessionDuration: 3600\n  Profile: myaccount\n  Region: us-east-1\n}\n\nConfiguration saved for IDP account: default\n```\n\nThen to login using this account.\n\n```\nsaml2aws login\n```\n\nYou can also add named accounts, below is an example where I am setting up an account under the `wolfeidau` alias, again just follow the prompts.\n\n```\nsaml2aws configure -a wolfeidau\n```\n\nYou can also configure the account alias without prompts.\n\n```\nsaml2aws configure -a wolfeidau --idp-provider KeyCloak --username mark@wolfe.id.au -r cn-north-1  \\\n  --url https://keycloak.wolfe.id.au/auth/realms/master/protocol/saml/clients/amazon-aws --skip-prompt\n```\n\nThen your ready to use saml2aws.\n\n## Example\n\nLog into a service (without MFA).\n\n```\n$ saml2aws login\nUsing IDP Account default to access Ping https://id.example.com\nTo use saved password just hit enter.\nUsername [mark.wolfe@example.com]:\nPassword: ************\n\nAuthenticating as mark.wolfe@example.com ...\nSelected role: arn:aws:iam::123123123123:role/AWS-Admin-CloudOPSNonProd\nRequesting AWS credentials using SAML assertion\nSaving credentials\nLogged in as: arn:aws:sts::123123123123:assumed-role/AWS-Admin-CloudOPSNonProd/wolfeidau@example.com\n\nYour new access key pair has been stored in the AWS configuration\nNote that it will expire at 2016-09-19 15:59:49 +1000 AEST\nTo use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances).\n```\n\nLog into a service (with MFA).\n\n```\n$ saml2aws login\nUsing IDP Account default to access Ping https://id.example.com\nTo use saved password just hit enter.\nUsername [mark.wolfe@example.com]:\nPassword: ************\n\nAuthenticating as mark.wolfe@example.com ...\nEnter passcode: 123456\n\nSelected role: arn:aws:iam::123123123123:role/AWS-Admin-CloudOPSNonProd\nRequesting AWS credentials using SAML assertion\nSaving credentials\nLogged in as: arn:aws:sts::123123123123:assumed-role/AWS-Admin-CloudOPSNonProd/wolfeidau@example.com\n\nYour new access key pair has been stored in the AWS configuration\nNote that it will expire at 2016-09-19 15:59:49 +1000 AEST\nTo use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances --region us-east-1).\n```\n\n## Advanced Configuration\n### Windows Subsystem Linux (WSL) Configuration\nIf you are using WSL1 or WSL2, you might get the following error when attempting to save the credentials into the keychain\n\n```\n No such interface “org.freedesktop.DBus.Properties” on object at path /\n```\n\nThis happens because the preferred keyring back-end - uses the `gnome-keyring` by default - which requires X11 - and if you are not using Windows 11 with support for Linux GUI applications - this can be difficult without [configuring a X11 forward](https://stackoverflow.com/questions/61110603/how-to-set-up-working-x11-forwarding-on-wsl2).\n\nThere are 2 preferred approaches to workaround this issue:\n\n#### Option 1: Disable Keychain\nYou can apply the  `--disable-keychain` flag when using both the `configure` and `login` commands. Using this flag means that your credentials (such as your password to your IDP, or in the case of Okta the Okta Session Token) will not save to your keychain - and be skipped entierly. This means you will be required to enter your username and password each time you invoke the `login` command.\n\n#### Option 2: Configure Pass to be the default keyring\nThere are a few steps involved with this option - however this option will save your credentials (such as your password to your IDP, and session tokens etc) into the `pass`[https://www.passwordstore.org/] keyring. The `pass` keyring is the standard Unix password manager. This option was *heavily inspired* by a similar issue in [aws-vault](https://github.com/99designs/aws-vault/issues/683)\n\nTo configure pass to be the default keyring the following steps will need to be completed (assuming you are using Ubuntu 20.04 LTS):\n\n1. Install the pass backend and update gnupg, which encrypts passwords\n```bash\nsudo apt-get update \u0026\u0026 sudo apt-get install -y pass gnupg\n```\n\n2. Generate a key with gpg (gnupg) and take note of your public key\n```bash\ngpg --gen-key\n```\n\nThe output of the gpg command will output the something similar to the following:\n```\npublic and secret key created and signed.\n\npub   rsa3072 2021-04-22 [SC] [expires: 2023-04-22]\n      844E426A53A64C2A916CBD1F522014D5FDBF6E3D\nuid                      Meir Gabay \u003cwilly@wonka.com\u003e\nsub   rsa3072 2021-04-22 [E] [expires: 2023-04-22]\n```\n\n3.  Create a storage key in pass from the previously generated public (pub) key\n```bash\npass init \u003cGPG_PUBLIC_KEY\u003e\n```\nduring the `init` process you'll be requested to enter the passphrase provided in step 2\n\n4. Now, configure `saml2aws` to use the `pass` keyring. This can be done by setting the `SAML2AWS_KEYRING_BACKEND` environment variable to be `pass`. You'll need to also set the `GPG_TTY` to your current tty which means you can set the variable to `\"$( tty )\"`\n\nwhich means the following can be added into your profile\n```\nexport SAML2AWS_KEYRING_BACKEND=pass\nexport GPG_TTY=\"$( tty )\"\n```\n\n5. Profit! Now when you run login/configure commands - you'll be promoted once to enter your passphrase - and your credentials will be saved into your keyring!\n\n\n### Configuring Multiple Accounts\nConfiguring multiple accounts with custom role and profile in `~/.aws/config` with goal being isolation between infra code when deploying to these environments. This setup assumes you're using separate roles and probably AWS accounts for `dev` and `test` and is designed to help operations staff avoid accidentally deploying to the wrong AWS account in complex environments. Note that this method configures SAML authentication to each AWS account directly (in this case different AWS accounts). In the example below, separate authentication values are configured for AWS accounts 'profile=customer-dev/awsAccount=was 121234567890' and 'profile=customer-test/awsAccount=121234567891'\n#### Dev Account Setup\n\nTo setup the dev account run the following and enter URL, username and password, and assign a standard role to be automatically selected on login.\n\n```\nsaml2aws configure -a customer-dev --role=arn:aws:iam::121234567890:role/customer-admin-role -p customer-dev\n```\n\nThis will result in the following configuration in `~/.saml2aws`.\n\n```\n[customer-dev]\nurl                     = https://id.customer.cloud\nusername                = mark@wolfe.id.au\nprovider                = Ping\nmfa                     = Auto\nskip_verify             = false\ntimeout                 = 0\naws_urn                 = urn:amazon:webservices\naws_session_duration    = 28800\naws_profile             = customer-dev\nrole_arn                = arn:aws:iam::121234567890:role/customer-admin-role\nregion                  = us-east-1\n```\n\nTo use this you will need to export `AWS_DEFAULT_PROFILE=customer-dev` environment variable to target `dev`.\n\n#### Test Account Setup\n\nTo setup the test account run the following and enter URL, username and password.\n\n```\nsaml2aws configure -a customer-test --role=arn:aws:iam::121234567891:role/customer-admin-role -p customer-test\n```\n\nThis results in the following configuration in `~/.saml2aws`.\n\n```\n[customer-test]\nurl                     = https://id.customer.cloud\nusername                = mark@wolfe.id.au\nprovider                = Ping\nmfa                     = Auto\nskip_verify             = false\ntimeout                 = 0\naws_urn                 = urn:amazon:webservices\naws_session_duration    = 28800\naws_profile             = customer-test\nrole_arn                = arn:aws:iam::121234567891:role/customer-admin-role\nregion                  = us-east-1\n```\n\nTo use this you will need to export `AWS_DEFAULT_PROFILE=customer-test` environment variable to target `test`.\n\n### Playwright Browser Drivers for Browser IDP\n\nIf you are using the Browser Identity Provider, on first invocation of `saml2aws login` you need to remember to install\nthe browser drivers in order for playwright-go to work. Otherwise you will see the following error message:\n\n`Error authenticating to IDP.: please install the driver (vx.x.x) and browsers first: %!w(\u003cnil\u003e)`\n\nTo install the drivers, you can:\n* Pass `--download-browser-driver` to `saml2aws login`\n* Set in your shell environment `SAML2AWS_AUTO_BROWSER_DOWNLOAD=true`\n* Set `download_browser_driver = true` in your saml2aws config file, i.e. `~/.saml2aws`\n\n## Advanced Configuration (Multiple AWS account access but SAML authenticate against a single 'SSO' AWS account)\n\nExample:\n(Authenticate to my 'SSO' AWS account. With this setup, there is no need to authenticate again. We can now rely on IAM to assume role cross account)\n\n~/.aws/credentials: #(these are generated by `saml2aws login`. Sets up SAML authentication into my AWS 'SSO' account)\n```\n[saml]\naws_access_key_id        = AAAAAAAAAAAAAAAAB\naws_secret_access_key    = duqhdZPRjEdZPRjE=dZPRjEhKjfB\naws_session_token        = #REMOVED#\naws_security_token       = #REMOVED#\nx_principal_arn          = arn:aws:sts::000000000123:assumed-role/myInitialAccount\nx_security_token_expires = 2019-08-19T15:00:56-06:00\n```\n\n(Use AWS profiles to assume an aws role cross-account)\n(Note that the \"source_profile\" is set to SAML which is my SSO AWS account since it is already authenticated)\n\n~/.aws/config:\n```\n[profile roleIn2ndAwsAccount]\nsource_profile=saml\nrole_arn=arn:aws:iam::123456789012:role/OtherRoleInAnyFederatedAccount # Note the different account number here\nrole_session_name=myAccountName\n\n[profile extraRroleIn2ndAwsAccount]\n# this profile uses a _third_ level of role assumption\nsource_profile=roleIn2ndAwsAccount\nrole_arn=arn:aws:iam::123456789012:role/OtherRoleInAnyFederatedAccount\n```\n\nRunning saml2aws without --exec-profile flag:\n```\nsaml2aws exec aws sts get-caller-identity\n{\n    \"UserId\": \"AROAYAROAYAROAYOO:myInitialAccount\",\n    \"Account\": \"000000000123\",\n    \"Arn\": \"arn:aws:sts::000000000123:assumed-role/myInitialAccount\"  # This shows my 'SSO' account (SAML profile)\n}\n\n```\n\nRunning saml2aws with --exec-profile flag:\n\nWhen using '--exec-profile' I can assume-role into a different AWS account without re-authenticating. Note that it\ndoes not re-authenticate since we are already authenticated via the SSO account.\n\n```\nsaml2aws exec --exec-profile roleIn2ndAwsAccount aws sts get-caller-identity\n{\n    \"UserId\": \"YOOYOOYOOYOOYOOA:/myAccountName\",\n    \"Account\": \"123456789012\",\n    \"Arn\": \"arn:aws:sts::123456789012:assumed-role/myAccountName\"\n}\n```\n\nAs an example\n\n```\nsaml2aws login\n\naws s3 ls --profile saml\n\nAn error occurred (AccessDenied) when calling the ListBuckets operation: Access Denied\n# This is denied in this example because there are no S3 buckets in the 'SSO' AWS account\n\nsaml2aws exec --exec-profile roleIn2ndAwsAccount aws s3 ls  # Runs given CMD with environment configured from --exec-profile role\n\n# If we check env variables we see that our environment is configured with temporary credentials for our 'assumed role'\nenv | grep AWS\nAWS_SESSION_TTL=12h\nAWS_FEDERATION_TOKEN_TTL=12h\nAWS_ASSUME_ROLE_TTL=1h\nAWS_ACCESS_KEY_ID=AAAAAAAASORTENED\nAWS_SECRET_ACCESS_KEY=secretShortened+6jJ5SMqsM5CkYi3Gw7\nAWS_SESSION_TOKEN=ShortenedTokenXXX=\nAWS_SECURITY_TOKEN=ShortenedSecurityTokenXXX=\nAWS_CREDENTIAL_EXPIRATION=2016-09-04T38:27:00Z00:00\n\n# If we desire to execute multiple commands utilizing our assumed profile, we can obtain a new shell with Env variables configured for access\n\nsaml2aws exec --exec-profile roleIn2ndAwsAccount $SHELL  # Get a new shell with AWS env vars configured for 'assumed role' account access\n\n# We are now able to execute AWS cli commands with our assume role permissions\n\n# Note that we do not need a --profile flag because our environment variables were set up for this access when we obtained a new shell with the --exec-profile flag\n\naws s3 ls\n2019-07-30 01:32:59 264998d7606497040-sampleBucket\n\naws iam list-groups\n{\n    \"Groups\": [\n        {\n            \"Path\": \"/\",\n            \"GroupName\": \"MyGroup\",\n            \"GroupId\": \"AGAGTENTENTENGOCQFK\",\n            \"Arn\": \"arn:aws:iam::123456789012:group/MyGroup\",\n            \"CreateDate\": \"2019-05-13T16:12:19Z\"\n            ]\n        }\n}\n```\n## Advanced Configuration - additional parameters\nThere are few additional parameters allowing to customise saml2aws configuration.\nUse following parameters in `~/.saml2aws` file:\n- `http_attempts_count` - configures the number of attempts to send http requests in order to authorise with saml provider. Defaults to 1\n- `http_retry_delay` - configures the duration (in seconds) of timeout between attempts to send http requests to saml provider. Defaults to 1\n- `region` - configures which region endpoints to use, See [Audience](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_audience-restriction) and [partition](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)\n- `target_url` - look for a target endpoint other than signin.aws.amazon.com/saml. The Okta, Pingfed, Pingone and Shibboleth ECP providers need to either explicitly send or look for this URL in a response in order to obtain or identify an appropriate authentication response. This can be overridden here if you wish to authenticate for something other than AWS.\n\nExample: typical configuration with such parameters would look like follows:\n```\n[default]\nurl                     = https://id.customer.cloud\nusername                = user@versent.com.au\nprovider                = Ping\nmfa                     = Auto\nskip_verify             = false\ntimeout                 = 0\naws_urn                 = urn:amazon:webservices\naws_session_duration    = 28800\naws_profile             = customer-dev\nrole_arn                = arn:aws:iam::121234567890:role/customer-admin-role\nhttp_attempts_count     = 3\nhttp_retry_delay        = 1\nregion                  = us-east-1\n```\n\nFor KeyCloak, 2 more parameters are available to end a failed authentication process.\n - `kc_auth_error_element` - configures what HTTP element saml2aws looks for in authentication error responses. Defaults to \"span#input-error\" and looks for `\u003cspan id=input-error\u003exxx\u003c/span\u003e`. Goquery is used. \"span#id-name\" looks for `\u003cspan id=id-name\u003exxx\u003c/span\u003e`. \"span.class-name\" looks for `\u003cspan class=class-name\u003exxx\u003c/span\u003e`.\n - `kc_auth_error_message` - works with the `kc_auth_error_element` and configures what HTTP message saml2aws looks for in authentication error responses. Defaults to \"Invalid username or password.\" and looks for `\u003cxxx\u003eInvalid username or password.\u003c/xxx\u003e`. [Regular expressions](https://github.com/google/re2/wiki/Syntax) are accepted.\n\nExample: If your KeyCloak server returns the authentication error message \"Invalid username or password.\" in a different language in the `\u003cspan class=kc-feedback-text\u003exxx\u003c/span\u003e` element, these parameters would look like:\n```\n[default]\nurl                     = https://id.customer.cloud\nusername                = user@versent.com.au\nprovider                = KeyCloak\n...\nkc_auth_error_element   = span.kc-feedback-text\nkc_auth_error_message   = \"Ungültiger Benutzername oder Passwort.\"\n```\nIf your KeyCloak server returns a different error message depending on an authentication error type, use a pipe as a separator and add multiple messages to the `kc_auth_error_message`:\n```\n[default]\nurl                     = https://id.customer.cloud\nusername                = user@versent.com.au\nprovider                = KeyCloak\n...\nkc_auth_error_message   = \"Invalid username or password.|Account is disabled, contact your administrator.\"\n```\n\n## Building\n\n### macOS\n\nTo build this software on macOS, clone the repo to `$GOPATH/src/github.com/versent/saml2aws` and ensure you have `$GOPATH/bin` in your `$PATH`. You will also need [GoReleaser](https://github.com/goreleaser/goreleaser) installed.\n\n```\nmake mod\n```\n\nInstall the binary to `$GOPATH/bin`.\n\n```\nmake install\n```\n\nThen to test the software just run.\n\n```\nmake test\n```\n\nBefore raising a PR please run the linter.\n\n```\nmake lint-fix\n```\n\n### Linux\n\nTo build this software on Debian/Ubuntu, you need to install a build dependency:\n\n```\nsudo apt install libudev-dev\n```\n\nYou also need [GoReleaser](https://github.com/goreleaser/goreleaser) installed, and the binary (or a symlink) in `bin/goreleaser`.\n\n```\nln -s $(command -v goreleaser) bin/goreleaser\n```\n\nThen you can build:\n\n```\nmake build\n```\n\n## Environment vars\n\nThe exec sub command will export the following environment variables.\n\n* AWS_ACCESS_KEY_ID\n* AWS_SECRET_ACCESS_KEY\n* AWS_SESSION_TOKEN\n* AWS_SECURITY_TOKEN\n* EC2_SECURITY_TOKEN\n* AWS_PROFILE\n* AWS_DEFAULT_PROFILE\n* AWS_CREDENTIAL_EXPIRATION\n\nNote: That profile environment variables enable you to use `exec` with a script or command which requires an explicit profile.\n\n# Dependencies\n\nThis tool would not be possible without some great opensource libraries.\n\n* [goquery](https://github.com/PuerkitoBio/goquery) html querying\n* [etree](https://github.com/beevik/etree) xpath selector\n* [kingpin](https://github.com/alecthomas/kingpin) command line flags\n* [aws-sdk-go](https://github.com/aws/aws-sdk-go) AWS Go SDK\n* [go-ini](https://github.com/go-ini/ini) INI file parser\n* [go-ntlmssp](https://github.com/Azure/go-ntlmssp) NTLM/Negotiate authentication\n\n# Releasing\n\n1. Create a git tag locally with `git tag -as vX.X.X`\n2. Run build with `make build`\n3. Test the newly created binary nested in the `dist/` of the project root directory\n4. If testing pass, push the tag `git push origin vX.X.X`\n5. Make an announcement in \"Discussions\"\n\n# Debugging Issues with IDPs\n\nThere are two levels of debugging, first emits debug information and the URL / Method / Status line of requests.\n\n```\nsaml2aws login --verbose\n```\n\nThe second emits the content of requests and responses, this includes authentication related information so don't copy and paste it into chat or tickets!\n\n```\nDUMP_CONTENT=true saml2aws login --verbose\n```\n# Using saml2aws as credential process\n\n[Credential Process](https://github.com/awslabs/awsprocesscreds) is a convenient way of interfacing credential providers with the AWS Cli.\n\nYou can use `saml2aws` as a credential provider by simply configuring it and then adding a profile to the AWS configuration. `saml2aws` has a flag `--credential-process` generating an output with the right JSON format, as well as a flag `--quiet` that will block the logging from being displayed.\nThe AWS credential file (typically ~/.aws/credentials) has precedence over the credential_process provider. That means that if credentials are present in the file, the credential process will not trigger. To counter that you can override the aws credential location of `saml2aws` to another file using `--credential-file` or specifying it during `configure`.\n\nThe AWS credential file (typically ~/.aws/credentials) has precedence over the credential_process provider. That means that if credentials are present in the file, the credential process will not trigger.\n\nAn example of the aws configuration (`~/.aws/config`):\n\n```\n[profile mybucket]\nregion = us-west-1\ncredential_process = saml2aws login --credential-process --role \u003cROLE\u003e --profile mybucket\n```\n\nYou can add this manually or via the awscli, i.e.\n\n```\naws configure set credential_process \"saml2aws login --credential-process --role \u003cROLE\u003e --profile mybucket\"\n```\n\nWhen using the aws cli with the `mybucket` profile, the authentication process will be run and the aws will then be executed based on the returned credentials.\n\n# Caching the saml2aws SAML assertion for immediate reuse\n\nYou can use the flag `--cache-saml` in order to cache the SAML assertion at authentication time. The SAML assertion cache has a very short validity (5 min) and can be used to authenticate to several roles with a single MFA validation.\n\nthere is a file per saml2aws profile, the cache directory is called `saml2aws` and is located in your `.aws` directory in your user homedir.\n\nYou can toggle `--cache-saml` during `login` or during `list-roles`, and you can set it once during `configure` and use it implicitly.\n\n# Okta Sessions\n\nThis requires the use of the keychain (local credentials store). If you disabled the keychain using `--disable-keychain`, Okta sessions will also be disabled.\n\nOkta sessions are enabled by default. This will store the Okta session locally and save your device for MFA. This means that if the session has not yet expired, you will not be prompted for MFA.\n\n* To disable remembering the device, you can toggle `--disable-remember-device` during `login` or `configure` commands.\n* To disable using Okta sessions, you can toggle `--disable-sessions` during `login` or `configure` commands.\n  * This will also disable the Okta MFA remember device feature\n\nUse the `--force` flag during `login` command to prompt for AWS role selection.\n\nIf Okta sessions are disabled via any of the methods mentioned above, the login process will default to the standard authentication process (without using sessions).\n\nPlease note that your Okta session duration and MFA policies are governed by your Okta host organization.\n\n\n# License\n\nThis code is Copyright (c) 2024 [Versent](https://versent.com.au) and released under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.\n\n","funding_links":[],"categories":["Go","aws","Auth"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVersent%2Fsaml2aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVersent%2Fsaml2aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVersent%2Fsaml2aws/lists"}