Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Configure access for Active Directory manually

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Getting started with Teleport Desktop Access for Windows Servers

Getting started with Teleport Desktop Access for Windows Servers

Length: 24:47

You can configure access for Active Directory users through the Teleport Web UI and the scripts described in Configure access for Active Directory with scripts. However, if automation won't work for your environment—for example, because you use an older version of Teleport or have custom configuration or network requirements—you can manually configure access for Active Directory domain users using the instructions in this guide.

This guide demonstrates how to connect an Active Directory domain and how to log into a Windows desktop from the connected domain.

You should note that Teleport requires the Kerberos authentication protocol to support certificate-based authentication for Active Directory. Because Azure Active Directory doesn't use Kerberos, you can't use the Teleport Windows Desktop Service for Azure Active Directory.

Prerequisites

To complete the steps in this guide, verify your environment meets the following requirements:

  • Access to a running Teleport cluster, tctl admin tool, and tsh client tool version >= 15.0.2.

    You can verify the tools you have installed by running the following commands:

    tctl version

    Teleport Enterprise v15.0.2 go1.21


    tsh version

    Teleport v15.0.2 go1.21

    You can download these tools by following the appropriate Installation instructions for the Teleport edition you use.

  • A Linux server to run the Teleport Windows Desktop Service. You can use an existing server that runs the Teleport agent for other resources.

  • An Active Directory domain that is configured for LDAPS. Because Teleport requires an encrypted LDAP connection, you should verify that your domain uses Active Directory Certificate Services or a non-Microsoft certification authority (CA) to issue LDAPS certificates.

    If you don't have Active Directory or Active Directory Certificate Services installed, you can add roles and services using Server Manager or refer to Configure access for Active Directory with scripts for how to use the Teleport-provided scripts to install these services.

  • Administrative access to a domain controller.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines.

    For example:

    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 15.0.2

    CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/7. Create a restrictive service account

Teleport requires a service account to connect to your Active Directory domain. You should create a dedicated service account with restrictive permissions for maximum security.

To create the service account:

  1. Open PowerShell on a Windows domain computer.

  2. Create a service account with a randomly-generated password by copying and pasting the following script into the PowerShell console:

    $Name="Teleport Service Account"
    $SamAccountName="svc-teleport"
    
    # Generate a random password that meets the "Password must meet complexity
    # requirements" security policy setting.
    # Note: if the minimum complexity requirements have been changed from the
    # Windows default, this part of the script may need to be modified.
    Add-Type -AssemblyName 'System.Web'
    do {
       $Password=[System.Web.Security.Membership]::GeneratePassword(15,1)
    } until ($Password -match '\d')
    $SecureStringPassword=ConvertTo-SecureString $Password -AsPlainText -Force
    
    New-ADUser `
      -Name $Name `
      -SamAccountName $SamAccountName `
      -AccountPassword $SecureStringPassword `
      -Enabled $true
    

    The password generated for the service account is discarded immediately. Teleport doesn't need the password because it uses x509 certificates for LDAP authentication. You can reset the password for the service account if you need to perform password authentication.

  3. Set the minimum permissions that must granted to the service account by running the following script in the PowerShell console:

    # Save your domain's distinguished name to a variable.
    $DomainDN=$((Get-ADDomain).DistinguishedName)
    
    # Create the CDP/Teleport container.
    # If the command fails with "New-ADObject : An attempt was made to add an object
    # to the directory with a name that is already in use", it means the object
    # already exists and you can move on to the next step.
    New-ADObject -Name "Teleport" -Type "container" -Path "CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN"
    
    # Allow Teleport to create LDAP containers in the CDP container.
    dsacls "CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):CC;container;"
    
    # Allow Teleport to create and delete cRLDistributionPoint objects in the CDP/Teleport container.
    dsacls "CN=Teleport,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):CCDC;cRLDistributionPoint;"
    
    # Allow Teleport to write the certificateRevocationList property in the CDP/Teleport container.
    dsacls "CN=Teleport,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN " /I:T /G "$($SamAccountName):WP;certificateRevocationList;"
    
    # Allow Teleport to read certificationAuthority objects in the NTAuthCertificates container.
    dsacls "CN=NTAuthCertificates,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):GR;certificationAuthority;"
    
    # Allow Teleport to read the cACertificate property in the NTAuthCertificates container.
    dsacls "CN=NTAuthCertificates,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):RP;cACertificate;"
    
  4. Get the security identifier for the new service account. For example, run the following command:

    Get-AdUser -Identity $SamAccountName | Select SID
    

    The command returns the security identifier for the specified account:

    SID
    ---
    S-1-5-21-209875886-835680547-4265310078-1113
    
  5. Copy the full security identifier—beginning with S-—returned.

    You'll use this value for the sid field when you configure the ldap settings in a later step.

