Amazon AppStream 2.0 supports identity federation to AppStream 2.0 stacks through Security Assertion Markup Language 2.0 (SAML 2.0). You can use an identity provider (IdP) that supports SAML 2.0 to provide an onboarding flow for your AppStream 2.0 users. Examples of an IdP are Active Directory Federation Services (AD FS) in Windows Server, Ping One Federation Server, or Okta. This feature offers your users the convenience of a one-step access to their AppStream 2.0 applications using their existing identity credentials. You also have the security benefit of identity authentication by your IdP. By using your IdP, you can control which users have access to a particular AppStream 2.0 stack.

AWS Single Sign-On (AWS SSO) is an AWS service that lets you centrally manage SSO access to multiple AWS accounts and business applications. AWS SSO provides a user portal so that your users can find and access all of their assigned accounts and applications from one place, using their existing corporate credentials. AWS SSO is integrated with AWS Organizations to enable you to manage access to AWS accounts in your organization. In addition, AWS SSO supports Security Assertion Markup Language (SAML) 2.0, which means you can extend SSO access to your SAML-enabled applications by using the AWS SSO application configuration wizard. For more information about AWS SSO and its benefits, refer to AWS SSO documentation.

Using AWS SSO, you can setup identity federation to AppStream 2.0 stacks. If your AppStream 2.0 fleets are connected to an Active Directory domain, you can also connect AWS SSO to that same domain. Then you can assign stacks to Active Directory users or user groups. If your AppStream 2.0 stacks are not domain joined, you can use the built-in user management capabilities of AWS SSO to create users or user groups and provide them access to AppStream 2.0 stacks. This blog post describes how to do both.

In this post, you:

1. Learn about the AWS SSO Directory Options
2. Connect AWS SSO to your Active Directory
3. Create the AWS SSO Application for AppStream 2.0 (AWS SSO)
4. Create the AppStream 2.0 Identity Provider (IAM)
5. Create the AppStream 2.0 Stack stream access role (IAM)
6. Attach an Inline Policy to the AppStream 2.0 stream access role (IAM)
7. Create the AWS SSO Attribute Mappings (AWS SSO)
8. Assign User(s) and Test
9. Alternate Directory Path: How to use AWS SSO dedicated directory to manage access to AppStream 2.0

Prerequisites

This post assumes that the following prerequisites are in place:

• AWS SSO prerequisites are met
• An existing Active Directory Forest or AWS Managed Microsoft Active Directory
• Familiarity with AppStream 2.0
• An existing AppStream 2.0 stack

Now, lets review a few directory options for AWS SSO, and then get started.

1) AWS SSO directory options

AWS SSO allows administrators to connect AWS SSO in the following ways:

• AWS Managed Microsoft Active Directory
• An on-premise Active Directory using a two-way trust relationship between an AWS Managed Microsoft Active Directory and an on-premise Active Directory
• AD Connector

Note: AWS SSO does not support SAMBA4-based Simple AD as a connected directory.

This post uses the stack name ExampleStack, which is located in US East (N. Virginia). Make sure to adapt the naming to meet your needs.

2) Connect AWS SSO to an existing directory

By default, when you first enable AWS Single Sign-On, you’re provided with a default directory for creating users and groups without a need for an Active Directory. To connect to your own Microsoft Active Directory, from the AWS SSO dashboard choose Directory in the left pane. In the details section of the Directory page, choose Change directory.

Important

You can switch directories within AWS SSO at any time. However, doing so removes all existing permissions to AWS accounts and applications that you previously granted to users and groups in AWS SSO.

Next, choose Microsoft AD directory, and select the directory ID of an existing Managed Microsoft Active Directory or Active Directory Connector. Choose Next: Review.

On the Review page, you receive the following warning:

To proceed, type CONFIRM, and then choose Finish.

Once complete, a message stating We have successfully configured your AWS SSO appears with confirmations that assignments were removed and that the existing directory is disconnected and the newly selected directory is connected.

You have now successfully connected your Microsoft Active Directory to AWS SSO.

For more information about how to manage users and groups using AWS SSO, see How to create and manage users with AWS Single Sign-On.

3) Create the AWS SSO Application for AppStream 2.0

First create the AWS SSO application for AppStream 2.0 and download the metadata.

1. From the AWS SSO Dashboard, choose Applications from the left pane.
2. Choose Add a new application.
3. On the Add New Application page, choose Add a custom SAML 2.0 application.
4. Enter a display name. In this example, the display name is AppStream ExampleStack. This name appears in the user portal.
5. Provide an optional description.
6. In the AWS SSO metadata section, choose Download to the right of the AWS SSO SAML metadata file section. This is the metadata file that is used to create the IAM Identity Provider later on in this setup.
7. In the Application Properties section, keep Application start URL as blank, and enter the AppStream 2.0 Relay State URL for ExampleStack.

For example:
https://appstream2.us-east-1.aws.amazon.com/saml?stack=ExampleStack&accountId=012345678910

