Configuring Amazon WorkSpaces Pools with Entra ID

Overview

Video Walkthrough, Part One

Video Walkthrough, Part Two

High Level Steps

• First, you will begin by creating a WorkSpaces Pool setup
  • Specifically, a WorkSpaces Pool Directory, and then WorkSpaces Pool itself.
• Next, you will create the SAML application in Entra ID, perform the majority of the Entra ID specific steps, and configure the SAML sign in settings on the WorkSpaces Pools Directory.
• Then, you will use AWS Identity and Access Management (or IAM).
  • Specifically, you will set up an Identity Provider for the Entra ID application to use, and a Role containing the permissions it will need.
• Then you will finalize the SAML assertions on the Entra ID application

WorkSpaces Pools Directory Setup

• User identity source:   
  • User access URL: put https://placeholder
  • Leave relay state blank
• Directory Information   
  • Directory name and description: A friendly name, not a Fully Qualified Domain Name. For example, use something like Pools-1.
  • Description can be a friendly placeholder.
• Networking and Security   
  • The Enable internet access box should be unchecked, unless you are deploying the Pool to public subnets. When enabled, this option attaches public IPv4 addresses to the WorkSpaces. In most cases, you should deploy your WorkSpaces in private subnets and use a NAT Gateway or managed security appliance to access the Internet instead of direct public IPv4 addresses.
    • VPC: Select your VPC
    • Subnet 1 and 2: Select your subnets.
    • Security Group: Select a Security Group you would like to attach to your Pools.
• Configuration
  • If your account is enabled for Bring Your Own License, you will need to enable this option. If enabled, this Directory can be used for Windows 10 and 11 images. If not enabled, this Directory cannot be used for Windows 10 and 11 images.
    • This option cannot be switched after creation.
• Active Directory Config   
  • If you would like your WorkSpaces Pool to join an Active Directory environment, this is where you would configure that. This section is optional.
• Streaming properties   
  • If you would like to control settings like clipboard redirection and printer access, this is where you can do so.
• IAM role
  • If you would like to attach an IAM role to the WorkSpaces Pool instances, permitting programmatic access to AWS resources, you can do so here. See our documentation for more information on how to configure an IAM Role that can be used here.

WorkSpaces Pool setup

1. On Step 1, "Onboarding", select I know what workspace options I need for my use case, and then Next.
2. Select Pools under WorkSpace Type, and enter a Name and Description.
3. For Bundle, select a public bundle, or alternatively, a custom bundle with the WSP protocol that you have already prepared. Existing WSP WorkSpaces Personal bundles can be used with Pools.
4. The options in Settings can be left at their default values unless you need to customize them.
5. The Capacity and Scaling section can be left at its defaults for this test, or customized based on your needs. Select Next at the bottom.
6. Then, select the WorkSpace Pool Directory you created previously, and then the orange Create WorkSpace Pool button.
7. Select the Pool you just created, and then Actions, and then Start. While the Pool is starting, you can proceed to the next steps.

Entra ID integration - initial setup

1. Sign into the Microsoft Entra ID administration center.
2. In the left column, under the "Identity" section, expand the "Applications" section and select "Enterprise Applications."
3. Select "New Application" at the top.
4. In the resulting "Browse Microsoft Entra Gallery" screen, you should see "Amazon Web Services (AWS)" at the top, under "Cloud platforms." Select this.
5. On the next screen, select "AWS Single-Account Access." A sidebar on the right will open where you can enter a name for the application. Name your Pools application here, and select "Create" at the bottom of the sidebar.   
   1. Note that each Pool will require its own separate Entra ID Application, so if you are going to have more than one Pool setup, be sure to name this something specific.