Step 2/7. Prevent the service account from performing interactive logins

The next steps modify group policy objects (GPOs). Changes to group policies can take time to propagate to all hosts. You can force changes to take effect immediately on your current host by opening PowerShell and running gpupdate.exe /force. However, the change might still take time to propagate to other hosts in the domain.

The Teleport service account is only needed to authenticate over LDAP. The account doesn't need to log on to Windows computers like an ordinary user. You can prevent the service account from being used to log on by creating a new Group Policy Object (GPO) linked to your entire domain, and then denying interactive logins.

Create a GPO

  1. Open PowerShell and specify a name for the new group policy object with the $GPOName variable:

    $GPOName="Block teleport-svc Interactive Login"
    
  2. Create the new GPO by running the following command in the PowerShell console:

    New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
    

Deny interactive login

  1. Open Group Policy Management and expand Forest > Domains > $YOUR_DOMAIN > Group Policy Objects to locate the group policy object you just created.

  2. Select the group policy object, click Action, then select Edit.

  3. Expand Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment.

  4. Double-click Deny log on locally, then select Define these policy settings.

  5. Click Add User or Group, then click Browse.

  6. Type all or part of the service account name—for example, svc-teleport—then click Check Names.

  7. Verify the Teleport Service Account is selected, then click OK in all the dialogs.

    Deny Interactive Login
  8. Repeat these steps for Deny log on through Remote Desktop Services.

For added security, you can disable username and password authentication completely. If you disable username and password authentication, only the Teleport virtual smart card can be used to access Windows computers in the domain.

Step 3/7. Configure a GPO to allow Teleport connections

To enable access to Windows desktop sessions through Teleport, you must configure a group policy object that allows Windows computers to trust the Teleport certificate authority and accept certificate-based smart card authentication.

You need to do the following to configure the group policy object:

  • Export a certificate signed by the Teleport certificate authority for an existing Teleport cluster.
  • Create a new group policy object and import the signed Teleport certificate.
  • Publish the signed Teleport certificate to the Active Directory domain.
  • Publish the signed Teleport certificate to the NTAuth Store.
  • Enable smart card authentication.
  • Allow remote desktop connections.

You must repeat these steps if you rotate the Teleport user certificate authority.

Export the Teleport certificate

To export the Teleport user CA certificate:

  1. Log on to a Windows domain controller where you can access Group Policy Management.

  2. Open PowerShell and download the Teleport user certificate authority by running the following command and replacing teleport.example.com with the address of your Teleport cluster:

    curl -o user-ca.cer https://teleport.example.com/webapi/auth/export?type=windows
  3. Take note of the path to the user-ca.cer file for use in a later step.

Create the GPO for the Teleport certificate

To configure the group policy object:

  1. Create a new group policy object with the name Teleport Access Policy by running the following command:

    $GPOName="Teleport Access Policy"
    New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
    

    This command applies the GPO to the entire Active Director domain. If you only want to protect a subset of computers in the domain, you can apply the GPO to a specific organizational unit (OU) that only includes those computers.

    If you use AWS Managed Microsoft Active Directory, AWS Delegated Domain Administrator accounts are not granted permissions to apply GPOs at the domain level. Instead, you should apply this GPO to the automatically-created OU with the NetBIOS domain name containing Computers and Users nested one level inside the domain root.

    AWS Managed AD OU Location
  2. Open Group Policy Management and expand Forest, Domains, your domain, and Group Policy Objects to locate the GPO you just created.

  3. Select the new GPO—for example, Teleport Access Policy, right-click, then select Edit.

  4. In the group policy editor, expand Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies.

  5. Right-click Trusted Root Certification Authorities, then click Import.

  6. Use the wizard to select and import the Teleport certificate.

    Import Teleport CA
  7. To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):

    gpupdate.exe /force
    