Click here for instructions to configure the Relay State URL.

8. In the Application metadata section, choose If you don’t have a metadata file, you can manually type your metadata values. Enter the following values:

Application ACS URL: https://signin.aws.amazon.com/saml
Application SAML audience: urn:amazon:webservices

Gov Cloud
Application ACS URL: https://signin.amazonaws-us-gov.com/saml
Application SAML audience: urn:amazon:webservices:govcloud

Note
The Application Assertion Consumer Service (ACS) URL is used to identify where the service provider accepts SAML assertions.

9. Save the Application

At this point, the screen should look similar to the following screenshot. Also, the following message appears:

Configuration for AppStream ExampleStack has been saved. You must configure attribute mappings for SSO to work.

4) Create AppStream 2.0 identity provider

Next, in AWS Identity and Access Management (IAM), create the IAM IdP.

1. Sign in to the IAM console.
2. Choose Identity providers in the left pane.
3. Choose Create Provider.
4. For the Provider Type, choose SAML.
5. Name the provider. In this post, the provider is named AWS_SSO_ExampleStack.
6. For Metadata Document, choose Choose File, and upload the Metadata document that was saved in the section Create the AWS SSO Application for AppStream 2.0, step 6.
7. Choose Next Step, and on the Verify Provider Information page, choose Create.

A message stating that you have finished creating a SAML provider should display.

8. Click on the Identity Provider that was just created AWS_SSO_ExampleStack and note the Provider ARN.

For example, in this post the ARN is:
arn:aws:iam::012345678910:saml-provider/AWS_SSO_ExampleStack

GOV cloud

arn:aws-us-gov:iam::<GovCloudAccount#>:saml-provider/<IDP Name>

5) Create the AppStream 2.0 stack stream access role

Next, create a SAML 2.0 federation IAM role. This establishes the trust relationship between IAM and the Identity Provider (IdP), AWS SSO. Steps to create this role are available here or follow along below.

1. From the IAM console, choose Roles from the left pane.
2. Choose Create Role.
3. Choose the type of trusted entity, and then choose SAML 2.0 federation.
4. Under Choose a SAML 2.0 provider, choose the Identity Provider created previously in the Create AppStream 2.0 Identity Provider section. For this post, use AWS_SSO_ExampleStack.

Do not choose either of the two SAML 2.0 access methods: Allow programmatic access only or Allow programmatic and AWS Management Console access.

5. For Attribute, choose SAML:sub_type.
6. For Value, enter persistent.
7. Choose Next: Permissions.
8. On the Attach permissions policies page, choose Next: Review. Proceed without selecting any policies.
9. Name the role. In this post, the role is named ExampleStack. A description is optional.
10. Choose Create role.

A message stating that the role ExampleStack has been created should display.

11. Click on the role and note the Role ARN

In this post, the Role ARN is:
arn:aws:iam::012345678910:role/ExampleStack

Gov cloud will contain this format
arn:aws-us-gov:iam::<GovCloudAccount#>:role/<your defined Role name>

6) Attach an inline policy to the AppStream 2.0 Stream access role

Next, attach an inline policy to the AppStream 2.0 role. Steps to create the inline policy are available here, or follow along below.

1. From the IAM console, choose Roles in the left hand pane.
2. Click on the role created in the Create AppStream 2.0 Role section of this post, in this post the role was named ExampleStack.
3. On the permissions tab, under Permissions policies, on the right side, choose + Add inline policy.
4. Choose the JSON tab. Replace the JSON with a policy matching the following template below. This template is available here to copy and paste.

For Gov Cloud replace resource in the snippet above with below
“Resources” : “arn:aws-us-gov:appstream:us-gov-west-1:<GovCloudAccount#>:stack/<GovCloudStackName>”

5. In the template above, change the REGION-CODE, ACCOUNT-ID-WITHOUT-HYPHENS, and STACK-NAME. The Stack Name is case sensitive. Below shows the policy for ExampleStack in US East (N. Virginia).

6. Choose Review policy
7. Name the policy, in this post I name it ExampleStackAccess

Note: A message appears that states “This policy does not grant any permissions. To grant access, policies must have an action that has an applicable resource or condition. For details, choose Show remaining.”

This message can be ignored.

8. Choose Create policy

7) Create AWS SSO attribute mappings

With the Identity Provider, IAM Role, and permissions in place, let’s jump back to the AWS SSO console and configure the Attribute Mappings.

1. In the left pane, choose Applications.
2. Choose the application that was created in Create the AWS SSO Application for AppStream 2.0. In this post the application was named AppStream ExampleStack.
3. Choose the Attribute mappings tab.

To find the current attribute mappings, from the AWS SSO dashboard, choose Directory in the left hand pane. Here you’ll see the Attribute Mappings below.

For AppStream 2.0 fleets that are joined to an Active Directory domain, using AWS SSO, Appstream 2.0 requires that the SAML_Subject NameID value for the user who is logging in be provided in the following format:

