Using Auth0 with Microsoft Active Directory on Amazon AppStream 2.0

Enterprises are seeking method to offer more secure authentication and a better user experience. Furthermore, they’re required to have centralized user Authentication and Authorization without the need to replicate user credentials and authorization in another Identity provider (IDP).

In previous blog, we showed how to provide users with Single Sign-On (SSO) access to Amazon AppStream 2.0 using existing enterprise credentials as an Active Directory. AppStream 2.0 supports any SAML 2.0-complaint identify provider to setup SSO login to its sessions.

In this blog post, I show you how to setup Auth0 as a SAML 2.0 provider federated with an existing enterprise Active Directory as Single Sign-On to your Amazon AppStream 2.0 sessions.

Auth0 identity and management platform provides greater control, superior security, and ease of use. It provides SSO through a variety of ways including enterprise federation, social login, or username and password authentication. This allows your users to simply login once and use all their applications they have access to.

Overview of solution
I provide a step-by-step guide to configure an Auth0 Active Directory connector that is able to communicate to a corporate Active Directory. I guide you on how to configure Auth0 Applications and SAML assertion rules. Then I shows you how to sign in to your Amazon AppStream 2.0 session using credentials from your corporate Active Directory. Last I provide you some tips to help you debug your configuration.

Reference Architecture Diagram of the solution

Figure 1: Reference Architecture Diagram of the solution

Walkthrough
There are seven steps you’ll need to perform and complete this task:

Step 1: Configure Active Directory connector in Auth0
Step 2: Configure Auth0 to establish a trust relationship with AWS
Step 3: Create a SAML Identity Provider in AWS Identity and Access Management (IAM)
Step 4: Create a SAML 2.0 Federation IAM Role
Step 5: Embed an Inline Policy for the IAM Role
Step 6: Create Assertions for the SAML Authentication Response
Step 7: Add Application Entitlements
Step 8: Test your configuration

Prerequisites
For this walkthrough, the perquisites you need are as follows:

Auth0 account
An AWS account
A provisioned AppStream 2.0 stack joined to a domain. Follow this getting started guide to deploy an AppStream 2.0 stack
Administration access to your domain controller

Step 1: Configure Active Directory connector in Auth0

1. Log in to Auth0 Management Dashboard, then click on Authentication -> Enterprise. Click on Active Directory/LDAP

Available Enterprise Connections in Auth0

Figure 2: Available Enterprise Connections in Auth0

2. Create new connection

3. Add a name to your connection. I use test123 in my example. Then click on Create

4. Install a Windows Agent and keep a copy of the Provisioning Ticket URL

Install Windows Agent

Figure 3: Install Windows Agent

5. With administrator user credentials, log in to your domain controller

6. Install the Auth0 Windows Agent

7. Once the installation is complete, you should see the following screen in a browser pointing to local host:

Active Directory Connector Configuration

Figure 4: Active Directory Connector Configuration

8. Enter the provisioning Ticket URL from Step 4, then Click on Continue

9. Enter your administrator Username as OU\user, where OU is your Organization unit

10. Enter the user Password, then click on Save

Settings configuration to connect to your Active Directory

Figure 5: Settings configuration to connect to your Active Directory

11. Once connection established to Auth0 you should see the following logs at the bottom of the screen

Configuration log status

Figure 6: Configuration log status

12. Switch back to Auth0 console. The connector should be online

Connector Status

Figure 7: Connector Status

By now, your Active directory is connected to Auth0.

Step 2: Configure Auth0 to establish a trust relationship with AWS
1. Log in to Auth0 Management Dashboard, and create a new Application. You can use an existing Application, but in this example I walk through creating a new one. On the Addons tab, enable the SAML2 Web App addon.

Auth0 Applications list

Figure 8: Auth0 Applications list

2. Configure this add-on using the pop-up that appears immediately after you’ve enabled the SAML2 Web App. On the Settings tab, populate Application Callback URL with https://signin.aws.amazon.com/saml and paste the following SAML configuration code in JSON format into Settings:

{
   "audience": "https://signin.aws.amazon.com/saml",
   "mappings": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
      "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
   },
   "createUpnClaim": false,
   "passthroughClaimsWithNoMapping": true,
   "mapUnknownClaimsAsIs": false,
   "mapIdentities": false,
   "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
   "nameIdentifierProbes": [
      "http://schemas.auth0.com/userPrincipalName"
   ]
}

SAML2 Web Application Settings

Figure 9: SAML2 Web Application Settings

3. Scroll to the bottom and click Enable.

4. Click on to the Usage tab. You’ll need to configure Auth0 as the identity provider (IdP) for AWS, which requires you to provide the appropriate metadata to AWS. You can obtain a file containing this information by clicking Identity Provider Metadata.

SAML2 Web Application Usage

Figure 10: SAML2 Web Application Usage