Publish the Teleport CA to the Active Directory domain

To publish the Teleport certificate in the Active Directory domain:

  1. Log on to a Windows computer that is joined to the Active Directory domain with an account that's a member of the Domain Administrators or AWS Delegated Domain Administrators group.

  2. Open PowerShell and run the following command using the path to the user-ca.cer file you exported from Teleport:

    certutil -dspublish -f user-ca.cer RootCA
    

    This command enables the domain controllers to trust the Teleport CA so that certificate-based smart card authentication through Teleport can succeed.

Publish the Teleport CA to the NTAuth Store

For authentication with Teleport-issued certificates to succeed, the Teleport CA also must be published to the enterprise NTAuth store. Teleport periodically publishes its CA after it is able to authenticate, but this step must be performed manually the first time for Teleport to have LDAP access.

To publish the Teleport CA to LDAP:

  1. Open PowerShell and run the following command using the path to the user-ca.cer file:

    certutil -dspublish -f user-ca.cer NTAuthCA
    
  2. Force the retrieval of the CA from LDAP by running the following command:

    certutil -pulse
    

    This step isn't strictly required. However, it allows you to proceed to the next steps without waiting for the certificate to propagate.

Enable smart card authentication

Teleport performs certificate-based authentication by emulating a smart card.

To add smart card authentication to your group policy object:

  1. Verify that you have the Teleport Access Policy group policy object open in the group policy editor.

  2. Expand Computer Configuration > Policies > Windows Settings > Security Settings > System Services.

  3. Double-click Smart Card and select Define this policy setting.

  4. Select Automatic, then click OK.

    Enable the Smart Card Service
  5. To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):

    gpupdate.exe /force
    

Allow remote desktop connections

Next you need to configure policies that allow remote connections to domain computers.

  1. Verify that you have the Teleport Access Policy group policy object open in the group policy editor.

  2. Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections.

  3. Right-click Allow users to connect remotely by using Remote Desktop Services, select Edit, select Enabled, then click OK.

  4. Under Remote Desktop Session Host, select Security.

  5. Right-click Require user authentication for remote connections by using Network Level Authentication, select Edit, select Disabled, then click OK.

    Disable Require user authentication...
  6. Right-click Always prompt for password upon connection, select Edit, select Disabled, then click OK.

    The Teleport certificate-based smart card authentication generates a random smart card PIN for each desktop session and provides the PIN to the desktop when establishing the RDP connection. Because the PIN is never provided to the Teleport user, the Always prompt for password upon connection policy must be disabled for authentication to succeed.

  7. Expand Computer Configuration, Policies, Windows Settings, Security Settings to select Windows Firewall with Advanced Security.

  8. Right-click Inbound Rules, select New Rule.

    • Under Predefined, select Remote Desktop, then click Next.
    • Select User Mode (TCP-in), then click Next.
    • Select Allow the connection, then click Finish.
    Open the Firewall
  9. To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):

    gpupdate.exe /force
    

Enable RemoteFX

To finish configuring the Teleport Access Policy group policy object, you must enable RemoteFX. RemoteFX is a compression technology that significantly improves the performance of remote desktop connections.

  1. Verify that you have the Teleport Access Policy group policy object open in the group policy editor.

  2. Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment > RemoteFX for Windows Server 2008 R2

  3. Right-click Configure RemoteFX, select Edit, select Enabled, then click OK.

  4. Now left-click Remote Session Environment (Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment in the left pane) and from the items in the right pane, right-click Enable RemoteFX encoding for RemoteFX clients designed for Windows Server 2008 R2 SP1, select Edit, select Enabled, then click OK.

    Enable RemoteFX
  5. Again left-click Remote Session Environment in the left pane, and from the items in the right pane, right-click Limit maximum color depth, select Edit, select Enabled, then click OK.

  6. Open PowerShell and run the following command to update your Teleport group policy object:

    gpupdate.exe /force
    

