Implement SAML 2.0 authentication for Amazon WorkSpaces by using Auth0 and AWS Managed Microsoft AD - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsTroubleshootingRelated resources

Implement SAML 2.0 authentication for Amazon WorkSpaces by using Auth0 and AWS Managed Microsoft AD

Siva Vinnakota and Shantanu Padhye, Amazon Web Services

Summary

This pattern explores how you can integrate Auth0 with AWS Directory Service for Microsoft Active Directory to create a robust SAML 2.0 authentication solution for your Amazon WorkSpaces environment. It explains how to establish federation between these AWS services to enable advanced features such as multi-factor authentication (MFA) and custom login flows while preserving seamless desktop access through AWS Managed Microsoft AD. Whether you're managing only a handful of users or thousands, this integration helps provide flexibility and security for your organization. This pattern provides the steps for the setup process so you can implement this solution in your own environment.

Prerequisites and limitations

Prerequisites

  • An active AWS account

  • AWS Managed Microsoft AD

  • A provisioned desktop in Amazon WorkSpaces Personal that is associated with AWS Managed Microsoft AD

  • An Amazon Elastic Compute Cloud (Amazon EC2) instance

  • An Auth0 account

Limitations

Some AWS services aren’t available in all AWS Regions. For Region availability, see AWS services by Region. For specific endpoints, see the Service endpoints and quotas page, and choose the link for the service.

Architecture

The SAML 2.0 authentication process for a WorkSpaces client application consists of five steps that are illustrated in the following diagram. These steps represent a typical workflow for logging in. You can use this distributed approach to authentication after you follow the instructions in this pattern, to help provide a structured and secure method for user access.

Workflow for the SAML 2.0 authentication process for a WorkSpaces client application.

Workflow:

  1. Registration. The user launches the client application for WorkSpaces and enters the WorkSpaces registration code for their SAML-enabled WorkSpaces directory. WorkSpaces returns the Auth0 identity provider (IdP) URL to the client application.

  2. Login. The WorkSpaces client redirects to the user’s web browser by using the Auth0 URL.  The user authenticates with their username and password. Auth0 returns a SAML assertion to the client browser. The SAML assertion is an encrypted token that asserts the user’s identity.

  3. Authenticate. The client browser posts the SAML assertion to the AWS Sign-In endpoint to validate it. AWS Sign-In allows the caller to assume an AWS Identity and Access Management (IAM) role. This returns a token that contains temporary credentials for the IAM role.

  4. WorkSpaces login. The WorkSpaces client presents the token to the WorkSpaces service endpoint. WorkSpaces exchanges the token for a session token and returns the session token to the WorkSpaces client with a login URL. When the WorkSpaces client loads the login page. the username value is populated by the NameId value that’s passed in the SAML response.

  5. Streaming. The user enters their password and authenticates against the WorkSpaces directory. After authentication, WorkSpaces returns a token to the client. The client redirects back to the WorkSpaces service and presents the token. This brokers a streaming session between the WorkSpaces client and the WorkSpace.

Note

To set up a seamless single sign-on experience that doesn’t require a password prompt, see the Certificate-based authentication and WorkSpaces Personal in the WorkSpaces documentation.

Tools

AWS services

  • Amazon WorkSpaces is a fully managed virtual desktop infrastructure (VDI) service that provides users with cloud-based desktops without having to procure and deploy hardware or install complex software.

  • AWS Directory Service for Microsoft Active Directory enables your directory-aware workloads and AWS resources to use Microsoft Active Directory in the AWS Cloud.

Other tools

  • Auth0 is an authentication and authorization platform that helps you manage access to your applications.

Epics

TaskDescriptionSkills required