5. Close the SAML2 Web App window, then click over Connections

6. Under Enterprise, select the Active Directory / LDAP connector you created in step1

Active Directory / LDAP selected

Figure 11: Active Directory / LDAP selected

Step 3: Create a SAML Identity Provider in AWS IAM

1. Open the IAM console

2. In the navigation pane, click Identity Providers and then click Create Provider.

3. For Provider Type, click Choose a provider type and click SAML.

4. Type a name for the identity provider.

5. For Metadata Document, click Choose File, specify the SAML metadata document that you downloaded in Step 2, and click Open. Click Next Step.

6. Verify the information that you have provided, and click Create.

Step 4: Create a SAML 2.0 Federation IAM Role

1. Open the IAM console

2. In the navigation pane, choose Roles, Create role.

3. For Role type, choose SAML 2.0 federation.

4. For SAML Provider, select the SAML IdP that you created.

Important

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, type persistent. This step restricts role access to only SAML user streaming requests that include a SAML subject type assertion with a value of persistent. If the SAML:sub_type is persistent, your IdP sends the same unique value for the NameID element in all SAML requests from a particular user. For more information about the SAML:sub_type assertion, see the Uniquely Identifying Users in SAML-Based Federation section in Using SAML-Based Federation for API Access to AWS.

7. Review your SAML 2.0 trust information, confirming the correct trusted entity and condition, and then choose Next: Permissions.

8. On the Attach permissions policies page, choose Next: Tags.

9. (Optional) Type a key and value for each tag that you want to add. For more information, see Tagging IAM Users and Roles.

10. When you’re done, choose Next: Review. You create and embed an inline policy for this role later.

11. For Role name, type a name that helps you identify the purpose of this role. Because various entities might reference the role, you cannot edit the name of the role after it has been created.

12. (Optional) For Role description, type a description for the new role.

13. Review the role details and choose Create role.

14. Select the role you created, then choose Trust relationships, Edit trust relationship.

15. Update the action to allow sts:TagSession

1. Replace the existing Policy document with the following code

2. Update <account_id> with your account ID.

3. Update <saml_provider_name> with the name of your SAML provider.

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Principal": {
            "Federated": "arn:aws:iam:::saml-provider/"
         },
         "Action": [
            "sts:AssumeRoleWithSAML",
            "sts:TagSession"
         ],
         "Condition": {
            "StringEquals": {
               "SAML:sub_type": "persistent"
            }
         }
      }
   ]
}

Step 5: Embed an Inline Policy for the IAM Role
To embed an inline IAM policy for the role that you created

1. In the details for the IAM role that you created, choose the Permissions tab, and then choose Add inline policy. The Create policy wizard starts.

2. In Create policy, choose the JSON tab.

3. Copy and paste the following JSON policy into the JSON window and modify the resource by entering your AWS Region Code, account ID, and stack name. In the following policy, “Action”: “appstream:Stream” is the action that provides your AppStream 2.0 users with permissions to connect to streaming sessions on the stack that you created.

{
   "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}"
            }
         }
      }
   ]
}

Choose value for REGION-CODE and ACCOUNT-ID-WITHOUT-HYPHENS that corresponds to the AWS Region and accont id where your AppStream 2.0 stack exists. Replace STACK-NAME with the name of the stack. Note that this value is case-sensitive, so the case in the stack name that you specify in this policy must match the case in the AppStream 2.0 stack name as it appears in the Stacks dashboard of the AppStream 2.0 management console.

Note: if you choose to add Application Entitlements, there is no need to specify the stackname in Resource. The format of Resource will be as follows:

"Resource": "arn:aws:appstream:REGION-CODE:ACCOUNT-ID-WITHOUT-HYPHENS"
4. When you’re done, choose Review policy. The Policy Validator reports any syntax errors.

Step 6: Create Assertions for the SAML Authentication Response
Create a new Rule in Auth0 for SAML mappings

1. Log in to Auth0 Management Dashboard, then Click on Auth Pipeline->Rules

2. Click CREATE, then </> Empty Rule

3. Give a name to the Rule, then copy-paste the below script in the script window

function(user, context, callback) {
    if (context.clientName === 'App_Name') {
        user.awsRole = 'IAM_arn,saml_provider_arn';
        user.awsRoleSession = user.userPrincipalName;
        context.samlConfiguration.destination = 'https://signin.aws.amazon.com/saml';
        context.samlConfiguration.mappings = {
            'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
            'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession'
        };
    }
    callback(null, user, context);

}

Replace App_Name with the name of the Auth0 App you created in step2. Then replace IAM_arn assigned to user.awsRole with IAM role arn created in step4 and replace saml_provider_arn assigned to user.awsRole with saml provider arn created in step3.

