docs: mention support for multiple AD domains (gravitational#33273)

This documents the changes in gravitational#33218

docs/cspell.json

@@ -597,6 +597,7 @@
     "noprompt",
     "nosql",
     "nowait",
+    "ntauth",
     "nvme",
     "obtainlicense",
     "octocat",
@@ -861,4 +862,4 @@
   "flagWords": [
     "hte"
   ]
-}
+}

docs/pages/desktop-access/active-directory-manual.mdx

@@ -35,7 +35,7 @@ This guide requires you to have:
 <Admonition title="Azure AD" type="warning">
 
 Microsoft's Azure Active Directory (Azure AD) offering does not support the
-Kerberos authentication protocol, which is required for the certificate-based 
+Kerberos authentication protocol, which is required for the certificate-based
 authentication described in this section.
 
 At this time, Teleport does not support integration with Azure AD, however
@@ -682,6 +682,51 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Local
 Double click the "Add workstations to domain" policy and ensure that the
 "Authenticated Users" group is not present.
 
+## Multiple domains
+
+Each `windows_desktop_service` is designed to support connecting to hosts in a
+single Active Directory domain. If you have multiple independent domains, you
+can deploy multiple Teleport agents to service them.
+
+If you have multiple domains with a trust relationship between them, you can
+configure Teleport to perform PKI operations against one domain, while generating
+certificates for users in another domain.
+
+In order for this to work, the hosts that you want to connect to and the AD
+users that you want to connect as must reside in the same domain.
+
+For example, suppose you have a root domain at `example.com` and a child domain
+for developers at `dev.example.com`. If your PKI is configured at the root, but
+you want to allow users in the child domain to connect to hosts in the child
+domain, you would do the following:
+
+1. Import Teleport's CA certificate as a trusted root certificate in the root
+   domain's group policy and add the certificate to the NTAuth store as
+   described in the
+   [section above](#publish-the-teleport-ca-to-the-ntauth-store).
+1. Configure Teleport to perform PKI against the root domain, while
+   issuing certificates for users and hosts in the child domain:
+
+  ```yaml
+  windows_desktop_service:
+    enabled: yes
+
+    # configure LDAP settings to point at the child domain
+    ldap:
+      addr: dev.example.com:636
+      username: 'DEV\svc-teleport'
+
+    # optional: configure discovery for the child domain
+    discovery:
+      base_dn: CN=Computers,DC=dev,DC=example,DC=com
+
+    # perform PKI against the root domain
+    pki_domain: root.example.com
+  ```
+
+With this configuration, Teleport will generate certificates for users in
+`dev.example.com`, but it will publish its CA and CRLs to `example.com`.
+
 ## Troubleshooting
 
 If you hit any issues, check out the

docs/pages/includes/config-reference/desktop-config.yaml

@@ -63,6 +63,12 @@ windows_desktop_service:
     # and requesting the attribute = objectSid
     sid: '$LDAP_USER_SID'
 
+  # (optional) When AD support is used, this field allows you to override
+  # the domain that Teleport uses for PKI operations. If empty, the domain
+  # from the ldap section is used. This can be useful for cases where PKI
+  # is configured in a root domain but Teleport is used to provide access
+  # to users and computers in a child domain.
+  pki_domain: root.example.com
 
   # (optional) hosts is a list of hostnames to register as WindowsDesktop
   # objects in Teleport. These hosts must be part of the Active Directory
@@ -95,7 +101,7 @@ windows_desktop_service:
   # Rules for applying labels to Windows hosts based on regular expressions
   # matched against the host name. If multiple rules match, the desktop will
   # get the union of all matching labels.
-  # 
+  #
   # The rules for matching static hosts (hosts and non_ad_hosts) and discovered hosts
   # are slightly different. See https://goteleport.com/docs/desktop-access/rbac/
   # for details.