AWS Tools for PowerShell
User Guide

Configuring Federated Identity with the AWS Tools for PowerShell

To let users in your organization access AWS resources, you must configure a standard and repeatable authentication method for purposes of security, auditability, compliance, and the capability to support role and account separation. Although it's common to provide users with the ability to access AWS APIs, without federated API access, you would also have to create AWS Identity and Access Management (IAM) users, which defeats the purpose of using federation. This topic describes SAML (Security Assertion Markup Language) support in the Tools for PowerShell that eases your federated access solution.

SAML support in the Tools for PowerShell lets you provide users federated API access. SAML is an XML-based, open-standard format for transmitting user authentication and authorization data between services; in particular, between an identity provider (such as Active Directory Federation Services), and a service provider (such as AWS). For more information about SAML and how it works, see SAML on Wikipedia, or SAML Technical Specifications at the Organization for the Advancement of Structured Information Standards (OASIS) website. SAML support in the Tools for PowerShell is compatible with SAML 2.0.


You must have the following in place before you try to use SAML support for the first time.

  • A federated identity solution that is correctly integrated with your AWS account for console access by using only your organizational credentials. For more information about how to do this specifically for Active Directory Federation Services, see the blog post, Enabling Federation to AWS Using Windows Active Directory, AD FS, and SAML 2.0. Although the blog post covers AD FS 2.0, the steps are similar if you are running AD FS 3.0.

  • Version or newer of the Tools for PowerShell installed on your local workstation.

How an Identity-Federated User Gets Federated Access to AWS Service APIs

The following process describes, at a high level, how an Active Directory (AD) user is federated by AD FS to gain access to AWS resources.

  1. The federated user authenticates against AD FS.

  2. If authentication is successful, the user is sent a SAML assertion.

  3. The SAML assertion is sent to the AWS Security Token Service (STS) in the form of a SAML request.

  4. If the SAML request is valid, STS returns a SAML response that contains the user's AWS temporary credentials.

  5. The AWS temporary credentials can be used to work with AWS service APIs by using tools including the Tools for PowerShell.

How SAML Support Works in the Tools for PowerShell

This section describes how Tools for PowerShell cmdlets enable configuration of SAML-based identity federation for users.

  1. The Tools for PowerShell authenticate against AD FS by using the Windows user's current credentials, or interactively, when a cmdlet that requires credentials to call into AWS is run.

  2. AD FS authenticates the user.

  3. AD FS generates a SAML 2.0 authentication response that includes an assertion; the purpose of the assertion is to identify and provide information about the user. The PowerShell cmdlet extracts the list of the user's authorized roles from the SAML assertion.

  4. The PowerShell cmdlet forwards the SAML request, including the requested role Amazon Resource Names (ARN), to STS by making the AssumeRoleWithSAMLRequest API call.

  5. If the SAML request is valid, STS returns a response that contains the AWS AccessKeyId, SecretAccessKey, and SessionToken. These credentials last for 3,600 seconds (1 hour).

  6. The Tools for PowerShell user now has valid credentials to work with any AWS service APIs that the user's role is authorized to access. The Tools for PowerShell automatically apply these credentials for any subsequent AWS API calls, and renew them automatically when they expire.


    When the credentials expire, and new credentials are required, the Tools for PowerShell automatically reauthenticate with AD FS, and obtain new credentials for a subsequent hour. For users of domain-joined accounts, this process occurs silently. For accounts that are not domain-joined, users are prompted to enter their credentials before they can reauthenticate.

How to Use the PowerShell SAML Configuration Cmdlets

The Tools for PowerShell include two new cmdlets that provide SAML support.

  • Set-AWSSamlEndpoint configures your AD FS endpoint, assigns a friendly name to the endpoint, and optionally describes the authentication type of the endpoint.

  • Set-AWSSamlRoleProfile creates or edits a user account profile that you want to associate with an AD FS endpoint, identified by specifying the friendly name you provided to the Set-AWSSamlEndpoint cmdlet. Each role profile maps to a single role that a user is authorized to perform.

    Just as with AWS credential profiles, you assign a friendly name to the role profile. You can use the same friendly name with the Set-AWSCredential cmdlet, or as the value of the -ProfileName parameter for any cmdlet that invokes AWS service APIs.

