Package: awscli-login
The awscli-login plugin allows retrieving temporary Amazon credentials
by authenticating against a SAML Identity Provider (IdP).  This
application is fully supported under Linux, macOS, and theWindows
Subsystem for Linux.
Currently, Windows PowerShell, Command Prompt, and Git Shell for
Windows are supported with limitations (SeeWindows Issues).Jump to:InstallationGetting StartedAdvanced UsageAdvanced ConfigurationCommand line argumentsKnown IssuesInstallationThe simplest way to install the awscli-login plugin is to use pip:$ pip install awscli-loginAfter awscli-login has been installed, run the following command
to enable the plugin:$ aws configure set plugins.login awscli_loginIf you receive a bad interpreter error or other error please see
theKnown Issuessection below.Getting StartedBefore using awscli-login to retrieve temporary credentials,
optionally configure one or morenamed profilesfor use with the plugin. To configure this plugin, you must know
the URL of the ECP Endpoint for your IdP.  If you do not have this
information, contact your IdP administrator.Here is an example configuring the default profile for use with the
University of Illinois at Urbana-Champaign’s IdP:$ aws login configure
ECP Endpoint URL [None]: https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Username [None]:
Enable Keyring [False]:
Duo Factor [None]:
Role ARN [None]:To log in, type the following command:$ aws login
Username [username]: netid
Password: ********
Factor: passcode
Code: 123456789Theusernameandpasswordare the values needed to authenticate
against the IdP configured for the selected profile.  Thefactoris only required if your IdP requires Duo for authentication.  If
it does not, leavefactorblank. If your IdP does require Duo
thenfactormay be one ofauto,push,passcode,sms, orphone.  Iffactoris left blank,autois
the default. Thecodeis a Duo code useful for use with a
YubiKey, SMS codes, or other one-time codes.If you have access to more than one role, you will be prompted to
choose one. For example:$ aws login
Username [username]: netid
Password: ********
Factor:
Please choose the role you would like to assume:
    Account: 978517677611
        [ 0 ]: Admin
    Account: 520135271718
        [ 1 ]: ReadOnlyUser
        [ 2 ]: S3Admin
Selection: 2To switch roles, first log out, then log in again selecting a
different role. Note that if you log in to the same IdP using the
same username, you will not be prompted for your password or Duo
factor until the IdP session expires:$ aws logout
$ aws login
Username [netid]:
Please choose the role you would like to assume:
    Account: 520135271718
        [ 0 ]: TestUser
        [ 1 ]: IAMUser
Selection: 0Advanced UsageIt is possible to be logged in to more than one role at the same
time using multiplenamed profiles.
For example, consider the following configuration involving two
profiles – one calledprod, and the othertest:$ aws --profile prod login configure
ECP Endpoint URL [None]: https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Username [None]: netid
Enable Keyring [False]: True
Duo Factor [None]: auto
Role ARN [None]: arn:aws:iam::999999999999:role/Admin

$ aws --profile test login configure
ECP Endpoint URL [None]: https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Username [None]: netid
Enable Keyring [False]: True
Duo Factor [None]: passcode
Role ARN [None]: arn:aws:iam::111111111111:role/AdminThis example involves several advanced features. First, we are
setting the username, factor, and role. This means we will not be
prompted for this information when logging in to these two profiles.
In addition, we are using a keyring. On the first login using one
of the profiles, the user will be prompted for his password.  On
subsequent logins the user will not be prompted for his password
because it has been stored in a secure keyring.For example, when we initially log in to prod:$ export AWS_PROFILE=test
$ aws login
Password: ********
Code: 123456789We are only prompted for the password and code. We’re prompted for
the password because this is the initial login, and the code because
this profile is configured for use with a passcode device such as
a YubiKey. We are now no longer prompted when we log in to test:$ aws --profile prod loginEven if the IdP session has expired in this case, we will not be
prompted for a password because it is stored in the keyring. The
user will receive either a phone call or a push to the default
Duo device.Advanced ConfigurationThe plugin’s configuration file (~/.aws-login/config) is an ini
file that supports more configuration options than is exposed via
the basic interactive configuration as seen in theGetting Startedsection. Each section corresponds to anAWS named profilejust like the awscli’s credentials file~/.aws/credentials.Here is a simple example configuration file:[default]
ecp_endpoint_url = https://shib.uiuc.edu/idp/profile/SAML2/SOAP/ECP
username = netid
enable_keyring = True
factor = auto

[prod]
username = netid
ecp_endpoint_url = https://shib.uiuc.edu/idp/profile/SAML2/SOAP/ECPand the corresponding awscli configuration file~/.aws/config[plugins]
login = awscli_login

[default]
region = us-east-2
output = json

