Desktop and Application Streaming

Amazon WorkSpaces SAML 2.0 Federation with Keycloak

In this blog, I discuss how customers can use Keycloak as their Identity Provider (IDP) of choice when implementing SAML 2.0 federation with Amazon WorkSpaces. Keycloak is an open-source solution providing a cost-effective means for customers to use enterprise level IDP features without incurring monthly subscription costs.

With SAML 2.0 authentication, customers can access their Amazon WorkSpaces by authenticating to Keycloak using their default web browser. This feature enables a consistent and familiar experience for customers who authenticate to Keycloak to access enterprise applications within their organization as well as extending the IDP features to Amazon WorkSpaces e.g. multi-factor authentication. Additionally, with SAML 2.0 in place customers should extend its capability by implementing certificate-based authentication to provide customers with a seamless single sign-on experience.

Time to read 20 minutes
Time to complete 2 hours
Learning level 200
Services Used Amazon Workspaces
AWS Directory Service
AWS Identity and Access Management

Overview of solution

This blog details how to build a Keycloak IDP server and how to integrate the Keycloak IDP with Amazon Workspaces for SAML 2.0 Federation. The following figure describes the end-to-end user authentication flow using Keycloak with Amazon WorkSpaces.

Keycloak Architecture Diagram

1 – Registration

    • The WorkSpaces client is launched & the user enters their WorkSpaces registration code for their SAML enabled WorkSpaces directory. The Keycloak IDP URL is returned to the client

2 – Login

    • The WorkSpaces client redirects to the user’s web browser using the Keycloak URL
    • User authenticates with username and password
    • Keycloak returns a SAML assertion to client browser. The SAML assertion is an encrypted token asserting the users identity

3 – Authenticate

    • The client browser will post the SAML assertion to the AWS Sign-In endpoint to validate the SAML assertion
    • AWS Sign-in will allow the caller to assume an IAM role which returns a token containing temporary credentials for the IAM role

4 – WorkSpaces Login

    • The WorkSpaces client presents the token to the AWS WorkSpaces service endpoint
    • The token is exchanged for a session token and returned to the WorkSpaces client along with a login URL
    • The username field is now populated when the WorkSpaces client loads the login page
    • The username value is populated by the NameId value passed in the SAML response

5 – Streaming

    • The end user enters their password & authenticates against the WorkSpaces directory
    • Once authenticated a token is returned to the client
    • The client redirects back to the WorkSpaces service, presents the token and a streaming session is brokered between the WorkSpaces client and the WorkSpace

Note for a seamless single sign-on experience with no password prompt required, see the ‘certificate-based authentication’ section at the end of this article.

Walkthrough

Note, this article describes an on-premise Windows Server OS deployment of Keycloak. For additional deployment options please refer to the Keycloak documentation. The steps to implement this solution are as follows:-

    • Installation and launch of Keycloak
    • Configuring Keycloak for production
      • TLS for secure communication
      • Keycloak hostname
      • Production-grade database
      • Configure Trusted Certificates for outgoing requests
    • Active Directory User Synchronization
    • Configure Keycloak Realm
    • Configure Keycloak Client
    • Configure SAML 2.0 Attributes
    • Assign AD Users to Keycloak Client
    • Certificate-based Authentication (optional)

Prerequisites

    • An AWS account
    • An Identity and Access Management (IAM) user with permissions to create AWS Managed AD, AD Connectors & Amazon Workspaces
    • Familiarity with Amazon Workspaces
    • Familiarity with AWS Directory Services

Installation & Launch of Keycloak

  • Download and install OpenJDK here
  • Download Keycloak binaries here & extract
  • Create a JAVA_HOME system variable pointing at the JDK directory

Configure a Keycloak Console Administrator username and password by creating the following Windows System Variables

KEYCLOAK_ADMIN

KEYCLOAK_ADMIN_PASSWORD

Configuring Keycloak for Production

A Keycloak production environment provides secure authentication and authorization for deployments. These range from on-premise deployments that support thousands of users to deployments that serve millions of users. Below details how to configure the TLS configuration, hostname & production database. The settings are saved to a keycloak.conf configuration file read by the server during Keycloak launch to fetch the configuration settings.

TLS Configuration for Keycloak Inbound Connections

Keycloak continually exchanges sensitive data such as user credentials etc., meaning all communication to and from Keycloak requires a secure communication channel. To prevent several attack vectors, I enable HTTPS for that channel. In order to achieve this there is a requirement to create and bind a TLS Web Server certificate to our Keycloak server. Follow your PKI documentation to generate a Web Server certificate for TLS. In this example I submitted a certificate request against my Microsoft Certificate Authority.

