AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Creates or updates one or more role profiles for use with authentication against a SAML-based federated identity provider to obtain temporary role-based AWS credentials.

Syntax

StoreOneRole (Default)
Set-AWSSamlRoleProfile
-EndpointName <String>
-PrincipalARN <String>
-RoleARN <String>
-StoreAs <String>
-STSEndpointRegion <String>
StoreAllRoles
Set-AWSSamlRoleProfile
-EndpointName <String>
-StoreAllRoles <SwitchParameter>
-STSEndpointRegion <String>

Description

Creates or updates role profiles for use with a SAML federated identity provider to obtain temporary AWS credentials for roles the user is authorized to assume. The endpoint for authentication should have been configured previously using Set-AWSSamlEndpoint. Once created the role profiles can be used to obtain time-limited temporary AWS credentials by specifying the name of the role profile to the -ProfileName parameter of the Set-AWSCredentials cmdlet or any cmdlet that makes calls to AWS service operations.

User authentication is not performed until AWS credentials are required, i.e. just prior to a service operation call. Additionally if the credentials expire then the tools will automatically attempt to re-authenticate the user to obtain fresh credentials. When a role profile is configured to use the default logged-in user identity then this process happens silently. If a role profile is configured to use an alternate identity (by specifying the -NetworkCredential parameter) the user is prompted to re-enter their credentials prior to re-authentication.

Parameters

-EndpointName <String>
The name assigned to the endpoint definition that was previously registered using Set-AWSSamlEndpoint. The endpoint definition contains the URL of the endpoint to be used to authenticate users prior to vending temporary AWS credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-PrincipalARN <String>
The Amazon Resource Name (ARN) of the principal holding the role to be assumed when credentials are requested following successful authentication. If specified the RoleARN parameter must also be specified.

If neither of the PrincipalARN and RoleARN parameters are supplied and the user is authorized to assume multiple roles the cmdlet will prompt to select the role that should be referenced by the profile. The user is also prompted if ARNs are specified but cannot be found in the data returned on successful authentication.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-RoleARN <String>
The Amazon Resource Name (ARN) of the role to be assumed when credentials are requested following successful authentication. If specified the PrincipalARN parameter must also be specified.

If neither of the PrincipalARN and RoleARN parameters are supplied and the user is authorized to assume multiple roles the cmdlet will prompt to select the role that should be referenced by the profile. The user is also prompted if ARNs are specified but cannot be found in the data returned on successful authentication.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StoreAllRoles <SwitchParameter>
If set all roles available to the user are evaluated following authentication and one role profile per role will be created. The name of each role will be used for each corresponding profile that is created.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-StoreAs <String>
The name to associate with the role data. This name will be used with the -ProfileName parameter to Set-AWSCredentials cmdlet and AWS service cmdlets to load the profile and obtain temporary AWS credentials based on the role and other data held in the profile.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-STSEndpointRegion <String>
Specifies the region to be used when making calls to STS to obtain temporary credentials after successful authentication. This parameter is only needed in regions where a specific regional endpoint for STS must be used (eg cn-north-1). In all regions where the global sts.amazonaws.com endpoint can be used this parameter should not be specified.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-NetworkCredential <PSCredential>
Optional. Supply a value only if an identity different to the user's default Windows identity should be used during authentication.

If an alternate credential is specified then when the tools need to re-authenticate the user to obtain fresh credentials following expiry the user is prompted to re-enter the password for the user account before re-authentication can be performed. When the default user identity is configured for use (-NetworkCredential not specified) re-authentication occurs silently.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesCredential, UserCredential

Outputs

System.String
This cmdlet returns the name of the role profile to the pipeline. If the -StoreAllRoles switch is used the names of all created or updated profiles are output.

Examples

Example 1

Set-AWSSamlRoleProfile -StoreAs Role1 -EndpointName MyADFSEndpoint
Authenticates the currently logged in user account against the specified endpoint (configured previusly using Set-AWSSamlEndpoint). Following successful authentication, if the user is authorized to assume only a single role the role details are stored in a profile named 'Role1'. If the user is authorized for more than one role a menu is presented for the desired  role to be associated with the profile to be selected.

The role profile can be used to obtain time-limited temporary AWS credentials by specifying it as the value of the -ProfileName parameter to the Set-AWSCredentials cmdlet or any cmdlet that makes calls to AWS service operations. Authentication prior to obtaining credentials is performed using the current user identity.

Example 2

$credential = Get-Credential -Message "Enter user credentials for authentication" 
Set-AWSSamlRoleProfile -StoreAs Role1 -EndpointName MyADFSEndpoint -NetworkCredential $credential
	
Authenticates the specified user account against the specified endpoint (configured previously using Set-AWSSamlEndpoint). Following successful  authentication, if the user is authorized to assume only a single role the role details are stored in a profile named 'Role1'. If the user is authorized for more than one role a menu is presented for the desired  role to be associated with the profile to be selected.

The role profile can be used to obtain time-limited temporary AWS credentials by specifying it as the value of the -ProfileName parameter to the Set-AWSCredentials cmdlet or any cmdlet that makes calls to AWS service operations. Authentication prior to obtaining credentials is performed using the current user identity.

Example 3

$params = @{
    "PrincipalARN"="arn:aws:iam::012345678912:saml-provider/ADFS"
    "RoleARN"="arn:aws:iam::012345678912:role/ADFS-Dev"
}
Set-AWSSamlRoleProfile @params -StoreAs ADFS-Dev
	
This example shows how to create or update a role profile when the Amazon Resource Names (ARNs) for the role are known in advance. Following authentication for the currently logged in user the cmdlet will verify that the role is present in the set the user is authorized to assume and set up the role profile. If the role is not found the user is prompted to select the correct role.

To authenticate as a different user account add the -NetworkCredential parameter as shown in other examples.

Example 4

Set-AWSSamlRoleProfile -StoreAllRoles -EndpointName MyADFSEndpoint
Authenticates the current user account against the configured endpoint and if successful creates one role profile for each role the user is authorized to assume. The 'friendly name' of the role is used as the name for each profile.

To authenticate as a different user account add the -NetworkCredential parameter as shown in other examples.
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z