username@domain.com using the user principal name (UPN).

AWS SSO supports mapping to windowsUPN and this is the default mapping between AWS SSO and Microsoft Active Directory for subject for ${user:email}. This table is also available here.

4. Add the following attributes
—————————————-
User attribute in the application: Subject
Maps to this string value or user attribute in AWS SSO: ${user:email}
Format: persistent
—————————————-
User attribute in the application: https://aws.amazon.com/SAML/Attributes/RoleSessionName
Maps to this string value or user attribute in AWS SSO: ${user:email}
Format: unspecified
—————————————-
User attribute in the application: https://aws.amazon.com/SAML/Attributes/Role
Maps to this string value or user attribute in AWS SSO: arn:aws:iam::012345678910:role/ExampleStack,arn:aws:iam:: 012345678910:saml-provider/AWS_SSO_ExampleStack
Format: unspecified

The format used above for Maps to this string value or user attribute in AWS SSO is:

Role ARN, Identity Provider ARN

Use the ARNs that were noted in previous steps to construct this.
—————————————-

5. Choose Save changes

8) Assign users and test

To test, assign a user from your directory to the application.

1. From the AWS SSO dashboard, choose Applications in the left hand pane.
2. Click on the application that was created, in this post, the application was named AppStream ExampleStack.
3. Choose the Assigned Users tab, then choose Assign users.
4. Choose whether or not to search Groups or Users. Groups is selected by default.
5. Choose Search connected directory.
6. Select the users and choose Assign user.
7. On the AWS SSO dashboard, find the User portal URL and login, for example username testuser@domain.local, and enter the applicable password.
8. Choose the application.

This setup also makes it easy to manage AppStream 2.0 Stack access directly from Active Directory.

1. In Active Directory, first create a Security Group, in this post the group is named AWS-012345678910-ExampleStack.
2. From the AWS SSO dashboard, choose Applications in the left pane.
3. Choose the application to assign the Active Directory security group to, in this post the application was named AppStream ExampleStack.
4. Select the Assigned users tab and select Assign users.
5. With Groups selected, search for the appropriate security group, in this post I named it AWS-012345678910-ExampleStack.
6. Select the box to the left of the security group, and choose Assign users
7. Next I create a test user named TUser1@domain.local and grant group membership to AWS-012345678910-ExampleStack

8. Now, TUser1 and other users assigned to this security group, can login to the AppStream 2.0 ExampleStack, and access can be managed from Active Directory.

9) Using the AWS SSO Directory to manage user access to AppStream 2.0

When AWS SSO is first enabled, by default a custom directory dedicated to AWS SSO is selected. Below, I’ll discuss how to use this directory to manage user access to AppStream 2.0.

Using this directory AppStream 2.0 users can be created and managed using the AWS SSO dedicated directory. While this does not support AppStream 2.0 domain joined fleets, this is a great way to enable users to access their AppStream 2.0 resources using SAML 2.0 without needing an independent directory.

To create users in this directory choose Directory from the left hand pane from the AWS SSO dashboard.

In this example, users are created and assigned to the AppStream 2.0 Example Stack application using a directory group.

On the Users tab, choose Add user.

Complete the user details and choose either to send the user an email with password setup instructions, or generate a one-time password that the user can reset at first login.

Complete the wizard to add the user.

Repeat this process for the users that need AppStream 2.0 stack access.

Next, choose the Groups tab.
Choose Create group. Here the group is named ExampleStack and a description of “AppStream ExampleStack Access” was included.
Choose Create
Next, click on the ExampleStack group and choose Add users.
Select the users that require access to the AppStream 2.0 Example stack and choose Add user(s).

Back on the AWS SSO dashboard, choose Applications in the left hand pane.
Click on the application, in this post the application is named AppStream ExampleStack.
Choose the Assigned users tab and select Assign users
Select the Groups tab, select the ExampleStack group previously created, and select Assign users

You have now successfully created users in the AWS SSO dedicated directory and assigned them to an AppStream 2.0 SAML application in AWS SSO.

The users can now login using the persistent User portal URL and access their AppStream 2.0 session.

Summary

In this post, we enabled federation with AWS Single Sign-On and Amazon AppStream 2.0. While AWS SSO is only available in US East (N. Virginia), federation can be configured targeted AppStream 2.0 resources in any region AppStream 2.0 is supported. Keep in mind, AWS SSO metadata is unique per application. If multiple applications are configured, each will needs its own respective IAM Identity Provider. More information about AppStream 2.0 SAML setup is available here.

About the Author

Matt Guanti is a Cloud Support Engineer at AWS. He specializes in Amazon AppStream 2.0 and Amazon EC2 Windows. Outside of work, Matt enjoys playing golf, taking his dog Toby on adventures, and is an avid fan of The Office.

This blog was updated and co-authored by Ese Alofoje.  Ese is a Cloud Support Engineer II at AWS.  He specializes in Amazon WorkSpaces.  Outside of work, Ese enjoys spending time with his family.