There is a requirement to specify the Certificate & Private Key PEM files in our configuration file in order to encrypt incoming traffic. Please refer to your PKI documentation for details on how to generate the relevant PEM files for both certificate and private key. Once both PEM files are generated, include them in the Keycloak.conf configuration as shown.

Hostname Configuration

Keycloak exposes different endpoints to talk with applications as well as enabling access to the administration console. In order to effectively create a base URL for the various endpoints there is a requirement to set the hostname parameter in the keycloak.conf file. Set the hostname value to the FQDN of your Keycloak server.

Keycloak Production Database

By default, Keycloak uses a local dev-file database which is not suitable for enterprise environments. I will replace this with a production-grade option before deployment. In this example I use MariaDB, a free production-ready open-source MySQL relational database.

    • Download and install MariaDB here
    • Download and install DBeaver here (a free Universal Database Manager)
    • Launch DBeaver, select MariaDB, set root password
    • Expand localhost, right click Databases & Create New Database
    • Provide a name for your database, for example ‘Keycloak_db’
    • Select utf8mb4 for Charset
    • Expand the database, right click Users and Create New User
    • Enter a username, for example ‘kc_user’ & password
    • Click the Check All button to grand necessary privileges
    • Click the Schema Privileges tab and click Check All for both Table Privileges and Other Privileges
    • Click Save & Persist

Configure Trusted Certificates for Outgoing Requests

Using TLS, Keycloak must validate the remote server’s certificate to ensure it’s connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks. The certificates of these remote server’s or the CA that signed these certificates must be put in a truststore. Follow these steps to add the CA cert to the truststore: –

    • Export your CA Root Certificate in DER X.509 format
    • Launch a command window and move to the JDK\bin folder
      C:\Program Files\Java\jdk-21\bin
    • Enter the following command to import the root certificate into the Java Keystore:

keytool -import -noprompt -trustcacerts -alias MYROOTCERTIFICATE -file "C:\temp\rootcert.cer" -keystore "C:\Program Files\Java\jdk-21\lib\security\cacerts"

Active Directory User Synchronization

Keycloak includes an LDAP/AD provider which provides a means to import users from Active Directory into the local Keycloak user database. This copy of the user database synchronizes on-demand or through a periodic background task. For AD synchronization to work there is a requirement to establish an LDAP bind to Active Directory. From the Keycloak Admin Console select the AWS Realm created earlier and set up the LDAP bind configuration as follows: –

  • Click User federation & Add Ldap providers
  • For Connection URL enter the URL to your Domain Controller in the form LDAPS://dc.mydomain.local
  • For Bind type select simple
  • For Bind DN enter the AD distinguished name for a user with permissions to bind to your Active Directory & enter password
  • Test connection & authentication to confirm connectivity and successful LDAP bind
  • Set the LDAP searching and updating parameters as shown below (replacing Users DN accordingly)

Synchronize Users

  • To synchronize users into the Keycloak database set the following parameters under Synchronization settings as shown below. Note once users have been imported into the Keycloak database, change the Full sync period to a larger value as appropriate.

  • Lastly, to ensure the sAMAccountName is passed as expected in the Keycloak SAML response, create a User Federation Mapper as with the parameters below. In this example the name of the mapper is a combination of saml.persistent.name.id.for. + Keycloak client name (created in upcoming steps).

Example: saml.persistent.name.id.for.urn.amazon.webservices

Configure Keycloak Realm

A realm is a space where you manage objects, including users & clients. In this example a new realm ‘AWS’ is created that will host our Keycloak WorkSpaces client.

  • Go to the URL for the Admin Console, log in with the username and password created through environment variables earlier
  • Initial log in will land on the Master realm, click the drop-down menu and Create Realm
  • Enter AWS as the name for the realm, click Create

Configure Keycloak Client

A Keycloak client is comparable to a SAML 2.0 enterprise application in other enterprise Identity Providers. We Cconfigure our SAML configuration via the Keycloak client.

  • Switch to the AWS realm just created from the drop-down menu
  • Click Clients and Create Client
  • Client type = “SAML”
  • Client ID = urn:amazon:webservices
  • Name = Workspaces
  • Description = provide a description of your choice

  • Click Next
  • Enter the values as shown below in the Login Settings screen
  • Note the IDP Initiated SSO Relay State URL is unique per customer account as per our documentation

  • For SAML capabilities set the values as shown below :-

  • Under Signature and Encryption set the properties as shown below:-