[profile prod]
region = us-east-2
output = jsonAll configuration options are documented below in thepropertiessection.PropertiesEach property can be overridden at the command line using a flag.
See the online documentation for further details by runningaws login help.ecp_endpoint_urlThe ECP endpoint URL of the IdP. This is the only required
property:ecp_endpoint_url = https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECPusernameThe username to use on login to the IdP. If the username is not
supplied the user will be prompted:username = netidpasswordThe password to use on login to the IdP. If the password is not
supplied the user will be prompted. It is not recommended to
use this property. Instead supply the password interactively
or use the keyring for secure storage:password = secretThe password property and command line flag are ignored if the
keyring is enabled. When this happens a warning is issued.factorTheDuo factorto use
on login:factor = autoThe following values are currently supported:factorautoauthenticates withpushif available,
otherwise fallbacks tophonepushauthenticates with Duo Pushpasscodeauthenticates the user with a user
supplied code from a hardware token,
Duo Mobile, or bypass codesmssends a batch of SMS passcodes to the userphoneAuthenticates with phone callbackTo login usingsms, requires two attempts. The first attempt
will send SMS passcodes, and return authentication failed. The
second attempt will use the passcodes:$ aws login --factor sms
Authentication failed!
$ aws login --factor passcode
Code: 829437passcodeA bypass code or Duopasscodegenerated by Duo Mobile, SMS, or a hardware token can be set
using the passcode property:passcode = 829437It is not recommended to store a passcode in your configuration
file since a passcode can only be used once. A passcode is
better passed interactivally or by the--passcodecommand
line flag.role_arnThe role ARN to select. If the IdP returns a single role it is
autoselected:role_arn = arn:aws:iam::999999999999:role/Adminenable_keyringBy default the keyring is not used for password storage. The
keyring is implemented using the Python modulekeyring, and supports various
secure backends such as the macOS Keychain, Windows Credential
Locker, and Linux keyrings. Additional, system configuration
may be required to use a keyring on Linux systems (Seehttps://pypi.org/project/keyringfor details). Set to True to
enable:enable_keyring = TrueThe password property and command line flag are ignored when
the keyring is enabled.disable_refresh:On POSIX systems tokens are refreshed automatically unless this
property is set to True:disable-refresh = TruerefreshHow often the refresh process attempts to renew the STS credentials
in seconds. When set to 0 the refresh process will refresh once
90% of the time till expiration has transpired (Default 0):refresh = 1800durationSet the time in seconds that the STS token will last. The token
lasts for the duration you specify, or until the time specified
by the IdP, whichever is shorter. The default is an hour, and
the minimum is 15 minutes (SeeAssumeRoleWithSAMLfor details):duration = 3600http_header_factorHTTP Header to store the user’s Duo factor:http_header_factor = X-Shibboleth-Duo-Factorhttp_header_passcodeHTTP Header to store the user’s passcode:http_header_passcode = X-Shibboleth-Duo-PasscodeCommand line argumentsThe plugin supports two subcommandsloginandlogout.loginDetailed online documentation can be accessed using the following
command:$ aws login helpAllproperties, except for enable_keyring, can be overridden
with a corresponding command line option. Properties that contain
an underscore will have a corresponding option with hyphens, for
example the property ecp_endpoint_url becomes--ecp-endpoint-url.
For details on these options see the documentation above or refer
to the online documentation. Options not avaliable as properties
are documented below.options--ask-passwordForce prompt for password. This can be used to override theenable_keyringproperty.--force-refreshForces the refresh process to retrieve new credentials for the
user selected role. If the refresh process is not running then
a normal login will proceed after a warning.--verboseDisplay verbose output. The flag can be repeated up to three
times. Each time it is repeated more detailed information is
returned.configureSeeGetting Startedand online documentation for documentation on this
subcommand:$ aws login configure helpoptions--verboseDisplay verbose output. The flag can be repeated up to three
times. Each time it is repeated more detailed information is
returned.logoutSeeGetting Startedand online documentation for documentation on this
subcommand:$ aws logout helpoptions--verboseDisplay verbose output. The flag can be repeated up to three
times. Each time it is repeated more detailed information is
returned.Known IssuesUnable to authenticate after changing passwordAfter the user changes his IdP password, subsequent logins fail.
To remedy the situation, change the data stored in the keyring as follows:$ keyring set awscli_loginusername@hostname_of_your_IdPYou may be prompted for your user login password by your operating
system, depending on how your key store is configured.Command line flag--ecp-endpoint-urlerror parsing parameterIf you encounter the following error it is because the awscli expects
urls passed as arguments to return a 200 on an HTTP GET (Seeaws-cli#4473):$ aws login --ecp-endpoint-url https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Error parsing parameter '--ecp-endpoint-url': Unable to retrieve https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP: received non 200 status code of 500This check can be disabled on a per profile basis using the following
command:$ aws configure set cli_follow_urlparam offWindows issuesAuto-renewal is not supported under the Windows PowerShell, Command
Prompt, or Git Shell for Windows. Auto-renewal is supported under
the Windows Subsystem for Linux (WSL).GitBash bad interpreter errorsIf you receive a bad interpreter error from the aws command it may
be because you have a space in the path of your Python interpreter:bash: /c/Users/me/AppData/Roaming/Python/Python38/Scripts/aws: c:\program: bad interpreter: No such file or directoryTo fix this issue either reinstall your Python interpreter to a
path that does not contain a space and then reinstall the awscli
package, or more simply just define an alias in your bashrc file:alias aws='python $(which aws)'Windows Subsystem for Linux bad interpreter errorIf you receive a bad interpreter error from the aws command on
Windows Subsystem for Linux (WSL) it may be because the location
where the awscli is installed is not listed in the WSL’s PATH before
the location of a Windows install of awscli:-bash: /mnt/c/Python39/Scripts/aws: c:\python39\python.exe^M: bad interpreter: No such file or directoryTo remedy this issue please ensure that the location where the
awscli is installed in the WSL comes before the location of the
Windows install in the WSL PATH environment variable.