Step 4/7. Configure a certificate for RDP connections

The Teleport RDP client requires secure cryptographic algorithms to make TLS connections. However, Windows Server 2012 R2 doesn't support these algorithms by default.

You can configure Windows Server 2012 R2 to support the required algorithms by doing the following:

  • Create a new certificate template that uses elliptic curve cryptography.
  • Update the Teleport group policy object to use the new certificate template when issuing certificates for remote desktop connections.

If your hosts support the required algorithms, you can skip this step and go to Export your LDAP CA certificate.

Create a certificate template

To create a certificate template that uses elliptic curve P-384 and SHA384 as the signature algorithm:

  1. Click Start, Control Panel, and Administrative Tools to select Certificate Authority.

  2. Open your CA computer, right-click Certificate Templates, then select Manage.

  3. Select the Computer template, right-click, then select Duplicate Template.

  4. Select the Compatibility tab:

    • Change Certification Authority to Windows Server 2012 R2, then click OK.
    • Change Certificate recipient to Windows Server 2012 R2, then click OK.
  5. Select the General tab:

    • Change Template display name to RemoteDesktopAccess.
    • Verify that Template name is also RemoteDesktopAccess.
  6. Select the Cryptography tab:

    • Change Provider Category to Key Storage Provider.
    • Change Algorithm name to ECDH_P384.
    • Change Request hash to SHA384.
  7. Select the Extensions tab:

    • Select Application Polices, then click Edit.
    • Remove all entries from the list.
  8. Select the Security tab:

    • Select Domain Computers and give the group Read and Enroll permissions.
  9. Click OK to create the Template.

  10. Go back to the Certificate Authority console, right-click Certificate Templates.

  11. Click New, select Certificate Template to Issue, then select RemoteDesktopAccess.

  12. Click OK.

Update GPO to use a new certificate template

To update the Teleport group policy object to use the new certificate template:

  1. Open the Teleport Access Policy group policy object in the group policy editor.

  2. Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security.

  3. Right-click Server authentication certificate template, select Edit, select Enabled, then set the Certificate Template Name to RemoteDesktopAccess.

    RDP Certificate Template
  4. Expand Computer Configuration, Policies, and Windows Settings to select Public Key Policies.

  5. Double-click Certificate Services Client - Auto-Enrollment, then select Enabled in the Configuration Model.

  6. Open PowerShell and run the following command to update your Teleport group policy object:

    gpupdate.exe /force
    

Step 5/7. Export your LDAP CA certificate

Teleport connects to your domain controller using LDAPS. This means that you must let Teleport know that the certificate sent by your domain controller during the initial connection is trusted. If your domain controller's certificate is trusted by the system repository on the system running Teleport, you can skip this step.

If you are unable to acquire the LDAP CA certificate, you can skip TLS verification by setting insecure_skip_verify: true. However, you shouldn't skip TLS verification in production environments.

To export a CA certificate:

  1. Click Start, Control Panel, and Administrative Tools to select Certificate Authority.
  2. Select your CA computer, right-click, then select Properties.
  3. One the General tab, click View Certificate.
  4. Select Details, then click Copy to File.
  5. Click Next in the Certificate Export Wizard, and ensure that DER encoded binary X.509 (.CER) is selected.
  6. Select a name and location for the certificate and click through the wizard.
  7. Transfer the exported file to the system where you're running Teleport. You can either add this certificate to your system's trusted repository or provide the file path to the der_ca_file configuration variable.

Step 6/7. Configure Teleport