Open a new Tools for PowerShell session. If you are running PowerShell 3.0 or newer, the Tools for PowerShell module is automatically imported when you run any of its cmdlets. If you are running PowerShell 2.0, you must import the module manually. To do this, run the Import-Module cmdlet, as shown in the following example.

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

How to Run the Set-AWSSamlEndpoint and Set-AWSSamlRoleProfile Cmdlets

  1. First, configure the endpoint settings for the AD FS system. The simplest way to do this is to store the endpoint in a variable, as shown in this step. Be sure to replace the placeholder account IDs and AD FS host name with your own account IDs and AD FS host name. Specify the AD FS host name in the Endpoint parameter.

PS C:\> $endpoint = ""
  1. To create the endpoint settings, run the Set-AWSSamlEndpoint cmdlet, specifying the correct value for the AuthenticationType parameter. Valid values include Basic, Digest, Kerberos, Negotiate, and NTLM. If you do not specify this parameter, the default value is Kerberos.

    PS C:\> $epName = Set-AWSSamlEndpoint -Endpoint $endpoint -StoreAs ADFS-Demo -AuthenticationType NTLM

    The cmdlet returns the friendly name you assigned by using the -StoreAs parameter, so you can use it when you run Set-AWSSamlRoleProfile in the next line.

  2. Now, you run the Set-AWSSamlRoleProfile cmdlet to authenticate with the AD FS identity provider and get the set of roles (in the SAML assertion) that the user is authorized to perform.

    The Set-AWSSamlRoleProfile cmdlet uses the returned set of roles to either prompt the user to select a role to associate with the specified profile, or validate that role data provided in parameters is present (if not, the user is prompted to choose). If the user is authorized for only one role, the cmdlet associates the role with the profile automatically, without prompting the user. There is no need to provide a credential to set up a profile for domain-joined usage.

    PS C:\> Set-AWSSamlRoleProfile -StoreAs SAMLDemoProfile -EndpointName $epName

    Alternatively, for non-domain-joined accounts, you can provide Active Directory credentials, and then select an AWS role to which the user has access, as shown in the following line. This is useful if you have different Active Directory user accounts to differentiate roles within your organization (for example, administration functions).

    PS C:\> $credential = Get-Credential -Message "Enter the domain credentials for the endpoint" Set-AWSSamlRoleProfile -EndpointName $epName -NetworkCredential $credential -StoreAs SAMLDemoProfile
  3. In either case, the Set-AWSSamlRoleProfile cmdlet prompts you to choose which role should be stored in the profile. The following example uses the ADFS-Dev role.

    Select Role Select the role to be assumed when this profile is active [1] 1 - ADFS-Dev [2] 2 - ADFS-Production [?] Help (default is "1"): 1

    You can also specify a role without waiting for the prompt, by entering the RoleARN, PrincipalARN, and optional NetworkCredential parameters (provided the role exists in the assertion returned by authentication. If it does not exist, the user is prompted to choose from available roles.)

    PS C:\> $params = @{ "NetworkCredential"=$credential, "PrincipalARN"="{arn:aws:iam::012345678912:saml-provider/ADFS}", "RoleARN"="{arn:aws:iam::012345678912:role/ADFS-Dev}" } PS C:\> $epName | Set-AWSSamlRoleProfile @params -StoreAs SAMLDemoProfile1 -Verbose
  4. You can create profiles for all roles in a single command by adding the StoreAllRoles parameter, as shown in the following code. Note that the role name is used as the profile name.

    PS C:\> Set-AWSSamlRoleProfile -EndpointName $epName -StoreAllRoles ADFS-Dev ADFS-Production

How to Use Role Profiles to Run Cmdlets that Require AWS Credentials