Configure SAML 2.0 Attributes

Next, we set the SAML attributes as documented in the Workspaces Admin Guide.

  • Navigate to the Client Scopes tab, select the urn:amazon:webservices-dedicated scope
  • From the Mappers tab select Configure a new mapper
  • Select Hardcoded attribute
  • Set the values for the Role attribute as shown below

Note the Attribute value is unique per AWS account and takes the form
arn:aws:iam::ACCOUNTNUMBER:role/ROLENAME,arn:aws:iam::ACCOUNTNUMBER:saml-provider/PROVIDERNAME

  • Create another mapper of type User Attribute with name ‘https://aws.amazon.com/SAML/Attributes/RoleSessionName’ and set the value shown below.

  • Create another mapper of type User Attribute with name ‘https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email’ and set the value shown below.

  • Upon completion you should have three attribute values configured for the Keycloak client as shown.

Note if there is a requirement to use WorkSpaces certificate-based authentication, please add the additional attribute, PrincipalTag:UserPrincipalName. This is a requirement for certificate-based authentication.

Create AWS IAM SAML Identity Provider & Role

When federating with SAML 2.0 from an IDP like Keycloak, there is a requirement to establish a trust between the IDP and AWS. This is achieved by creating an AWS IAM Identity Provider. With an IAM Identity Provider in place on the AWS side it enables customers to map a Keycloak user to an AWS IAM Role thereby providing the necessary permissions to stream traffic to & from the WorkSpaces directory in your account. Keycloak specific details on how this is configured are detailed in the Amazon WorkSpaces SAML Guide.

Assign AD Users to Keycloak Client

With the Keycloak client configured and our Active Directory users synchronized into the Keycloak database. Assign users to the Keycloak client to provide authorization and authentication. User authorization to Keycloak clients is achieved by creating a Role, assigning users to the role and assign the role to the Keycloak client as detailed below.

  • Create a Role by selecting Realm Roles , Create Role, give the role a name e.g. Amazon WorkSpace Role and click Save
  • Once the role has been created, add users to the role via the Users console
  • Select Users, search for and select a target user in your directory
  • From the Role mapping tab, click Assign role and select the role created

Enable SAML 2.0 Integration on your Amazon WorkSpaces directory

With the Keycloak configuration in place, enable SAML integration on the Workspaces directory as detailed in Step 5 in the Amazon WorkSpaces SAML Guide.

Federating to Amazon WorkSpaces via Keycloak client

With all the configuration now in place, end users can now connect via the Keycloak Home URL that can be copied and distributed across your organization.

In this example: https://keycloak.euc.local:8443/realms/aws/protocol/saml/clients/Workspaces

End users can now federate and connect to their Amazon WorkSpace by launching the Amazon WorkSpaces client that will initiate the authentication flow as shown.

Certificate-based Authentication

The above SAML 2.0 authentication flow requires users to enter credentials when challenged at their IDP. Additionally, users must enter a password a second time for Kerberos authentication against Active Directory. Customers now have the capability to remove the second logon prompt for the Active Directory domain password by configuring certificate-based authentication.

Certificate-based authentication (CBA) provides a single sign-on experience for the end user removing the “double hop” authentication flow.

To issue private certificates for CBA, you can use an existing public key infrastructure (PKI) or use AWS Private Certificate Authority (AWS Private CA). AWS Private CA is a highly available, fully managed private certificate authority service you can use to create CA hierarchies, and issue private X.509 certificates. The recommendation for CBA is to use short-lived private certificates that can be used to authenticate a user and then expire shortly afterward.

Conclusion

This blog demonstrates how customers can build a Keycloak server as a SAML 2.0 Identity Provider for federating to Amazon WorkSpaces. There are no additional charges for using SAML 2.0 authentication with Amazon WorkSpaces. SAML 2.0 authentication is available in all AWS Regions where WorkSpaces is offered, including AWS GovCloud (US-West). End users are able to access their WorkSpaces with SAML 2.0 authentication by using the latest WorkSpaces client application versions for Windows and macOS and the Web Access Client. Learn how to get started with WorkSpaces SAML 2.0 integration by visiting the WorkSpaces Administration Guide.

Peter Fergus is a Senior Specialist Solutions Architect based in Dublin, Ireland. Pete has been working with AWS cloud computing services for more than five years and enterprise infrastructure for over fifteen. Pete is passionate about collaborating with customers to help build optimal EUC solutions in AWS Cloud.