To configure Teleport to protect access to Windows desktops:

  1. Install Teleport on the Linux host that will run the Teleport Windows Desktop Service:

    Select an edition, then follow the instructions for that edition to install Teleport.

    Teleport Edition

    The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

    curl https://goteleport.com/static/install.sh | bash -s 15.0.2

    Add the Teleport repository to your repository list:

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for cloud.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Update the repo and install Teleport and the Teleport updater

    sudo apt-get update
    sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo yum install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo dnf install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo zypper install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

    Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

    • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
    • Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
    • Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for v15. You'll need to update this

    file for each major release of Teleport.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v15" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    sudo apt-get update
    sudo apt-get install teleport-ent

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo apt-get install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport.repo")"
    sudo yum install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")
    sudo yum install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo yum install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for v15. You'll need to update this

    file for each major release of Teleport.

    First, get the major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport.repo")"

    Install teleport

    sudo dnf install teleport-ent

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo dnf install teleport-ent-fips

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v15/teleport-zypper.repo")

    Install teleport

    sudo zypper install teleport-ent

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    sudo zypper install teleport-ent-fips

    In the example commands below, update $SYSTEM_ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

    curl https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz
    shasum -a 256 teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-bin.tar.gz
    cd teleport-ent
    sudo ./install

    For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

    curl https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

    <checksum> <filename>

    curl -O https://cdn.teleport.dev/teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    shasum -a 256 teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz

    Verify that the checksums match

    tar -xvf teleport-ent-v15.0.2-linux-$SYSTEM_ARCH-fips-bin.tar.gz
    cd teleport-ent
    sudo ./install

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Add the Teleport repository to your repository list:

    Download Teleport's PGP public key

    sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc

    Source variables about OS version

    source /etc/os-release

    Add the Teleport APT repository for cloud.

    echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Update the repo and install Teleport and the Teleport updater

    sudo apt-get update
    sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
    sudo yum install -y yum-utils
    sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo yum install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport YUM repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use the dnf config manager plugin to add the teleport RPM repo

    sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo dnf install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

    echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

    Source variables about OS version

    source /etc/os-release

    Add the Teleport Zypper repository for cloud.

    First, get the OS major version from $VERSION_ID so this fetches the correct

    package version.

    VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")

    Use Zypper to add the teleport RPM repo

    sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

    Provide your Teleport domain to query the latest compatible Teleport version

    export TELEPORT_DOMAIN=example.teleport.com
    export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Install Teleport and the Teleport updater

    sudo zypper install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

    OS repository channels

    The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v15 anywhere in the Teleport documentation.

    Channel nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling channel that receives all published Teleport releases

    Before installing a teleport binary with a version besides v14, read our compatibility rules to ensure that the binary is compatible with Teleport Enterprise Cloud.

    Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

    • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
    • Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
    • Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.
  2. Sign in to your Teleport cluster from your administrative workstation.

  3. Generate an invitation token for the cluster with the following command:

    tctl tokens add --type=windowsdesktop
  4. Copy the invitation token to a file on the Linux host that will run the Windows Desktop Service.

  5. Add the configuration for the Windows Desktop Service to the /etc/teleport.yaml on the Linux host.

    The /etc/teleport.yaml should include configuration settings similar to the following:

    version: v3
    teleport:
      auth_token: path-to-token
      proxy_server: teleport.example.com # replace with your proxy address
    windows_desktop_service:
      enabled: yes
      ldap:
        # Port must be included for the addr.
        # LDAPS port is 636 by default (example.com:636)
        addr: "$LDAP_SERVER_ADDRESS"
        domain: "$LDAP_DOMAIN_NAME"
        username: "$LDAP_USERNAME"
        sid: "$LDAP_USER_SID"
        # Path to the certificate you exported.
        der_ca_file: path-to-exported-cert
      discovery:
        base_dn: "*"
    auth_service:
      enabled: no
    proxy_service:
      enabled: no
    ssh_service:
      enabled: no
    

    For a detailed description of the configuration fields, see Desktop Configuration Reference.

  6. Configure the Teleport Desktop Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Desktop Service.

    On the host where you will run the Teleport Desktop Service, enable and start Teleport:

    sudo systemctl enable teleport
    sudo systemctl start teleport

    On the host where you will run the Teleport Desktop Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

    sudo teleport install systemd -o /etc/systemd/system/teleport.service
    sudo systemctl enable teleport
    sudo systemctl start teleport

    You can check the status of the Teleport Desktop Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 7/7. Log in using Teleport