To run cmdlets that require AWS credentials, you can use role profiles. Provide the name of a role profile to Set-AWSCredential (or as the value for any ProfileName parameter in the Tools for PowerShell) to get temporary AWS credentials automatically for the role that is described in the profile.

Although you use only one role profile at a time, you can switch between profiles within a shell session. The Set-AWSCredential cmdlet does not authenticate and get credentials when you run it by itself; the cmdlet records that you want to use a specified role profile. Until you run a cmdlet that requires AWS credentials, no authentication or request for credentials occurs.

You can now use the temporary AWS credentials that you obtained with the SAMLDemoProfile profile to work with AWS service APIs. The following sections show examples of how to use role profiles.

Example 1: Set a Default Role with Set-AWSCredential

This example sets a default role for a Tools for PowerShell session by using Set-AWSCredential. Then, you can run cmdlets that require credentials, and are authorized by the specified role. This example lists all Amazon Elastic Compute Cloud instances in the US West (Oregon) Region that are associated with the profile you specified with the Set-AWSCredential cmdlet.

PS C:\> Set-AWSCredential -ProfileName SAMLDemoProfile PS C:\> Get-EC2Instance -Region us-west-2 | Format-Table -Property Instances,GroupNames Instances GroupNames --------- ---------- {TestInstance1} {default} {TestInstance2} {} {TestInstance3} {launch-wizard-6} {TestInstance4} {default} {TestInstance5} {} {TestInstance6} {AWS-OpsWorks-Default-Server}

Example 2: Change Role Profiles During a PowerShell Session

This example lists all available Amazon Simple Storage Service buckets in the AWS account of the role associated with the SAMLDemoProfile profile. The example shows that although you might have been using another profile earlier in your Tools for PowerShell session, you can change profiles by specifying a different value for the -ProfileName parameter with cmdlets that support it. This is a common task for administrators who manage Amazon S3 from the PowerShell command line.

PS C:\> Get-S3Bucket -ProfileName SAMLDemoProfile CreationDate BucketName ------------ ---------- 7/25/2013 3:16:56 AM mybucket1 4/15/2015 12:46:50 AM mybucket2 4/15/2015 6:15:53 AM mybucket3 1/12/2015 11:20:16 PM mybucket4

Note that the Get-S3Bucket cmdlet specifies the name of the profile created by running the Set-AWSSamlRoleProfile cmdlet. This command could be useful if you had set a role profile earlier in your session (for example, by running the Set-AWSCredential cmdlet) and wanted to use a different role profile for the Get-S3Bucket cmdlet. The profile manager makes temporary credentials available to the Get-S3Bucket cmdlet.

Though the credentials expire after 1 hour (a limit enforced by STS), the Tools for PowerShell automatically refresh the credentials by requesting a new SAML assertion when the tools detect that the current credentials have expired.

For domain-joined users, this process occurs without interruption, because the current user's Windows identity is used during authentication. For non-domain-joined user accounts, the Tools for PowerShell show a PowerShell credential prompt requesting the user password. The user provides credentials that are used to reauthenticate the user and get a new assertion.

Example 3: Get Instances in a Region

The following example lists all Amazon EC2 instances in the Asia Pacific (Sydney) Region that are associated with the ADFS-Production profile. This is a useful command for returning all Amazon EC2 instances in a region.

PS C:\> (Get-Ec2Instance -ProfileName ADFS-Production -Region ap-southeast-2).Instances | Select InstanceType, @{Name="Servername";Expression={$_.tags | where key -eq "Name" | Select Value -Expand Value}} InstanceType Servername ------------ ---------- t2.small DC2 t1.micro NAT1 t1.micro RDGW1 t1.micro RDGW2 t1.micro NAT2 t2.small DC1 t2.micro BUILD

Additional Reading

For general information about how to implement federated API access, see How to Implement a General Solution for Federated API/CLI Access Using SAML 2.0.

For questions or comments, be sure to visit the AWS Developer Forums for PowerShell Scripting or .NET Development.