Skip to content

Scenario 1 — Gateway + AD (full deployment)

Installs a new Linux gateway (windows_desktop service), configures Active Directory and brings the domain's Windows Servers up in Teleport.

Prerequisites

  • A reachable Teleport cluster (proxy host:port).
  • A Linux server (Debian/RHEL) for the gateway, reachable from the DC.
  • A domain controller with LDAPS enabled (see below) and a Domain Admin account to run the AD script.
  • The application deployed and reachable (PUBLIC_API_BASE).

Steps in the wizard

  1. Choose "New proxy + Active Directory".
  2. Fill in the client, cluster (proxy + version), the Linux target (distro, arch), the AD domain, the server OUs, the service account, the filters.
  3. The wizard provides two commands: the Linux installation and the AD configuration, then a guided installation phase with checks.

To reuse the client of a proxy already in the fleet, pick it under Start from an existing client proxy (new proxy for this client, or servers added to that proxy).

The wizard keeps a draft in the browser tab (sessionStorage) so that leaving the page loses nothing: on return a "Draft restored" banner offers to discard it. The draft never contains a token or password (the pasted teleport.yaml of the merge mode is not kept) and is deleted once the deployment is generated or when the tab is closed.

A. Linux gateway

On the target Linux server (root):

curl -fsSL 'https://<PUBLIC_API_BASE>/api/i/<id>/<token>/install.sh' | bash

The script installs Teleport, writes /etc/teleport.yaml (windows_desktop service), handles NLA (systemd override), and connects the agent to the cluster.

B. Active Directory configuration (on the DC)

As Domain Admin, on the domain controller:

$f = Join-Path $env:TEMP ('tenantry-' + [guid]::NewGuid().ToString('N') + '-configure-ad.ps1')
try {
  irm 'https://<PUBLIC_API_BASE>/api/i/<id>/<token>/configure-ad.ps1' -OutFile $f
  if ((Get-FileHash -Algorithm SHA256 -LiteralPath $f).Hash -ne '<SHA-256 shown by Tenantry>') { throw 'Unexpected SHA-256' }
  powershell -NoProfile -ExecutionPolicy Bypass -File $f
} finally { Remove-Item -LiteralPath $f -Force -ErrorAction SilentlyContinue }

Copy the command shown by Tenantry: it carries the exact URL and SHA-256. The script embeds the deployment's callback token, so the command always deletes the downloaded file afterwards (also when it fails).

The script: creates/validates the service account, publishes the Teleport CA (RootCA + NTAuth), exports the LDAPS CA, then sends the auto-detected values back to the app (callback) (NetBIOS, SID, LDAP IP/name, certificate).

LDAPS prerequisite (mandatory)

Teleport talks to AD over LDAPS (port 636): the DC must have a server certificate (EKU Server Authentication). Test:

$h='dc1.example.local'
try { $t=[Net.Sockets.TcpClient]::new($h,636); $s=[Net.Security.SslStream]::new($t.GetStream(),$false,{$true}); $s.AuthenticateAsClient($h); "LDAPS OK - $($s.RemoteCertificate.Subject)"; $s.Dispose(); $t.Dispose() } catch { "LDAPS KO: $($_.Exception.Message)" }
  • KO … forcibly closed → no server certificate. Fix it:
  • Production: ADCS + auto-enrollment of the Kerberos / Domain Controller Authentication template (certutil -pulse).
  • Lab (self-signed, on the DC): 
    New-SelfSignedCertificate -Subject "CN=dc1.example.local" -DnsName "dc1.example.local" `
  -CertStoreLocation Cert:\LocalMachine\My -KeyUsage DigitalSignature,KeyEncipherment `
  -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1") -NotAfter (Get-Date).AddYears(2)
Restart-Service NTDS -Force

The CA export tries, in order: TLS LDAPS, then the local store LocalMachine\My, then certutil -ca.cert. On total failure: error [LDAPS-E-CAEXPORT] with the steps to follow. A self-signed certificate works end to end.

Verification

In the wizard's guided phase (or via the app), discovery lists the desktops reported for this client. On the cluster side:

tctl desktop ls

Checklist

  • [ ] The AD step turned green (callback or manual validation).
  • [ ] The agent is connected and runs the windows_desktop_service only.
  • [ ] The expected desktops are listed, no Windows 10/11 workstation leaked.
  • [ ] "Join token revoked" is shown: Tenantry deleted the multi-use windowsdesktop token (tctl tokens rm). If the UI reports a failure, delete it by hand: tctl tokens ls, then tctl tokens rm <token> for the WindowsDesktop token labelled client_code=<code>. Leaving the guided install (New deployment) also revokes it; an abandoned deployment is revoked when it expires.

Tenantry identity needs delete on token for this revocation (see Managing client proxies).

See Error codes & Debugging if something goes wrong.