How do I grant my Active Directory users access to the API or AWS CLI with AD FS?

Short description

When you allow SAML 2.0 federated users to access the AWS Management Console, users who require programmatic access still must have an access key and a secret key.

To get the access key ID and secret access key for an AWS Identity and Access Management (IAM) user, you can:

Configure the AWS CLI.

-or-

Get temporary credentials for federated users to access the AWS CLI.

Before you can give access to a federated user, you must:

• Turn on federation to AWS using Windows Active Directory, AD FS, and SAML 2.0.
• Use version 3.1.31.0 or higher of the AWS Tools for PowerShell. You can also install v2.36 or higher (stable version) of the AWS SDK for Python to your workstation.
• Use a minimal credentials file .aws/credentials.

Note: This solution is not compatible if you have multi-factor authentication (MFA) turned on for your directory users.

Resolution

If your identity provider (IdP) is configured to work with Integrated Windows Authentication (IWA), NTLM, or Kerberos (default for AD FS 2.0), see Solution 1. If your IdP is configured to work with Form-Based Authentication (default for AD FS 3.0 and 4.0), see Solution 2.

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

Solution 1: PowerShell for AD FS using IWA (PowerShell 2.0)

1.    Import the Windows PowerShell module by running the following command:

> Import-Module "C:\Program Files (x86)\AWS Tools\PowerShell\AWSPowerShell\AWSPowerShell.psd1"

2.    Set a variable for your AD FS endpoint by running a command similar to the following:

> $Endpoint = 'https://adfs.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices'

Note: This includes the complete URL of your AD FS login page and the login uniform resource name (URN) for AWS. 3.    Set the SAML endpoint by running a command similar to the following:

> $EndpointName = Set-AWSSamlEndpoint -Endpoint "$Endpoint" -StoreAs 'ADFS-Login' -AuthenticationType NTLM

Note: By default, the AD FS 2.0 AuthenticationType is set to NTLM. If you don't specify a value for the AuthenticationType in the preceding AWS Tools Cmdlet example, then AWS Tools uses Kerberos by default.

4.    Use the stored endpoint settings to authenticate with the AD FS IdP to obtain a list of roles that the user can then assume by using one of the following methods:

Use the credentials of the user who is currently logged into the workstation.

> Set-AWSSamlRoleProfile -StoreAs 'SAMLUser' -EndpointName $EndpointName

-or-

Specify credentials of an Active Directory user.

> $Credential = Get-Credential -Message "Enter the domain credentials for the endpoint"
> Set-AWSSamlRoleProfile -EndpointName $EndpointName -NetworkCredential $credential -StoreAs 'SAMLUser'

5.    If multiple roles are available, you're prompted to select the role that you want to assume. Enter the alphabetic character into your terminal session similar to the following:

SAMLUser[A] A - 123456789012:role/ADFS-DevAdmin [B] B - 123456789012:role/ADFS-DevReadOnly [?] Help (default is "A"): A

6.    Confirm that users can access the AWS CLI using the federated credentials and the specified profile by running a command similar to the following:

Get-IAMSAMLProviderList -ProfileName SAMLUser

Solution 2: Python for AD FS using form-based authentication (default for AD FS 3.0 and 4.0)

1.    Install the following modules to Python:

pip install --upgrade boto beautifulsoup4 requests

2.    Implement a general solution for federated API/CLI access using SAML 2.0, and then download the script from step 4 of this linked blog post.

3.    Open the script and set your preferred Region and output format. Replace adfs.example.com with your URL, and then enter the fully qualified domain name (FQDN) of your AD FS server.

region = 'eu-west-1'
    outputformat = 'json'
    awsconfigfile = '/.aws/credentials'
    idpentryurl = 'https://adfs.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices'

Note: If you have a different file path for your AWS credentials file, specify the file path.

4.    Save your changes, run the file, and then populate the following fields as they appear:

bob@Ubuntu64:~$ ./working_samlapi.py
   Username: bob@example.com
   Password: ***********

   Please choose the role you would like to assume:
   [ 0 ]:  arn:aws:iam::123456789012:role/ADFS-DevAdmin
   [ 1 ]:  arn:aws:iam::123456789012:role/ADFS-DevReadOnly

   Selection:  0

   ----------------------------------------------------------------
   Your new access key pair has been stored in the AWS configuration file /home/ec2-user/.aws/credentials under the saml profile.
   Note that it will expire at 2018-03-14T14:57:45Z.
   After this time, you may safely rerun this script to refresh your access key pair.
   To use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances).
   ----------------------------------------------------------------

5.    After you successfully federate, run commands using the newly configured SAML profile using the --profile parameter in your commands.

bob@Ubuntu64:~$ aws iam list-saml-providers --profile saml
            
{
  "SAMLProviderList": [
    {
      "CreateDate": "2018-03-14T13:28:24Z",
      "ValidUntil": "2118-03-14T13:28:23Z",
      "Arn": "arn:aws:iam::123456789012:saml-provider/adfs"
    }
  ]
}

Related information

Configuring federated identity with the AWS Tools for PowerShell

Single sign-on