Amazon AppStream 2.0
Developer Guide

Setting Up SAML

You can use an IAM role and a relay state URL to configure your SAML 2.0-compliant IdP and enable AWS to permit your federated users to access an AppStream 2.0 stack. The role grants the user permissions to access the stack. The relay state is the stack portal to which the user is forwarded after successful authentication by AWS.


Here is a summary of the prerequisite steps required for configuring your SAML 2.0 connection.

  • Configure your IdP to establish a trust relationship with AWS.

    • Inside your organization's network, configure your identity store, such as Windows Active Directory, to work with a SAML-based identity provider (IdP), such as Microsoft Windows Active Directory Federation Services, Shibboleth, and so on.

    • Using your IdP, generate a metadata document that describes your organization as an identity provider.

    • For more information, see AppStream 2.0 Integration with SAML 2.0 .

  • Create an AppStream 2.0 stack and note the name of the stack for use in IAM policy and IdP configuration.

    • You can create an AppStream 2.0 stack using the AppStream 2.0 management console, AWS CLI, or AppStream 2.0 API.

Step 1: Create a SAML Provider in AWS

This identity provider defines your organization's IdP to AWS using the metadata document you previously generated using your IdP. Here are the steps to create a SAML provider in AWS:

  • Sign in to the AWS Identity and Access Management (IAM) console.

  • Create a new SAML provider, which is an entity in IAM that holds information about your organization's identity provider.

  • As part of this process, upload the metadata document produced by the IdP software in your organization noted in the previous section. For more information, see Creating SAML Identity Providers in the IAM User Guide.

Step 2: Configure Permissions in AWS for Your Federated Users

The next step is to create an IAM role that establishes a trust relationship between IAM and your organization's IdP. The trust relationship identifies your IdP as a principal (trusted entity) for the purposes of federation. The role also defines which users authenticated by your organization's IdP are allowed to access an AppStream 2.0 stack. For more information about creating a role for a SAML IdP, see Creating a Role for SAML 2.0 Federation in the IAM User Guide.

After you have created the role, you can limit the role to have permissions only to one or more AppStream 2.0 stacks by attaching an inline policy to the role. The following sample policy document provides access to a single AppStream 2.0 stack:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "appstream:Stream", "Resource": "arn:aws:appstream:REGION-CODE:ACCOUNT-ID-WITHOUT-HYPHENS:stack/STACK-NAME", "Condition": { "StringEquals": { "appstream:userId": "${saml:sub}", "saml:sub_type": "persistent" } } } ] }

Choose a value for REGION-CODE that corresponds to the region where your AppStream 2.0 stack exists, and replace STACK-NAME with the name of the stack. You can view stack details in the Stacks dashboard of the AppStream 2.0 management console.

Step 3: Configure the SAML IdP

After you create the role, update your SAML IdP about AWS as a service provider by installing the saml-metadata.xml file found at Review instructions provided by your IdP for updating the metadata. Some providers give you the option to type the URL, whereupon the IdP gets and installs the file for you. Others require you to download the file from the URL and then provide it as a local file. For more information, see your IdP documentation or AppStream 2.0 Integration with SAML 2.0 .

Step 4: Create Assertions for the SAML Authentication Response

Next, configure the information that the IdP passes as SAML attributes to AWS as part of the authentication response. For more information, see Configuring SAML Assertions for the Authentication Response in the IAM User Guide.


For stacks with domain-joined fleets, the NameID for the user must be provided in the format of "domain\username" using the sAMAccountName or "" using userPrincipalName. If using the sAMAccountName format, the domain can be specified using either the NetBIOS name or the fully qualified domain name (FQDN). For more information, see Using Active Directory Domains with AppStream 2.0.

Step 5: Configure the Relay State of Your Federation

Configure the relay state of your federation to point to the AppStream 2.0 stack relay state URL. After successful authentication by AWS, the user is directed to the AppStream 2.0 stack portal, defined as the relay state in the SAML authentication response.

The format of the relay state URL is as follows:


Construct your relay state URL from your AWS account ID, stack name, and the relay state endpoint associated with the region in which your stack is located.

Region Relay state endpoint
us-east-1 (N.Virginia)
us-west-2 (Oregon)
eu-west-1 (Ireland)
ap-northeast-1 (Tokyo)