Certificate-based authentication - Amazon WorkSpaces

Certificate-based authentication

You can use certificate-based authentication with WorkSpaces to remove the user prompt for the Active Directory domain password. By using certificate-based authentication with your Active Directory domain, you can:

  • Rely on your SAML 2.0 identity provider to authenticate the user and provide SAML assertions to match the user in Active Directory.

  • Enable a single sign-on logon experience with fewer user prompts.

  • Enable passwordless authentication flows using your SAML 2.0 identity provider.

Certificate-based authentication uses AWS Private CA resources in your AWS account. AWS Private CA enables creation of private certificate authority (CA) hierarchies, including root and subordinate CAs. With AWS Private CA, you can create your own CA hierarchy and issue certificates with it for authenticating internal users. For more information, see the AWS Private Certificate Authority User Guide.

When using AWS Private CA for certificate-based authentication, WorkSpaces will request certificates for your users automatically during session authentication. Users are authenticated to Active Directory using a virtual smart card provisioned with the certificates.

Certificate-based authentication is supported with Windows WorkSpaces on WorkSpaces Streaming Protocol (WSP) bundles using the latest WorkSpaces Windows and macOS client applications. Open Amazon WorkSpaces Client downloads to find the latest versions:

  • Windows client version 5.5.0 or later

  • macOS client version 5.6.0 or later


Complete the following steps before enabling certificate-based authentication.

  1. Configure your WorkSpaces directory with SAML 2.0 integration to use certificate-based authentication. For more information, see WorkSpaces Integration with SAML 2.0.

  2. Configure the userPrincipalName attribute in your SAML assertion. For more information, see Create Assertions for the SAML Authentication Response.

  3. Configure the ObjectSid attribute in your SAML assertion. This is optional to perform strong mapping to the Active Directory user. Certificate-based authentication will fail if the attribute does not match the Active Directory security identifier (SID) for user specified in the SAML_Subject NameID. For more information, see Create Assertions for the SAML Authentication Response.

  4. Add the sts:TagSession permission to your IAM role trust policy used with your SAML 2.0 configuration if it is not already present. This permission is required to use certificate-based authentication. For more information, see Create a SAML 2.0 Federation IAM Role.

  5. Create a private certificate authority (CA) using AWS Private CA if you do not have one configured with your Active Directory. AWS Private CA is required to use certificate-based authentication. For more information, see Planning your AWS Private CA deployment and follow the guidance to configure a CA for certificate-based authentication. The following AWS Private CA settings are the most common for certificate-based authentication use cases:

    1. CA type options:

      1. Short-lived certificate CA usage mode (recommended if you are only using the CA to issue end user certificates for certificate-based authentication)

      2. Single level hierarchy with a Root CA (alternatively, choose a subordinate CA if you want to integrate with an existing CA hierarchy)

    2. Key algorithm options: RSA 2048

    3. Subject distinguished name options: Use any combination of options to identify the CA in your Active Directory Trusted Root Certification Authorities store.

    4. Certificate revocation options: CRL distribution


      Certificate-based authentication requires an online CRL distribution point accessible from desktops and the domain controller. This requires unauthenticated access to the Amazon S3 bucket configured for Private CA CRL entries, or a CloudFront distribution that will have access to the S3 bucket if it is blocking public access. For more information on these options, see Planning a certificate revocation list (CRL).

  6. Tag your private CA with a key entitled euc-private-ca to designate the CA for use with EUC certificate-based authentication. The key does not require a value. For more information, see Managing tags for your private CA.

  7. Certificate-based authentication utilizes virtual smart cards for logon. Following the Guidelines for enabling smart card logon with third-party certification authorities in Active Directory, perform the following steps:

    • Configure domain controllers with a domain controller certificate to authenticate smart card users. If you have an Active Directory Certificate Services enterprise CA configured in your Active Directory, domain controllers are automatically enrolled with certificates to enable smart card logon. If you don't have Active Directory Certificate Services, see Requirements for domain controller certificates from a third-party CA. You can create a domain controller certificate with AWS Private CA. If you do this, don't use a private CA configured for short-lived certificates.


      If you are using AWS Managed Microsoft AD, you can configure Certificate Services on an EC2 instance to satisfy the requirement for domain controller certificates. See AWS Launch Wizard for example deployments of AWS Managed Microsoft AD configured with Active Directory Certificate Services.

      An additional configuration task with AWS Managed Microsoft AD and Active Directory Certificate Services is to create outbound rules from the controllers VPC security group to the EC2 instance running Certificate Services allowing TCP ports 135 and 49152-65535 to enable certificate autoenrollment. In addition, the EC2 instance running must allow inbound access on the same ports from domain instances, including domain controllers. For more information on locating the security group for AWS Managed Microsoft AD see Configure your VPC subnets and security groups.

    • On the AWS Private CA console or using the SDK or CLI, select your CA and under the CA certificate, export the CA private certificate. For more information, see Exporting a private certificate.

    • Publish the CA to Active Directory. Logon to a domain controller or a domain-joined machine. Copy the CA private certificate to any <path>\<file> and run the following commands as a domain administrator. Alternatively, you can use Group Policy and the Microsoft PKI Health Tool (PKIView) tool to publish the CA. For more information, see Configuration instructions.

      certutil -dspublish -f <path>\<file> RootCA certutil -dspublish -f <path>\<file> NTAuthCA

      Ensure that the commands complete successfully, and then remove the private certificate file. Depending on Active Directory replication settings, it can take several minutes for the CA to be published to your domain controllers and desktop instances.


      It is required that Active Directory distribute the CA to the Trusted Root Certification Authorities and Enterprise NTAuth stores automatically for WorkSpaces desktops when they are joined to the domain.