Install the Active Directory LDAP connector in Auth0 with AWS Managed Microsoft AD.

  1. Log in to the Auth0 dashboard and choose Authentication, Enterprise, Active Directory / LDAP. Choose Create a connection.

  2. Provide the name for your Active Directory connection, and then choose Create.

  3. On the Setup tab, download the agent for your operating  system.

    When the installation is complete, your default browser displays a prompt for the ticket URL.

  4. Enter the provisioning ticket URL, which should be unique for your connection string, and then choose Continue.

  5. In the AD LDAP Configuration dialog box, for Username and Password, enter your administrator credentials, and then choose Save.

    When the connection to Auth0 has been established, the configuration log is displayed with a reporting status of OK for all checks.

Cloud administrator, Cloud architect

Create an application in Auth0 to generate the SAML metadata manifest file.

  1. Log in to the Auth0 dashboard and create a new application by following the instructions in the Auth0 documentation.

  2. On the Auth0 dashboard, choose the application name to access its configuration settings. On the AddOns tab, choose SAML2 Web App.

  3. On the Settings tab for the add-on, for Application Callback URL, enter https://signin.aws.amazon.com/saml. This is where the SAML token will send the POST request.

  4. On the Settings tab, in the Settings box, paste the following SAML configuration code in JSON format:

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

  5. Save, and then choose Enable.

  6. Choose the Usage tab, and download the metadata manifest file for the identity provider. This  information is required for the next steps.

  7. Close the SAML2 Web App window.

  8. On the applications screen, choose Connections. Under Enterprise, select the correct Active Directory/LDAP connector and enable it.

Cloud administrator, Cloud architect
TaskDescriptionSkills required

Create a SAML 2.0 IdP in IAM.

To set up SAML 2.0 as an IdP, follow the steps that are outlined in Create a SAML identity provider in IAM in the IAM documentation.

Cloud administrator

Create an IAM role and policy for SAML 2.0 federation.

  1. Create an IAM role for SAML 2.0 federation. For instructions, see step 2 in the instructions for setting up SAML 2.0 for WorkSpaces Personal in the WorkSpaces documentation.

  2. Create an IAM policy and associate it with the role you created in the previous step. For instructions, see step 3 in the instructions for setting up SAML 2.0 for WorkSpaces Personal in the WorkSpaces documentation.

Cloud administrator
TaskDescriptionSkills required

Configure Auth0 and SAML assertions.

You can use Auth0 actions to configure assertions in SAML 2.0 responses. A SAML assertion is an encrypted token that asserts the user’s identity.

  1. Sign in to the Auth0 dashboard. Choose Actions, Library, Create Action, Build from scratch.

  2. Provide the following values and then choose Create.

    Name: Specify a name for the action

    Trigger: Choose Login/Post Login

    Runtime: Choose Node 18

  3. On the next screen, enter the following code:

    exports.onExecutePostLogin = async (event, api) => 
{   if (event.client.name === "Workspace_Saml")
   {     const awsRole = 'arn:aws:iam::030784294031:role/Workspace_Auth0,arn:aws:iam::030784294031:saml-provider/Auth0';
     const awsRoleSession = event.user.sAMAccountName;
     const email = event.user.emails[0];
     api.samlResponse.setDestination('https://signin.aws.amazon.com/saml');
     api.samlResponse.setAttribute('https://aws.amazon.com/SAML/Attributes/Role', awsRole)
     api.samlResponse.setAttribute('https://aws.amazon.com/SAML/Attributes/RoleSessionName', awsRoleSession)
     api.samlResponse.setAttribute('https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email', email)
   } return;
};

  4. Choose Deploy.

This completes the setup of SAML 2.0 authentication for WorkSpaces Personal desktops. The Architecture section illustrates the authentication process after setup.

Cloud administrator

Troubleshooting

IssueSolution

SAML 2.0 authentication issues in WorkSpaces

If you encounter any issues when you implement SAML 2.0 authentication for WorkSpaces Personal, follow the steps and links outlined in the AWS re:Post article on troubleshooting SAML 2.0 authentication.

For additional information about investigating SAML 2.0 errors while accessing WorkSpaces, see:

Related resources