Setting up SAML 2.0

1. Configure your IdP to integrate user identities from the Microsoft Active Directory that is used with the WorkSpaces directory. For a user with a WorkSpace, the sAMAccountName and email attributes for the Active Directory user and the SAML claim values must match for the user to sign in to WorkSpaces using the IdP. For more information about integrating Active Directory with your IdP, consult your IdP documentation.

2. Configure your IdP to establish a trust relationship with AWS.

   • See Integrating third-party SAML solution providers with AWS for more information on configuring AWS federation. Relevant examples include IdP integration with AWS IAM to access the AWS management console.

   • Use your IdP to generate and download a federation metadata document that describes your organization as an IdP. This signed XML document is used to establish the relying party trust. Save this file to a location that you can access from the IAM console later.

3. Create or register a directory for WorkSpaces by using the WorkSpaces management console. For more information, see Manage directories for WorkSpaces. SAML 2.0 authentication for WorkSpaces is supported for the following directory types:

   • AD Connector

   • AWS Managed Microsoft AD

4. Create a WorkSpace for a user who can sign in to the IdP using a supported directory type. You can create a WorkSpace using the WorkSpaces management console, AWS CLI, or WorkSpaces API. For more information, see Launch a virtual desktop using WorkSpaces.

To create an IAM role for SAML IdP

1. Open the IAM console at https://console.aws.amazon.com/iam/.

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

   Don't choose either of the two SAML 2.0 access methods, Allow programmatic access only or Allow programmatic and Amazon Web Services Management Console access.

5. For Attribute, choose SAML:sub_type.

6. For Value enter persistent. This value restricts role access to 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) Enter 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'll create and embed an inline policy for this role later.

11. For Role name, enter a name that identifies the purpose of this role. Because multiple entities might reference the role, you can't edit the role's name once it is created.

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

13. Review the role details and choose Create role.

14. Add the sts:TagSession permission to your new IAM role's trust policy. For more information, see Passing session tags in AWS STS. In your new IAM role's details, choose the Trust relationships tab, and then choose Edit trust relationship*. When Edit Trust Relationship policy editor opens, add the sts:TagSession* permission, as follows:

    
    {
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:saml-provider/IDENTITY-PROVIDER"
            },
            "Action": [
                "sts:AssumeRoleWithSAML",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "SAML:aud": "https://signin.aws.amazon.com/saml"
                }
            }
        }]
    }    
                   

1. In the details for the IAM role that you created, choose the Permissions tab, and then add required permissions to the role's permissions policy. The Create policy wizard will start.

2. In Create policy, choose the JSON tab.

3. Copy and paste the following JSON policy into the JSON window. Then, modify the resource by entering your AWS Region Code, account ID, and directory ID. In the following policy, "Action": "workspaces:Stream" is the action that provides your WorkSpaces users with permissions to connect to their desktop sessions in the WorkSpaces directory.

   
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "workspaces:Stream",
               "Resource": "arn:aws:workspaces:REGION-CODE:ACCOUNT-ID-WITHOUT-HYPHENS:directory/DIRECTORY-ID",
               "Condition": {
                   "StringEquals": {
                       "workspaces:userId": "${saml:sub}"
                   }
               }
           }
       ]
   }
                  

   Replace REGION-CODE with the AWS Region where your WorkSpaces directory exists. Replace DIRECTORY-ID with the WorkSpaces directory ID, which can be found in the WorkSpaces management console. For resources in AWS GovCloud (US-West) or AWS GovCloud (US-East), use the following format for the ARN: arn:aws-us-gov:workspaces:REGION-CODE:ACCOUNT-ID-WITHOUT-HYPHENS:directory/DIRECTORY-ID.

4. When you're done, choose Review policy. The Policy Validator will report any syntax errors.

To enable integration with SAML 2.0

1. Open the WorkSpaces console at https://console.aws.amazon.com/workspaces/.

2. In the navigation pane, choose Directories.

3. Choose on the Directory ID for your WorkSpaces.

4. Under Authentication, choose Edit.

5. Choose Edit SAML 2.0 Identity Provider.

6. Check Enable SAML 2.0 authentication.

7. For the User Access URL and IdP deep link parameter name, enter values that are applicable to your IdP and the application you have configured in Step 1. The default value for the IdP deep link parameter name is “RelayState“ if you omit this parameter. The following table lists user access URL and parameter names that are unique to various identity providers for applications.

   Domains and IP addresses to add to your allow list
   Identity provider	Parameter	User access URL
   ADFS	RelayState	https://<host>/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID=<relaying-party-uri>
   Azure AD	RelayState	https://myapps.microsoft.com/signin/<app_id>?tenantId=<tenant_id>
   Duo Single Sign-On	RelayState	https://<sub-domain>.sso.duosecurity.com/saml2/sp/<app_id>/sso
   Okta	RelayState	https://<sub_domain>.okta.com/app/<app_name>/<app_id>/sso/saml
   OneLogin	RelayState	https://<sub-domain>.onelogin.com/trust/saml2/http-post/sso/<app-id>
   PingFederate	TargetResource	https://<host>/idp/startSSO.ping?PartnerSpId=<sp_id>
   PingOne for Enterprise	TargetResource	https://sso.connect.pingidentity.com/sso/sp/initsso?saasid=<app_id>&idpid=<idp_id>

   The user access URL is usually defined by the provider for unsolicited IdP-initiated SSO. A user can enter this URL in a web browser to federate directly to the SAML application. To test the user access URL and parameter values for your IdP, choose Test. Copy and paste the test URL to a private window in your current browser or another browser to test the SAML 2.0 logon without disrupting your current AWS management console session. When IdP-initiated flow opens, you can register your WorkSpaces client. For more information, see Identity provider (IdP)-initiated flow.

8. Manage fallback settings by checking or unchecking Allow clients that do not support SAML 2.0 to login. Enable this setting to continue providing your users access to WorkSpaces using client types or versions that do not support SAML 2.0 or if users need time to upgrade to the latest client version.

   Note

   This setting allows users to bypass SAML 2.0 and log in using directory authentication using older client versions.

9. To use SAML with the web client, enable Web Access. For more information, see Enable and configure Amazon WorkSpaces Web Access.

   Note

   PCoIP with SAML is not supported on Web Access.

10. Choose Save. Your WorkSpaces directory is now enabled with SAML 2.0 integration. You can use the IdP-initiated and client application-initiated flows to register WorkSpaces client applications and sign in to WorkSpaces.