6. The Entra ID console will automatically take you to the new application. In the left column, under "Manage", select "Single sign-on."
7. In the "Single sign-on" page, select the "Edit" button next to "Basic SAML Configuration".   
   1. Change the Identifier (Entity ID) section from the default https://signin.aws.amazon.com/saml to urn:amazon:webservices. You can append a number to the end of this line if you have more than one AWS application, for example, urn:amazon:webservices#1 and so on.       
      1. For more information, see the note about configuring multiple identifiers for multiple instances on this Entra documentation page.   
   2. In the Relay State (Optional) field, paste the URL value you constructed at the beginning of this section (which began with https://workspaces.euc-sso).   
   3. Select the Save button and then close the Basic SAML Configuration dialog box.
8. In the "Attributes & Claims" section, select the "Edit" button.
9. There will be four preconfigured items in the Required claim section, and four preconfigured items in the Additional claims section. Select and delete all the "Additional claims" (these will all have schemas.xmlsoap.org in their "Claim Name" column).
10. There will be a pre-existing Required Claim named Unique User Identifier (Name ID). Select this claim and edit it. By default, the Name identifier format will be Email address. Change this to Persistent and select Save in the top left.
11. There will be a pre-existing Required Claim named https://aws.amazon.com/SAML/Attributes/SessionDuration set to a value of 900 by default. This is in seconds, and the default value translates to a 15 minute claim, which you will likely want to adjust. Select this claim and adjust this value to accommodate expected user session times for WorkSpaces Pools. The maximum value is 43200 seconds (12 hours). Save this value after editing it.
12. Select the "Add New Claim" button and add the following claim.    
    1. Claim 1:       
       1. Name: PrincipalTag:Email       
       2. Namespace: https://aws.amazon.com/SAML/Attributes       
       3. Source: Attribute       
       4. Source Attribute: user.mail

Assign Users and Groups

1. In the left column, select "Enterprise Applications" to return to the main Applications section, and then select the application you just created.
2. Under "Manage" in the left column, select "Users and groups".
3. Select "Add user/group" in the top middle of the "Users and groups" console.
4. In the "Add Assignment" panel, under "Users and groups", you will see a link labeled "None Selected", since no users have been assigned yet. Select this link.
5. A dialog box to add users and groups will appear. Select any users and groups you would like to use with the application.
6. After selecting your users and groups, choose the blue Select button at the bottom of the panel, and then the blue Assign button in the left of the panel.

Finalize Pools SAML configuration

1. Navigate to the "My Apps" page of Entra ID.
2. Locate the application that you created. Select the three vertical dots in the top right of the application's pane, and select the "Copy link" button.
3. In the WorkSpaces Directory console, in the Details page for the directory created in the first steps, there is an "Authentication" section. Select the "Edit" button for that section.
4. Paste the value you just copied into this section. It will be in this format: https://launcher.myapps.microsoft.com/api/signin/<app_id>?tenantId=<tenant_id>   
   1. There is a similar "access URL" in the Entra ID application SSO setup page, in the format https://login.microsoftonline.com/<app ID>/saml2. This value will not work for this setup, and if it is used, you will see error AADSTS750054: SAMLRequest or SAMLResponse must be present as query string parameters in HTTP request for SAML Redirect binding.
5. Select the Save button.

WorkSpaces Pools Directory SAML Configuration

1. In the Entra ID configuration for your application, there is a Sign On tab. In that tab, under the SAML 2.0 Settings section, expand the Details and look for the Sign On URL. Copy this URL.
2. Return to the separate browser tab that has the WorkSpaces Pool Directory Details page open. In the second section, Authentication, select the Edit button.
3. Select the Edit SAML 2.0 Identity Provider button.
4. Paste the URL you just copied into the User Access URL field. Leave the Enable SAML 2.0 authentication box checked, and ensure the IdP deep link parameter name is at its default value of RelayState.
5. Select Save, and then return to the details tab for the overall directory.

AWS Identity and Access Management (IAM) Setup

IAM Identity Provider

1. In the Entra ID administration console, open your WorkSpaces Pool application you created previously.
2. In the Sign On tab, load the metadata URL in a new tab.
3. In the resulting XML tab, right select anywhere, and choose Save As.
4. Save this file as metadata.xml to your computer.
   1. Double check that the .xml extension does not get dropped. In Firefox, you will need to save as type All files and manually add the .xml extension to the file name before saving.

1. In a new browser tab, open the AWS IAM Identity Providers console and select Add provider in the top right.
2. Select SAML.
   1. For the Provider name, choose any name you prefer, such as Pools-Demo-1-IdP
   2. Metadata Document: Upload the metadata.xml file saved from the Entra ID console.
3. Choose Add provider to save the settings.
4. You will be returned to the list of identity providers, and you will see a green banner at the top that says <your chosen name> added. You must assign an IAM role to start using this provider. Select the View Provider button to the right of this to open your new Identity Provider's details page.
5. Leave this browser tab open, as you will need to return in a subsequent step.

IAM Role creation

1. In a new browser tab, open the AWS IAM Roles console and choose Create role.
2. Choose SAML 2.0 federation for the role type.
3. For the SAML 2.0-based provider drop down menu, choose the provider you created previously.
   1. Do not choose either "programmatic access" or "programmatic access and console" for the access levels.
   2. For Attribute choose SAML:sub_type
   3. For Value enter persistent
4. On Step 2, add permissions, do not select any polices. Choose Next at the bottom.
5. On Step 3, choose a name, description, and any desired tags, then scroll to the bottom and select Create role.
6. You will be returned to the list of roles, and you will see a green banner at the top that says Role <your chosen role name> created. To the right, you will see a View role button. Select this button to open the details page for the Role.

IAM Role Permission Setup

1. In the IAM Role's details page, under the Permissions tab, select Add Permissions > Create inline policy.
2. Choose JSON, and delete the pre-existing JSON that will be populated.
3. Replace the JSON with the following template.
   1. The first wildcard in the template corresponds to the AWS Region. As a wildcard value, this will permit the role to stream WorkSpaces Pools from any region.
   2. The ACCOUNTID placeholder should be replaced with your account ID.
   3. The second wildcard refers to your WorkSpaces Pool directory ID. As a wildcard, it permits connecting to any Pool.
4. After making any required changes to the example policy, scroll down and select Next to save it.

IAM Role Trust Policy setup

1. In the IAM role's details page, select the Trust relationships tab.
2. Select Edit trust policy.
3. You will need to add the "sts:TagSession" action. You will need to convert the Action section from a single item to an array. The below syntax is what it should look like.
   1. The value on Line 7 is the ARN (Amazon Resource Name) of your IAM Identity Provider. You can copy this ARN from the Identity Provider's details page, which is still open in a prior tab.
4. Select Update policy to save the trust policy and return to the Role's details page.
5. This concludes the IAM setup. Do not close the tab yet, as you will need it in the next section.

Finalize Entra ID Configuration

1. In the IAM Role details page, in the Summary section, you will see an ARN value. Copy this and paste it into your text editor. Then put a comma immediately after it, with no space.
2. In the IAM Identity Provider details page, in the Summary section, you will see an ARN value. Copy this and paste it into your text editor, immediately after the comma.

1. Return to the Entra ID tab you have open, and choose the "Single Sign-on" settings portion in the left column if you are not already there.
2. Select the "Edit" button next to "Attributes & Claims".
3. Modify the pre-existing Role value.
   1. Name: https://aws.amazon.com/SAML/Attributes/Role
      1. Name Format: URI Reference
      2. Value: Paste the string you created in your text editor.
4. Select next and finish to save your settings.

Test your setup

• Launch the WorkSpaces Pools application directly from the list of Entra ID applications in the My Apps dashboard: https://myapps.microsoft.com
• Log into the Pool using the WorkSpaces Client. You will need to enter the Registration Code from the Directory Details tab.

Conclusion