Configuring Amazon WorkSpaces Pools with Okta

Overview

• 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 Okta, perform the majority of the Okta 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 Okta application to use, and a Role containing the permissions it will need.
• Then you will finalize the SAML assertions on the Okta 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.

Okta integration - initial setup

1. In a new tab, open your Okta administration console. Navigate to Applications in the left column. Select the blue Create App Integration button at the top left.
2. Select the SAML 2.0 and Next choices.
3. Provide an App name and optionally, a logo, then selct Next.
4. For step 2 of the wizard, there are several sections to configure. Below are the fields to copy and paste.
   1. General:
      1. Single sign-on URL: https://signin.aws.amazon.com/saml
         1. Leave the Use this for Recipient URL and Destination URL box checked.
      2. Audience URI (SP Entity ID): urn:amazon:webservices
      3. Default RelayState: Paste the URL you constructed here.
      4. Name ID format: Select Persistent.
      5. Application username: Leave this at the default.
      6. Update application username: Leave this at the default.
   2. Attribute Statements: You will need to create 3 attribute statements here with the following values.
      1. Name: https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email
         1. Name Format: Unspecified
         2. Value: user.email
      2. Name: https://aws.amazon.com/SAML/Attributes/RoleSessionName
         1. Name Format: URI Reference
         2. Value: userName
      3. Name: https://aws.amazon.com/SAML/Attributes/SessionDuration
         1. Name Format: Basic
         2. Value: 3600
            1. This is measured in seconds, and can be higher than this - up to a max of 43200. See our SessionDuration SAML Attribute documentation for more information.
5. Scroll to the bottom of the page and choose Next.
6. Choose This is an internal app, and then Finish.

WorkSpaces Pools Directory SAML Configuration

1. In the Okta 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 Okta 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 Okta 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 perit 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 Okta 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. In the Okta administration console, go to your WorkSpaces Pool application in the Applications section.
2. Edit the application, go to to the General tab, expand SAML Settings, and choose the Edit button.
3. Add another attribute statement:
   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.

Assign a user or group

Test your setup

• Launch the WorkSpaces Pools application directly from the list of Okta applications in their Okta dashboard.
• Log into the Pool using the WorkSpaces Client. You will need to enter the Registration Code from the Directory Details tab.

Conclusion