SAML Federation to AWS AppStream

Why Federate Users to AppStream?

The idea of AppStream is to allow individual users (usually, external users, such as students) to access their own version of an app (their own appstream). Since there are multiple external users, it makes sense to federate their identities to AWS AppStream. Fortunately, this federation can be done on a per-stack basis (a stack is a set of apps).

To set up federation from GSuite

While AWS has a step by step guide for federating (to appStream) from various identity stores, you may encounter a few gotchas while trying to set up gSuite federation to Appstream.

This post summarizes some of these potential gotchas.

Step by Step guide for gSuite to AppStream federation

The exact steps for setting up gSuite to appStream federation can be found here. Based on the steps outlined there, these are some potential sources of confusion.

Step 1 – Relay State URL

AWS Region based relay endpoints – https://docs.aws.amazon.com/appstream2/latest/developerguide/external-identity-providers-setting-up-saml.html#external-identity-providers-relay-state

e.g. working relaystate URL –  https://appstream2.us-east-1.aws.amazon.com/saml?stack=STACKID&accountId=ACCTID-NO-HYPHENS

Step 3 – Custom Federation Role

Custom Role in AWS –> And also add a custom inline policy as shown below

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appstream:Stream",
"Resource": "arn:aws:appstream:us-east-1:881451466749:stack/HPRHS",
"Condition": {
"StringEquals": {
"appstream:userId": "${saml:sub}" 
}
}
}
]
}

Step 5: Add custom SAML attribute mappings

Navigate to the newly created SAML app. Choose Main menu, Apps, SAML Apps and select the newly created application.

Choose Attribute Mapping, Add New Mapping, add three mappings as defined below, and then choose Save.

In GSuite Custom Attributes, you should see the two custom attributes created in Step 4 (FederationRole and SessionDuration). PLUS, you will need the third attribute PRIMARY EMAIL.

• GSuite – FederationRole –> RHS Application attribute — https://aws.amazon.com/SAML/Attributes/Role
• GSuite – SessionDuration –> RHS Application attribute – https://aws.amazon.com/SAML/Attributes/SessionDuration
• GSuite – Primary Email –> RHS  – https://aws.amazon.com/SAML/Attributes/RoleSessionName

Step 1: Create a SAML 2.0 application in the G Suite management console

Log in into your G Suite admin console using your admin account and choose Apps, SAML Apps. 

Choose the plus icon (+) to create a new SAML application and choose SETUP MY OWN CUSTOM APP.

Download the IdP metadata and save it locally. You use this file in Step 2 to create the AWS IdP. Choose Next.

Provide a name for your SAML 2.0 application, description, and an optional logo to easily identify the application in the user login portal. After entering the inputs, choose Next. 

Provide the following input for various fields and then choose Next.

• ACS URL — https://signin.aws.amazon.com/saml
• Entity ID — urn:amazon:webservices.
  This is a parameter used by AWS (the service provider) to uniquely identify the SAML application. Every stack is configured as a SAML application in G Suite. You need to have a unique entity ID value for every AppStream 2.0 SAML application. To do so, just add a numerical counter as a suffix to this value. For example:
  • Stack1 app Entity ID – urn:amazon:webservices
  • Stack2 app Entity ID – urn:amazon:webservices1
  • Stack3 app Entity ID – urn:amazon:webservices2
• Start URL —Relay state URL of your AppStream 2.0 stack. For more information, see Step 6: Configure the Relay State of Your Federation.
  • e.g. relaystate URL https://appstream2.us-east-1.aws.amazon.com/saml?stack=STACKID&accountId=ACCTID-NO-HYPHENS
• Signed Response — Leave it unchecked.
• Name ID — Basic Information, Primary Email.
• Name ID Format — Persistent.

 

Skip the next page, Attribute Mapping, and choose Finish.

Step 2: Create an AWS SAML IdP in IAM

You need an IdP created in IAM. This IdP defines your organization’s IdP-to-AWS trust relationship using the metadata document generated by the IdP software in your organization. For more information and instructions, see Creating and Managing a SAML Identity Provider (AWS Management Console).

For the IdP metadata, use the metadata file downloaded earlier from the G Suite console. After you create the IdP, note the IdP ARN available from the details page. You need it later.

Step 3: Create an IAM federation role

You need an IAM role to provide users with the permissions to access an AppStream 2.0 stack. The permissions defined in this IAM role dictate the stacks to which the federating users have access.

You can choose to provide permissions to all stacks in your AWS account or individually list the stacks that can be accessed by the user assuming this role on federation.  After you create the IAM role, note the role ARN available from the details page. You need it later.

For more information and instructions, see Step 2: Create a SAML 2.0 Federation IAM Role and Step 3: Embed an Inline Policy for the IAM Role.

Step 4: Create a custom user attribute category in the G Suite admin console

Navigate to the users dashboard by choosing Directory, Users.
From the top right corner in the Users dashboard, choose Manage User Attributes, Add Custom Category.

Provide a name for the category and a description, add the SAML attributes as defined below, and then choose Add.

• Attribute name — FederationRole, Text, Visible to admin, Single Value
• Attribute name — SessionDuration, Text, Visible to admin, Single Value

Summary

While AWS’ step by step guide is helpful, there were a few areas where I encountered missing or outdated documentation – especially around the custom SAML attribute mappings.

Next Steps?

Need help with your AppStream efforts? Start the conversation today.  

Need an experienced AWS/GCP/Azure Professional to help out with your Public Cloud Strategy? Set up a time with Anuj Varma.