Tip: Since the rule will run for all application you sign in to, it would be best to scope the rule of the application by wrapping the code in a condition eg. if (context.clientName === ‘App_Name‘)

Configure the group attribute

To demonstrate application entitlements using Active Directory groups, we will add a new attribute to SAML configuration mapping as follow:

1. Name: https://aws.amazon.com/SAML/Attributes/PrincipalTag:groups

2. Value: reference to group name in user context.

function(user, context, callback) {
    if (context.clientName === 'App_Name') {
        user.awsRole = 'IAM_arn,saml_provider_arn';
        user.awsRoleSession = user.userPrincipalName;
        user.groups = 'Your_group_name';
        context.samlConfiguration.destination = 'https://signin.aws.amazon.com/saml';
        context.samlConfiguration.mappings = {
            'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
            'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession',
            'https://aws.amazon.com/SAML/Attributes/PrincipalTag:groups': 'group'
        };
    }
    callback(null, user, context);

}

Configure Relay state

The format of the relay state URL is as follows:

https://relay-state-region-endoint?stack=stackname&accountId=aws-account-id-without-hyphens

Get the relay state endpoint for the Regions where AppStream 2.0 is available from this table.

4. Add relay state to your Rule as in this example below:

function(user, context, callback) {
    if (context.clientName === 'App_Name') {
        user.awsRole = 'IAM_arn,saml_provider_arn';
        user.awsRoleSession = user.userPrincipalName;
        user.groups = 'Your_group_name';
        context.samlConfiguration.destination = 'https://signin.aws.amazon.com/saml';
        context.samlConfiguration.RelayState = 'https://appstream2.region-code.aws.amazon.com/saml?stack=stackname&accountId=aws-account-id-without-hyphens';
        context.samlConfiguration.mappings = {
            'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
            'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession',
            'https://aws.amazon.com/SAML/Attributes/PrincipalTag:groups': 'group'
        };
    }
    callback(null, user, context);

}

Choose value for region-code and aws-account-id-without-hyphens that corresponds to the AWS Region and accont id where your AppStream 2.0 stack exists. Replace stackname with the name of the stack. Note that this value is case-sensitive, so the case in the stack name that you specify in this policy must match the case in the AppStream 2.0 stack name as it appears in the Stacks dashboard of the AppStream 2.0 management console

Note: if you choose to add Application Entitlements, there is no need to specify the stackname in RelayState. The format of RelayState will be as follows:

https://relay-state-region-endoint?accountId=aws-account-id-without-hyphens

5. Click on SAVE CHANGES

Step 7: Add Application Entitlements
1. Open AppStream 2.0 console

2. Choose Stacks in the navigation pane.

3. Choose the Stack associated with the fleet that contains the applications you wish to limit.

4. Under Application Entitlements, choose Create.

5. Enter the following:

1. Name: group_team_finance

2. Attribute_name: groups

3. Attribute Value: team_finance

4. Under application settings, choose Select applications

5. Under Applications, choose one or multiple applications in your AppStream 2.0 Stack.

Step 8: Test your configuration
To test your configuration

1. Log in to Auth0 Management Dashboard, then Click on Applications

2. Click on the application that you created in Step2.

3. Click on Addons tab, then SAML2 WEB APP

4. Click on Usage, then use the URL under Identity Provider Login URL

Identity Provider Login URL field

Figure 12: Identity Provider Login URL field

5. Singing screen will show. Use a domain user. There is no need to specify domain\user or user@domain. Enter username with no domain name.

6. After singing, your URL will be automatically redirect to Amazon AppStream 2.0 session

AppStream 2.0 Session

Figure 13: AppStream 2.0 Session

Tips:

To Verify your SAML Assertions and Mappings

1. Log in to Auth0 Management Dashboard, then Click on Applications

2. Click on the application that you created in Step2.

3. Click on Addons tab, then SAML2 WEB APP

4. Click on DEBUG

5. After Success login, the decoded SAML response will be displayed

Decoded SAML response

Figure 14: Decoded SAML response

6. Verify the following response:

a. <saml:subject>

<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">user_email</saml:NameID>

b. <saml:attribute>

Name="https://aws.amazon.com/SAML/Attributes/Role"

Name=https://aws.amazon.com/SAML/Attributes/RoleSessionName

c. <saml:attribute>

Name="https://schemas.auth0.com/UserPrincipalName

The value of this attribute would include user@domain

Conclusion

In this post, you walked through how to configure Auth0 Active Directory connector to enable federate authentication with your corporate Active Directory. As in our case, Amazon AppStream 2.0 is configured to join the corporate Domain to gain access to Amazon FSx as persistence storage.

Similar method could be applied on other SAML 2.0-complaint identify provider. If you have questions or suggestions, please comment below.

Desktop and Application Streaming

Using Auth0 with Microsoft Active Directory on Amazon AppStream 2.0

Resources

Follow