Teleport users must have appropriate permissions to access remote Windows desktops. For example, you can create a role that gives its users access to all Windows desktop labels and the local "Administrator" user.

To create a role for accessing Windows desktops:

  1. Create a file called windows-desktop-admins.yaml with the following content:

    kind: role
    version: v5
    metadata:
      name: windows-desktop-admins
    spec:
      allow:
        windows_desktop_labels:
          "*": "*"
        windows_desktop_logins: ["jsmith"]
    

    Note that user names shared between domain and local users create login conflicts.

  2. Create the role:

    tctl create -f windows-desktop-admins.yaml
  3. Assign the windows-desktop-admins role to your Teleport user by running the appropriate commands for your authentication provider:

    1. Retrieve your local user's roles as a comma-separated list:

      ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
    2. Edit your local user to add the new role:

      tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},windows-desktop-admins"
    3. Sign out of the Teleport cluster and sign in again to assume the new role.

    1. Retrieve your github authentication connector:

      tctl get github/github --with-secrets > github.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.

    2. Edit github.yaml, adding windows-desktop-admins to the teams_to_roles section.

      The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

      Here is an example:

        teams_to_roles:
          - organization: octocats
            team: admins
            roles:
              - access
      +       - windows-desktop-admins
      
    3. Apply your changes:

      tctl create -f github.yaml
    4. Sign out of the Teleport cluster and sign in again to assume the new role.

    1. Retrieve your saml configuration resource:

      tctl get --with-secrets saml/mysaml > saml.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

    2. Edit saml.yaml, adding windows-desktop-admins to the attributes_to_roles section.

      The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

      Here is an example:

        attributes_to_roles:
          - name: "groups"
            value: "my-group"
            roles:
              - access
      +       - windows-desktop-admins
      
    3. Apply your changes:

      tctl create -f saml.yaml
    4. Sign out of the Teleport cluster and sign in again to assume the new role.

    1. Retrieve your oidc configuration resource:

      tctl get oidc/myoidc --with-secrets > oidc.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

    2. Edit oidc.yaml, adding windows-desktop-admins to the claims_to_roles section.

      The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

      Here is an example:

        claims_to_roles:
          - name: "groups"
            value: "my-group"
            roles:
              - access
      +       - windows-desktop-admins
      
    3. Apply your changes:

      tctl create -f oidc.yaml
    4. Sign out of the Teleport cluster and sign in again to assume the new role.

    Now that you have a Linux host running the Windows Desktop Service and a role that allows Teleport users to connect to Windows computers, you can use the Teleport user assigned the windows-desktop-admins role to connect to Windows desktops from the Teleport Web UI.

To connect to a Windows desktop:

  1. Sign in to the Teleport cluster using an account that's assigned the windows-desktop-admins role.

  2. Select Resources.

  3. Click Type, then select Desktops.

  4. Click Connect for the Windows computer you want to access, then select the login to use for the connection.

    Teleport opens a remote desktop connection and starts recording the desktop session. When you're finished working with the Windows desktop, click the More items menu, then click Disconnect.

    To view the recording, select Management in the Teleport Web UI, then click Session Recordings in the Activity section.

Security hardening

By default, the Default Domain Policy grants the Add workstations to domain user right to all authenticated users. As a security best practice, Teleport recommends that you only grant this right to administrators or other privileged groups.

To change the default domain policy:

  1. Open Group Policy Management and expand Forest, Domains, your domain, and Group Policy Objects.
  2. Right-click Default Domain Controller Policy, then select Edit.
  3. In the group policy editor, expand Computer Configuration, Policies, Windows Settings, Security Settings, Local Policies, and User Rights Assignment to select Add workstations to domain.
  4. 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.
  2. Configure Teleport to perform PKI against the root domain, while issuing certificates for users and hosts in the child domain:
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.

Next steps

If you encounter any issues, see Troubleshooting for common problems and solutions. For information about configuring Windows-specific role permissions, see Role-Based Access Control for Desktops.