AWS workspaces documentation change
Summary
Added new section for Amazon Linux 2 WorkSpaces with distinct security limitations (UPN-based mapping) and configuration requirements.
Security assessment
Documents security-relevant limitations of Amazon Linux 2 implementation compared to newer distributions, but does not address specific vulnerabilities or security incidents. Primarily adds feature documentation.
Diff
diff --git a/workspaces/latest/adminguide/smart-cards.md b/workspaces/latest/adminguide/smart-cards.md index 9bcfe0441..51ea33fdc 100644 --- a//workspaces/latest/adminguide/smart-cards.md +++ b//workspaces/latest/adminguide/smart-cards.md @@ -5 +5 @@ -RequirementsLimitationsDirectory configurationEnable smart cards for Windows WorkSpacesEnable smart cards for Linux WorkSpaces +RequirementsLimitationsDirectory configurationEnable smart cards for Windows WorkSpacesEnable smart cards for Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpacesEnable smart cards for Amazon Linux 2 WorkSpaces @@ -25 +25,3 @@ For example, users can use smart cards for in-session authentication while worki - * Enable smart cards for Linux WorkSpaces + * Enable smart cards for Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces + + * Enable smart cards for Amazon Linux 2 WorkSpaces @@ -34 +36 @@ For example, users can use smart cards for in-session authentication while worki - * To use a smart card with a Windows or Linux WorkSpace, the user must use the Amazon WorkSpaces Windows client version 3.1.1 or later or the WorkSpaces macOS client version 3.1.5 or later. For more information about using smart cards with the Windows and macOS clients, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the _Amazon WorkSpaces User Guide_. + * To use a smart card with a Windows or Linux WorkSpace, the user must use the Amazon WorkSpaces Windows client version 3.1.1 or later, WorkSpaces macOS client version 3.1.5 or later, or WorkSpaces Ubuntu 22.04 client version 2024.1 or later (smart card authentication is not supported with WorkSpaces Ubuntu 20.04 client). For more information about using smart cards with the Windows and macOS clients, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the _Amazon WorkSpaces User Guide_. @@ -41,0 +44,4 @@ In addition to those requirements, user certificates employed for smart card aut +###### Note + +Amazon Linux 2 WorkSpaces rely on UPN for certificate-to-user mapping. Newer Linux WorkSpaces, like Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, support more secure [mapping methods](https://www.idmanagement.gov/implement/scl-windows/#step-4---account-linking). + @@ -47,0 +54,7 @@ In addition to those requirements, user certificates employed for smart card aut +###### Note + +Ubuntu WorkSpaces, Rocky Linux WorkSpaces, and Red Hat Enterprise Linux WorkSpaces require OCSP for in-session authentication by default, and OCSP verification in these systems requires the OCSP responder to have NONCE extension enabled to prevent replay attacks. To disable NONCE extension, in-session OCSP verification must be disabled altogether. To disable OCSP verification in Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, create a new file `/etc/sssd/conf.d/disable-ocsp.conf`with the following content: + + [sssd] + certificate_verification = no_ocsp + @@ -53 +66 @@ In addition to those requirements, user certificates employed for smart card aut - * Only the WorkSpaces Windows client application version 3.1.1 or later and the macOS client application version 3.1.5 or later are currently supported for smart card authentication. + * Only the WorkSpaces Windows client application version 3.1.1 or later, the WorkSpaces macOS client application version 3.1.5 or later, and WorkSpaces Ubuntu 22.04 client application version 2024.1 or later are currently supported for smart card authentication. WorkSpaces Ubuntu 20.04 or earlier client application is not supported for smart card authentication. @@ -57,2 +69,0 @@ In addition to those requirements, user certificates employed for smart card aut - * Ubuntu WorkSpaces does not currently support smart card authentication. - @@ -77 +88 @@ In addition to those requirements, user certificates employed for smart card aut - * For in-session authentication and pre-session authentication on Linux or Windows WorkSpaces, only one smart card is currently allowed at a time. + * For in-session authentication and pre-session authentication on Linux or Windows WorkSpaces, only one smart card is currently allowed at a time. Simultaneous use of multiple cards may work, but is not supported. @@ -102 +113,11 @@ Smart card authentication requires Kerberos Constrained Delegation (KCD) to func -In addition to configuring your AD Connector directory, you must also make sure that the certificates that are issued to the domain controllers for your on-premises directory have the "KDC Authentication" extended key usage (EKU) set. To do this, use the Active Directory Domain Services (AD DS) default Kerberos Authentication certificate template. Do not use a Domain Controller certificate template or a Domain Controller Authentication certificate template because those templates don't contain the necessary settings for smart card authentication. +In addition to configuring your AD Connector directory: + + * Make sure that the certificates that are issued to the domain controllers for your on-premises directory have the "KDC Authentication" extended key usage (EKU) set. To do this, use the Active Directory Domain Services (AD DS) default Kerberos Authentication certificate template. Do not use a Domain Controller certificate template or a Domain Controller Authentication certificate template because those templates don't contain the necessary settings for smart card authentication. + + * For Linux WorkSpaces, make sure that OCSP responder for the CA issuing smart card certificates has NONCE extension enabled. If it cannot be enabled, in-session OCSP verification will have to be disabled in Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces. To disable OCSP verification, create a new file `/etc/sssd/conf.d/disable-ocsp.conf`with the following content: + + [sssd] + certificate_verification = no_ocsp + + + @@ -184 +205,52 @@ The tools for managing the certificates and keys on the smart card (such as remo -## Enable smart cards for Linux WorkSpaces +## Enable smart cards for Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces + +To enable the use of smart cards on Ubuntu, Rocky Linux, and Red Hat Enterprise Linux WorkSpaces, you need to include the root and all intermediate CA certificates in the WorkSpace image for all CAs issuing smart cards, and for all CAs issuing domain controller certificates. + +###### To obtain your CA certificate + +You can obtain your CA certificate in several ways: + + * You can use a CA certificate bundle of a third-party certification authority. + + * You can export your own CA certificate by using the Web Enrollment site, which is either `http://`ip_address`/certsrv` or `http://`fqdn`/certsrv`, where ``ip_address`` and ``fqdn`` are the IP address and the fully qualified domain name (FQDN) of the CA server. For more information about using the Web Enrollment site, see [ How to export a Root Certification Authority Certificate](https://docs.microsoft.com/troubleshoot/windows-server/identity/export-root-certification-authority-certificate) in the Microsoft documentation. + + * You can use the following procedure to export the CA certificate from a CA server that is running Active Directory Certificate Services (AD CS). For information about installing AD CS, see [ Install the Certification Authority](https://docs.microsoft.com/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority) in the Microsoft documentation. + + 1. Log into the CA server using an administrator account. + + 2. From the Windows **Start** menu, open a command prompt window (**Start** > **Windows System** > **Command Prompt**). + + 3. Use the following command to export the CA certificate to a new file, where ``rootca`.cer` is the name of the new file: + + certutil -ca.cert rootca.cer + +For more information about running certutil, see [ certutil](https://docs.microsoft.com/windows-server/administration/windows-commands/certutil) in the Microsoft documentation. + + 4. Use the following OpenSSL command to convert the exported CA certificate from DER format to PEM format, where `rootca` is the name of the certificate. For more information about OpenSSL, see [www.openssl.org](https://www.openssl.org/). + + openssl x509 -inform der -in rootca.cer -out /tmp/rootca.pem + + + + +###### + +To add your CA certificates to your Linux WorkSpaces + +To assist you with enabling smart cards, we've added the `enable_smartcard` script to our Linux WorkSpaces DCV bundles. This script performs the following actions: + + * Imports your CA certificates into a private PEM bundle that defines the trust root for SSSD on Linux WorkSpaces). + + * Updates SSSD, PAM, and Kerberos configuration, which includes enabling `PKINIT` (Kerberos authentication using certificate instead of password) during WorkSpace provisioning. + + + + +The following procedure explains how to use the `enable_smartcard` script to import your CA certificates and to enable smart card authentication for your Linux WorkSpaces. + + 1. Create a new Linux WorkSpace with the DCV protocol enabled. When launching the WorkSpace in the Amazon WorkSpaces console, on the **Select Bundles** page, be sure to select **DCV** for the protocol, and then select one of the Linux WorkSpaces public bundles. + + 2. On the newly created WorkSpace, make sure `/etc/skylight.conf` file has `pam_smartcard = true` line in `[features]` section: + + [features] + pam_smartcard = true @@ -188 +260,121 @@ The tools for managing the certificates and keys on the smart card (such as remo -Linux WorkSpaces on DCV currently have the following limitations: +If not all your users are yet configured to use strong `altSecurityIdentities` certificate mapping, you can also add `smartcard_weak_mapping = true` line to the same `[features]` section in `/etc/skylight.conf` to support legacy mapping methods, but we recommend migrating those users to use strong mapping methods as soon as possible instead. + + 3. On the WorkSpace, run the following command as root, where ``pem-path1``, ``pem-path2``, etc., are the paths to files, each containing one of the CA certificates in the trust chain for the smart card and domain controller certificates. All of these files should be in PEM format and contain one certificate per file. Glob patterns can be used (e.g., `*.pem`) + + /usr/lib/skylight/enable_smartcard --ca-cert pem-path1 pem-path2 pem-path3 ... + +###### Note + +Make sure additional dependency packages are installed on the WorkSpace before running the above command, using following commands as root. + +For Rocky Linux and Red Hat Enterprise Linux WorkSpaces: + + dnf install sssd-dbus libsss_simpleifp sssd-tools krb5-pkinit opensc + +For Ubuntu WorkSpaces: + + apt install krb5-pkinit opensc + + 4. Perform any additional customizations on the WorkSpace. For example, you might want to add a system-wide policy to enable users to use smart cards in Firefox. (Chrome users must enable smart cards on their clients themselves. For more information, see [ Smart Card Support](https://docs.aws.amazon.com/workspaces/latest/userguide/smart_card_support.html) in the _Amazon WorkSpaces User Guide_.) + + 5. [Create a custom WorkSpace image and bundle](./create-custom-bundle.html) from the WorkSpace. + + 6. Use the new custom bundle to launch WorkSpaces for your users. + + + + +###### + +To enable users to use smart cards in Firefox + +You can enable your users to use smart cards in Firefox by adding a SecurityDevices policy to your Linux WorkSpace image. For more information about adding system-wide policies to Firefox, see the [Mozilla policy templates](https://github.com/mozilla/policy-templates/releases) on GitHub. + + 1. On the WorkSpace that you're using to create your WorkSpace image, create a new file named `policies.json` in ``PREFIX`/firefox/distribution/`, where ``PREFIX`` is `/usr/lib64` on Fedora-based systems (Amazon Linux 2, Red Hat Enterprise Linux, and Rocky Linux WorkSpaces), and `/usr/lib` on Debian-based systems (Ubuntu WorkSpaces). + + 2. In the JSON file, add the following SecurityDevices policy, where ``NAME_OF_DEVICE`` is whatever value you want to use to identify the `pkcs` module. For example, you might want to use a value such as `"OpenSC"`: + + { + "policies": { + "SecurityDevices": { + "NAME_OF_DEVICE": "PREFIX/opensc-pkcs11.so" + } + } + } + + + + +###### Troubleshooting + +Troubleshooting of smart card authentication is easier when pre-session is set to use password authentication - during session provisioning Linux WorkSpaces automatically switch on-host authentication mode preference to password-based or smartcard-based depending on pre-session authentication method used. If there are any issues with smart card authentication, disconnecting and reconnecting using password pre-session authentication resets the workspace back to password on-host authentication. To manually switch Linux WorkSpaces instance to smart card authentication run `/usr/lib/skylight/resume_smartcard` command as root. + +Linux WorkSpaces use OpenSC software for working with smart cards. That software comes with tools like `pkcs11-tool` and `pkcs15-tool` which can be useful in troubleshooting issues with smart cards. These tools can be used for inspecting smart card readers, individual tokens, and PIV slots or certificates on each smart card token. + +An `openssl` command-line tool can be helpful in troubleshooting issues with trust chains, OCSP responders, or missing KUs/EKUs (key usage/extended key usage) flags, especially in combination with `pkcs15-tool`'s ability to extract public certificates from a smart card. + +Common troubleshooting options: + + * Extract first (usually PIV slot 9A) certificate from the smart card and save it as ``card-cert.pem``: `pkcs15-tool --read-certificate 1 > `card-cert.pem`` + + * Validate the extracted certificate against trust database on the WorkSpace: `openssl verify -verbose -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem -cert `card-cert.pem`` + + * Get OCSP URL from the extracted smart card certificate: `openssl x509 -noout -ocsp_uri -in `card-cert.pem`` + + * Verify that OCSP response indicates certificate is valid and includes NONCE: `openssl ocsp -issuer /etc/sssd/pki/sssd_auth_ca_db.pem -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem -cert `card-cert.pem` -text -url `OCSP_URI``, where `OCSP_URI` is the OCSP URL from above. + + * Check if domain controller certificate is considered trusted: `openssl s_client -connect `DC_HOSTNAME`:636 -showcerts | openssl verify -verbose -CAfile /etc/sssd/pki/sssd_auth_ca_db.pem`, where `DC_HOSTNAME` is the host name of one of the domain controllers in your Active Directory domain. + + * Confirm domain controller certificate has KDC Authentication EKU (extended key usage) set: `openssl s_client -connect `DC_HOSTNAME`:636 -showcerts | openssl x509 -noout -text`. + + * Attempt manual PKINIT to see if there are any error codes that can be used to narrow down the problem: `KRB5_TRACE=/dev/stdout kinit -X X509_user_identity=PKCS11:opensc-pkcs11.so:certid=`01` -V`, where `01` is the number of one of the four main PIV slots on the card - `01` for `9A`, `02` for `9C`, etc. Most cards will have certificate meant for user authentication in slot 9A. + + * Check if system is able to map smart card certificate to an AD user (execute as root): `dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe/Users org.freedesktop.sssd.infopipe.Users.FindByCertificate string:"$(<`card-cert.pem`)"`. This can be combined with enabling debug logging for SSSD. + + + + +The most common known issues: + + * Incomplete trust chain for the smart card certificate - when importing certificates using `enable_smartcard` script the full list of all root and intermediate CA certificates must to be provided. The `enable_smartcard` tool will show an error if not all imported certificates are trusted because of missing from the list root CA certificate, but it cannot detect when either an entire trust chain or the innermost intermediate CA certificate in one of the trust chains is missing. In that situation it will import certificates without an error, yet either a smart card certificate or domain controller certificates may still be considered untrusted. + + * Missing trust chain for the domain controller certificates - if domain controller certificates are issued by a different CA than smart cards (e.g., in case of [Common Access Card (CAC)](https://www.cac.mil/Common-Access-Card)), that CA trust chain needs to be imported together with the smart card issuing CA certificates. + + * Lack of NONCE extension support in OCSP responder - Linux WorkSpaces require that OCSP responder of the smart card issuer has NONCE extension enabled. If it cannot be enabled, OCSP validation will have to be completely disabled. + + * Domain controller certificates are missing `KDC Authentication` EKU (OID 1.3.6.1.5.2.3.1) - for smart card authentication to work domain controller certificates need to be re-issued to include KDC Authentication EKU. + + * Domain controller certificates are expired - for smart card authentication to work domain controller certificates must remain up-to-date. + + * Smart card certificates are mapped to users in AD using weak mapping methods - traditionally, UPN field in subjectAltName attribute was used to map a certificate to a user in AD, being expected to match userPrincipalName attribute. This is no longer considered a secure mapping method and is disallowed by default. It is possible to re-enable it by passing `--allow-weak-mapping` argument to `enable_smartcard` command and adding `smartcard_weak_mapping = true` line to the `[features]` section in `/etc/skylight.conf` file, but a better solution is to use one of the strong mapping methods. See [Account Linking](https://www.idmanagement.gov/implement/scl-windows/#step-4---account-linking) documentation for more details. + + + +