Desktop and Application Streaming

Enabling Federation with SimpleSAMLphp and Amazon AppStream 2.0

SimpleSAMLphp is an open-source project written in native PHP that deals with authentication for SAML 2.0 as a Service Provider and as an Identity Provider.

You can use single sign-on with Amazon AppStream 2.0 with many identity services that are compliant with Security Assertion Markup Language 2.0 (SAML 2.0). This post explains how to configure federated user access for Amazon AppStream 2.0 for customers already using SimpleSAMLphp.

If you are not using SimpleSAMLphp, you can review the AppStream 2.0 Administration Guide for configuring AWS Single Sign-On (SSO) and other third-party SAML 2.0 identity provider solutions that work with AppStream 2.0.

Overview of solution

This post shows configuring an SAML 2.0 federation, using SimpleSAMLphp. The steps to proceed through this post are:

  1. Create a SAML 2.0 Identity Provider
  2. Configure an IAM Policy
  3. Create an IAM Role
  4. Configure SimpleSAMLphp with AppStream 2.0 as a service provider
  5. Create assertions for the SAML authentication response
  6. Create a relay state URL to direct users to AppStream 2.0 stack

Walkthrough

This walkthrough will guide you through the steps needed to authenticate to an Amazon AppStream 2.0 Stack with SimpleSAMLphp.

Prerequisites:

This post assumes that you have the following:

  • SimpleSAMLphp already configured and deployed with your identity provider.
  • Familiarity with Amazon AppStream 2.0
  • Familiarity with SAML 2.0

Step 1: Create a SAML 2.0 Identity Provider

Create the SAML provider in the IAM console. You can also create it using the AWS Command Line Interface (AWS CLI). For more information, see the Setting Up SAML page in the AppStream 2.0 Developer Guide.

  1. In the IAM console, choose Identity providers, Add provider.
  2. On the Add an Identity Provider page, for the Provider Type, choose SAML.
  3. For the Provider Name, type something meaningful to you, such as SimpleSAML.
  4. Choose Choose File to upload the metadata document from SimpleSAMLphp. You can get the metadata from http://<your_domain>/simplesaml/saml2/idp/metadata.php?output=xhtml. Copy the XML format and save it to a file.
  5. Verify the provider information, and choose Add provider.
  6. Choose the identity provider (IdP) that you created to get the Provider ARN of the IdP. The ARN is required to configure claims rules later in this post. The ARN is in the following format:

arn:aws:iam::AccountID:saml-provider/Provider Name

Step 2: Configure an IAM Policy

Next, create a policy with permissions to the AppStream 2.0 stack. This makes sure that users have only the permission to stream applications from a specific stack.

1. In the IAM console, choose Policies, Create Policy, and choose to the JSON tab.

The following example policy gives users permissions to an AppStream 2.0 stack.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "appstream:Stream",
            "Resource": "arn:aws:appstream:<region_code>:<account_id>:stack/<stack_name>",
            "Condition": {
                "StringEquals": {
                    "appstream:userId": "${saml:sub}"
                }
            }
        }
    ]
}

2. Update the policy with the following changes:

a. Replace <region_code> with your region code. Use one of the following values based on the AWS Region your AppStream 2.0 stack is in.
b. Replace <account_id> with your account id without spaces or dashes.
c. Replace <stack_name> with your case sensitive stack name.

For more information, see the Setting Up SAML page in the AppStream 2.0 Admin Guide.

3. After you’ve specified the policy, choose Next: Tags.

4. Add any optional tags. Choose Next: Review.

5. For the Name, enter a descriptive name, such as AppStream2_ExampleStack.

6. For the Description, enter an optional description.

7. Choose Create Policy and you should see a notification that it has been created.

Step 3: Create an IAM Role

Next, create the role that your SimpleSAMLphp users assume when federating to AppStream 2.0.

  1. In the IAM console, choose Roles, Create role.
  2. For the trusted entity type, choose SAML 2.0 federation.
  3. Under SAML provider, choose the SAML IdP that you created earlier.
  4. Do not choose either of the two SAML 2.0 access level methods for AppStream 2.0.
  5. For the Attribute, choose SAML:aud and Value enter https://signin.aws.amazon.com/saml
  6. Do not add any conditions.
  7. Choose Next, Permissions.
  8. Choose the IAM policy you created in Step 2. Choose Next: Tags.
  9. Add any optional tags. Choose Next: Review.
  10. Enter a Role Name and Role Description that identifies the role, and choose Create Role.
  11. Copy the Role ARN. The ARN is required to configure claims rules later in this post. The ARN is in the following format:

