AWS IAM Identity Center (successor to AWS SSO) Integration Guide for Amazon Appstream 2.0
Introduction
This document helps you configure IAM Identity Center to facilitate single sign-on (SSO) for Amazon Appstream 2.0 using SAML.
Topics
Prerequisites
You'll need the following to set up SSO access to Amazon Appstream 2.0:
-
Access to the IAM Identity Center console with permissions to manage applications.
-
An Amazon Appstream 2.0 stack in your AWS account with admin permissions.
Setup instructions
- On the Configure page, in the Details section, fill in the Display name and the Description(optional) of the application.
Note
We suggest that you choose a unique display name if you plan to have more than one of the same application.
- Download the IAM Identity Center SAML metadata file.
-
Under Application metadata, choose If you don't have a metadata file, you can manually type your metadata values. to display the application metadata settings.
-
Insert these values:
Field | Value |
---|---|
Application ACS URL | https://signin.aws.amazon.com/saml |
Application SAML audience | urn:amazon:webservices |
-
Choose Save Changes.
-
Follow the process described here for setting up your Amazon Appstream stack SAML configuration:
6a. Create a SAML Identity Provider in AWS IAM console and upload the IAM Identity Center SAML metadata file downloaded in step 2.
6b. Create a SAML 2.0 Federation IAM Role that establish a trust relationship between IAM and IAM Identity Center.
6c. Embed an Inline Policy for the IAM Role grants federated users access to the Amazon Appstream 2.0 stack.
-
Go back to the IAM Identity Center console page where you are configuring the Application.
-
Choose Edit Configuration. Under Application properties, Insert these values:
Field | Value |
---|---|
Relay State | https://APPSTREAM-REGION-ENDPOINT?stack=STACKNAME&accountId=ACCOUNTID |
Note
You can find the Appstream regional endpoint URL here.
- (Optional) If you want an application from the Amazon Appstream 2.0 stack portal as the default landing page. Insert these values:
Field | Value |
---|---|
Relay State | https://APPSTREAM-REGION-ENDPOINT?stack=STACKNAME&accountId=ACCOUNTID&app=APPLICATIONNAME |
Note
The APPLICATIONNAME is the the name of the published application in the Amazon Appstream 2.0 stack portal. You can also find the Application name in the Image properties or Image Assistant.
-
Choose Save Changes.
-
Choose Attribute Mappings tab. Next to attribute https://aws.amazon.com/SAML/Attributes/Role insert the value below.
Field | Value | Format |
---|---|---|
https://aws.amazon.com/SAML/Attributes/Role | arn:aws:iam::ACCOUNTID:role/ROLENAME,arn:aws:iam::ACCOUNTID:saml-provider/SAMLPROVIDERNAME | unspecified |
- Assign a user to the application in IAM Identity Center.
Verification
Use the following sections to verify the SSO integration.
Note
Ensure that the user performing the verification is logged out of both IAM Identity Center and the application before performing the steps in each section.
Note
Users will not be able to login using SSO unless the user exists in both your directory and Amazon Appstream 2.0, and the user is assigned to the application.
Verifying SSO from IAM Identity Center
-
Access the AWS access portal using the credentials of a user assigned to the Amazon Appstream 2.0 application.
-
In the list of applications, choose Amazon Appstream 2.0 to initiate a login to Amazon Appstream 2.0.
-
If login was successful you will be signed-in to Amazon Appstream 2.0.
Note
Amazon Appstream 2.0 does not support SP initiated flow.
Troubleshooting
If sign in was not successful, please see the troubleshooting steps.
Troubleshooting
Error | Issue | Solution |
---|---|---|
An error occurred when we tried to process your request. | The Application ACS URL specified in the identity provider is incorrect. | Make sure that the ACS URL in IAM Identity Center application matches https://signin.aws.amazon.com/saml. |
Other | When IAM Identity Center creates a SAML Assertion for a user, it uses the value of the 'email' field (if they are present) from the connected directory to populate the 'Email' in the SAML assertion. Many service providers expect these attributes to contain the user’s email address. By default your directory is configured to send 'windowsUPN' in both fields. | Your directory may be configured to contain the users email in the 'Email' attribute instead. If so, you may need to change this in your Connected directory settings. |
For general troubleshooting problems, please refer to Troubleshooting Guide.
User Provisioning Types
There are two user provisioning you need to aware of:
-
Preprovisioned users
Preprovisioned users, means users must already exist in the downstream SaaS application. For instance, you may need to create SaaS users with the same subject as the AD users.
-
JIT users
JIT (or Just-In-Time) users, means users do not necessarily exist in the downstream SaaS application, and will be provisioned/created/registered the first time the user federates. You may need to enable JIT option in your SaaS application for the AD domain.