Enable certificate-based authentication

Complete the following steps to enable certificate-based authentication.

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

  2. In the navigation pane, choose Directories.

  3. Choose the Directory ID for your WorkSpaces.

  4. Under Authentication, click Edit.

  5. Click Edit Certificate-Based Authentication.

  6. Check Enable Certificate-Based Authentication.

  7. Confirm that your private CA ARN is associated in the list. The private CA should be in the same AWS account and AWS Region, and must be tagged with a key entitled euc-private-ca to appear in the list.

  8. Click Save Changes. Certificate-based authentication is now enabled.

  9. Reboot your Windows WorkSpaces on WorkSpaces Streaming Protocol (WSP) bundles for the changes to take effect. For more information, see Reboot a WorkSpace.

  10. After rebooting, when users authenticate via SAML 2.0 using a supported client, they will no longer receive a prompt for the domain password.


When certificate-based authentication is enabled to sign in to WorkSpaces, users are not prompted for multi-factor authentication (MFA) even if enabled on the Directory. When using certificate-based authentication, MFA can be enabled through your SAML 2.0 identity provider. For more information on AWS Directory Service MFA, see Multi-factor authentication (AD Connector) or Enable multi-factor authentication for AWS Managed Microsoft AD.

Manage certificate-based authentication

CA Certificate

In a typical configuration, the private CA certificate has a validity period of 10 years. See Managing the private CA lifecycle for more information on replacing a CA with an expired certificate, or reissuing the CA with a new validity period.

End User Certificates

End user certificates issued by AWS Private CA for WorkSpaces certificate-based authentication don't require renewal or revocation. These certificates are short-lived. WorkSpaces automatically issues a new certificate every 24 hours. These end user certificates have a shorter validity period than a typical AWS Private CA CRL distribution. As a result, end user certificates don't need to be revoked and won't appear in a CRL.

Audit Reports

You can create an audit report to list all of the certificates that your private CA has issued or revoked. For more information, see Using audit reports with your private CA.

Logging and Monitoring

You can use AWS CloudTrail to record API calls to AWS Private CA by WorkSpaces. For more information, see Using CloudTrail. In CloudTrail Event history you can view GetCertificate and IssueCertificate event names from acm-pca.amazonaws.com event source made by the WorkSpaces EcmAssumeRoleSession user name. These events will be recorded for every EUC certificate-based authentication request.