arn:aws:iam::AccountID:role/Role Name

Step 4: Configure SimpleSAMLphp with AppStream 2.0 as a service provider

Next, Configure AppStream 2.0 as a service provider in SimpleSAMLphp using the AWS SSO SAML metadata.

  1. Save the AWS SSO SAML metadata from the following link. https://signin.aws.amazon.com/static/saml-metadata.xml.
  2. Use the built in XML to SimpleSAMLphp metadata converter. http://<your_domain>/simplesaml/admin/metadata-converter.php. Select the file and choose Parse.
  3. On your SimpleSAMLphp server, open saml20-sp-remote.php in a text editor and append the converted metadata. The file is located /<install_dir>/simplesamlphp/metadata/saml20-sp-remote.php
  4. Save the saml20-sp-remote.php file.

Step 5: Create assertions for the SAML authentication response

Next, configure an authentication processing filter to add attributes for the Role and RoleSessionName. The Auth Proc Filters can be set in multiple locations. For more information refer to the SimpleSAMLphp documentation.

  1. On your SimpleSAMLphp server, open saml20-sp-remote.php in a text editor. The file is located /<install_dir>/simplesamlphp/metadata/saml20-sp-remote.php
  2. In the $metadata['urn:amazon:webservices'] section, after ‘saml20.sign.assertion’ => true, add the following authproc
'authproc' => array(
        10 => array(
            'class' => 'core:AttributeAdd',
            'https://aws.amazon.com/SAML/Attributes/Role' => array(
                'arn:aws:iam::<account_id>:role/<role_name>,arn:aws:iam::<account_id>:saml-provider/<identity_provider_name>
            ),
        ),
        20 => array(
            'class' => 'core:AttributeAdd',
            'https://aws.amazon.com/SAML/Attributes/RoleSessionName' => array(
                'SomeString'
            ),
        ),
        30 => array(
            'class' => 'saml:AttributeNameID',
            'attribute' => 'eduPersonPrincipalName',
            'Format' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
            ), 
        ),

3. Update the value of the Role Attribute to be <arn_of role,arn_of_identity_provider>. Update the filter with the following changes:

    1. Replace <account_id> with your account id without spaces or dashes
    2. Replace <role_name> with your role name created in Step 3.
    3. Replace <identity_provider_name> with your identity provider name created in Step 1.
    4. For ‘eduPersonPrincipalName’, replace with the attribute to return the format of “domain\username” or username@domain.com. For more information, see the AppStream 2.0 Administration Guide.

4. Save the saml20-sp-remote.php file.

Step 6: Create a relay state URL to direct users to AppStream 2.0 stack

In order to direct the user to the AppStream 2.0 Stack, we need to create a relay state. Without a relay state, the user would be authenticated and directed to the AWS Console.

  1. Create a Relay State URL. The format of the relay state URL is as follows:

https://<relay_state_region_endpoint>?stack=<stack_name>&accountId=<account_id>

Update the relay state URL with the following changes:

a. Replace <relay_state_region_endpoint> with region specific endpoint where your AppStream 2.0 Stack is provisioned. For more information, visit
Configure the Relay State of Your Federation.
b. Replace <stack_name> with your case specific stack name
c. Replace <account_id> with your account id with no spaces or dashes

  1. Next the relay state must be URL encoded. There are many tools online to accomplish this like https://www.url-encode-decode.com/
  2. Update the IdP-first URL. The URL is as follows: http://<your_domain>/simplesaml/saml2/idp/SSOService.php?spentityid=urn:amazon:webservices
    a. Replace <your_domain> with the domain to your SimpleSAMLphp server.
  3. Now combine the IdP URL with the service provider and also specify a RelayState parameter for the SP. An example is provided below:http://sso.example.com/simplesaml/saml2/idp/SSOService.php?spentityid=urn:amazon:webservices&RelayState=https%3A%2F%2Fappstream2.us-east-1.aws.amazon.com%2Fsaml%3Fstack%3DExampleStack%26accountId%3D01234567890

Conclusion

In this post, we enabled federation with SimpleSAMLphp and Amazon AppStream 2.0. For more information on AppStream 2.0 Integration with SAML 2.0, or documentation on other third-party SAML 2.0 identity provider solutions visit the Administration Guide.