diff --git a/docs/pages/admin-guides.mdx b/docs/pages/admin-guides.mdx index 4141a2e1bff9c..fc6592d7f0332 100644 --- a/docs/pages/admin-guides.mdx +++ b/docs/pages/admin-guides.mdx @@ -33,6 +33,8 @@ Guides for enrolling servers, databases, and other infrastructure resources with - [Protect Linux Servers with Teleport (section)](admin-guides/protect-resources/server-access.mdx): How to enroll Linux servers in your Teleport cluster to enable secure SSH access. - [Teleport Agents (section)](admin-guides/protect-resources/agents.mdx): How to use Teleport Agents, which enable users to connect to resources in your infrastructure. - [Teleport Auto-Discovery (section)](admin-guides/protect-resources/auto-discovery.mdx): Learn how to use the Teleport Discovery Service, which automatically enrolls resources by query APIs +- [Teleport Desktop Access (section)](admin-guides/protect-resources/desktop-access.mdx): How to proctect Windows Desktops with Teleport +- [Teleport Kubernetes Access (section)](admin-guides/protect-resources/kubernetes-access.mdx): Protect Kubernetes clusters with Teleport ## Self-Hosting Teleport diff --git a/docs/pages/admin-guides/protect-resources.mdx b/docs/pages/admin-guides/protect-resources.mdx index 9e6c2af2b25c4..6c90e0c02594a 100644 --- a/docs/pages/admin-guides/protect-resources.mdx +++ b/docs/pages/admin-guides/protect-resources.mdx @@ -44,3 +44,26 @@ Learn how to use the Teleport Discovery Service, which automatically enrolls res - [Automatically Enroll Kubernetes Clusters (section)](protect-resources/auto-discovery/kubernetes.mdx): Register Kubernetes clusters with your Teleport cluster by polling service discovery endpoints. - [Enroll Kubernetes Services as Teleport Applications (section)](protect-resources/auto-discovery/kubernetes-applications.mdx): Teleport can automatically detect applications running in your Kubernetes clusters and register them with Teleport for secure access. - [Server Auto-Discovery (section)](protect-resources/auto-discovery/servers.mdx): You can set up the Teleport Discovery Service to automatically enroll servers in your infrastructure. + +## Teleport Desktop Access + +How to proctect Windows Desktops with Teleport ([more info](protect-resources/desktop-access.mdx)) + +- [Automatic User Creation](protect-resources/desktop-access/user-creation.mdx): Using Automatic User Creation with Teleport desktop access. +- [Clipboard Sharing](protect-resources/desktop-access/clipboard.mdx): Using Clipboard Sharing with Teleport desktop access. +- [Configure access for Active Directory manually](protect-resources/desktop-access/active-directory-manual.mdx): Explains how to manually connect Teleport to an Active Directory domain. +- [Configure access for local Windows users](protect-resources/desktop-access/getting-started.mdx): Use Teleport to configure passwordless access for local Windows users. +- [Directory Sharing](protect-resources/desktop-access/directory-sharing.mdx): Teleport desktop Directory Sharing lets you easily send files to a remote desktop. +- [Manage Access to Windows Resources](protect-resources/desktop-access/introduction.mdx): Demonstrates how you can manage access to Windows desktops with Teleport. +- [Session Recording and Playback](protect-resources/desktop-access/sessions.mdx): Recording and playing back Teleport desktop access sessions. +- [Troubleshooting Desktop Access](protect-resources/desktop-access/troubleshooting.mdx): Common issues and resolutions for Teleport's desktop access + +## Teleport Kubernetes Access + +Protect Kubernetes clusters with Teleport ([more info](protect-resources/kubernetes-access.mdx)) + +- [Access Kubernetes Clusters with Teleport](protect-resources/kubernetes-access/introduction.mdx): Learn how Teleport can protect your Kubernetes clusters with RBAC, audit logging, and more. +- [Enroll a Kubernetes Cluster](protect-resources/kubernetes-access/getting-started.mdx): Demonstrates how to enroll a Kubernetes cluster as a resource protected by Teleport. +- [Kubernetes Access Troubleshooting](protect-resources/kubernetes-access/troubleshooting.mdx): Troubleshooting common issues with Kubernetes access +- [Registering Kubernetes Clusters with Teleport (section)](protect-resources/kubernetes-access/register-clusters.mdx): How to manually add a Kubernetes cluster to Teleport after creating it. +- [Setting Up Teleport Access Controls for Kubernetes](protect-resources/kubernetes-access/manage-access.mdx): How to configure Teleport roles to access clusters, groups, users, and resources in Kubernetes. diff --git a/docs/pages/admin-guides/protect-resources/desktop-access.mdx b/docs/pages/admin-guides/protect-resources/desktop-access.mdx new file mode 100644 index 0000000000000..c411f8060c073 --- /dev/null +++ b/docs/pages/admin-guides/protect-resources/desktop-access.mdx @@ -0,0 +1,15 @@ +--- +title: Teleport Desktop Access +description: How to proctect Windows Desktops with Teleport +--- + +{/*TOPICS*/} + +- [Automatic User Creation](desktop-access/user-creation.mdx): Using Automatic User Creation with Teleport desktop access. +- [Clipboard Sharing](desktop-access/clipboard.mdx): Using Clipboard Sharing with Teleport desktop access. +- [Configure access for Active Directory manually](desktop-access/active-directory-manual.mdx): Explains how to manually connect Teleport to an Active Directory domain. +- [Configure access for local Windows users](desktop-access/getting-started.mdx): Use Teleport to configure passwordless access for local Windows users. +- [Directory Sharing](desktop-access/directory-sharing.mdx): Teleport desktop Directory Sharing lets you easily send files to a remote desktop. +- [Manage Access to Windows Resources](desktop-access/introduction.mdx): Demonstrates how you can manage access to Windows desktops with Teleport. +- [Session Recording and Playback](desktop-access/sessions.mdx): Recording and playing back Teleport desktop access sessions. +- [Troubleshooting Desktop Access](desktop-access/troubleshooting.mdx): Common issues and resolutions for Teleport's desktop access diff --git a/docs/pages/desktop-access/active-directory.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/active-directory-manual.mdx similarity index 100% rename from docs/pages/desktop-access/active-directory.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/active-directory-manual.mdx diff --git a/docs/pages/admin-guides/protect-resources/desktop-access/active-directory.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/active-directory.mdx new file mode 100644 index 0000000000000..58ff6ee6a5ec6 --- /dev/null +++ b/docs/pages/admin-guides/protect-resources/desktop-access/active-directory.mdx @@ -0,0 +1,744 @@ +--- +title: Configure access for Active Directory manually +description: Explains how to manually connect Teleport to an Active Directory domain. +videoBanner: YvMqgcq0MTQ +--- + +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 >= (=teleport.version=). + + You can verify the tools you have installed by running the following commands: + + ```code + $ tctl version + # Teleport Enterprise v(=teleport.version=) go(=teleport.golang=) + + $ tsh version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + You can download these tools by following the appropriate [Installation + instructions](../installation.mdx#linux) 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. + +- Administrative access to a domain controller. + +- (!docs/pages/includes/tctl.mdx!) + +## Option 1: Automated configuration + +For relatively simple Active Directory environments, you can use the `tctl` generated configuration script +to bootstrap your Active Directory domain for use with Teleport. At a high level, the script does the following: + +1. Create a restrictive service account named `Teleport Service Account` with the SAM account name `svc-teleport` and create the necessary LDAP containers. +1. Prevent the service account from performing interactive logins by creating and linking a Group Policy Object (GPO) named `Block teleport-svc Interactive Login`. +1. Configure a GPO named `Teleport Access Policy` to allow Teleport connections, including: + - Importing the Teleport CA certificate. + - Configuring firewall rules. + - Allowing remote RDP connections. + - Enabling RemoteFX for improved remote desktop performance. +1. Read the LDAP CA certificate (required for secure LDAPS connections). +1. Generate a Teleport configuration file for the Windows Desktop Service. + +For more complex Active Directory environments, you may need to modify the generated script to meet your specific requirements. +It may also be easier to comprehend what the script does by following the manual configuration steps below. + +To use the `tctl` generated configuration script, run the following command: + +```bash +# Generate the script and save it to a file named configure-ad.ps1. +tctl desktop bootstrap > configure-ad.ps1 +``` + +After generating the script, transfer it to a Windows domain controller and run it in a PowerShell console. + +## Option 2: Manual configuration + +### 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. + +1. Create a service account with a randomly-generated password by copying and pasting + the following script into the PowerShell console: + + ```powershell + $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. + +1. Set the minimum permissions that must granted to the service account by running the + following script in the PowerShell console: + + ```powershell + # 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 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;" + ``` + +1. Get the security identifier for the new service account. + For example, run the following command: + + ```powershell + Get-AdUser -Identity $SamAccountName | Select SID + ``` + + The command returns the security identifier for the specified account: + + ```powershell + SID + --- + S-1-5-21-209875886-835680547-4265310078-1113 + ``` + +1. 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: + + ```powershell + $GPOName="Block teleport-svc Interactive Login" + ``` + +1. Create the new GPO by running the following command in the PowerShell console: + + ```powershell + 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. + +1. Select the group policy object, click **Action**, then select **Edit**. + +1. Expand **`Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment`**. + +1. Double-click **Deny log on locally**, then select **Define these policy settings**. + +1. Click **Add User or Group**, then click **Browse**. + +1. Type all or part of the service account name—for example, `svc-teleport`—then click **Check Names**. + +1. Verify the **Teleport Service Account** is selected, then click **OK** in all the dialogs. + +
+ ![Deny interactive login](../../img/desktop-access/deny-interactive-login.png) +
+ +1. 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**. + +1. 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: + + ```code + $ curl.exe -fo user-ca.cer https:///webapi/auth/export?type=windows + ``` + +1. 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: + + ```powershell + $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](../../img/desktop-access/aws-managed-ad.png) +
+ +1. Open **Group Policy Management** and expand Forest, Domains, your domain, and + Group Policy Objects to locate the GPO you just created. + +1. Select the new GPO—for example, `Teleport Access Policy`, right-click, then select **Edit**. + +1. In the group policy editor, expand + **`Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies`**. + +1. Right-click **Trusted Root Certification Authorities**, then click **Import**. + +1. Use the wizard to select and import the Teleport certificate. + +
+ ![Import Teleport CA](../../img/desktop-access/ca.png) +
+ +1. To ensure your GPO update takes effect immediately on this host, + open PowerShell and run the following command (optional): + + ```powershell + 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. + +1. Open PowerShell and run the following command using the path to the `user-ca.cer` + file you exported from Teleport: + + ```powershell + certutil -dspublish -f 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: + + ```powershell + certutil -dspublish -f NTAuthCA + ``` + +1. Force the retrieval of the CA from LDAP by running the following command: + + ```powershell + 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. + +1. Expand **`Computer Configuration > Policies > Windows Settings > Security Settings > System Services`**. + +1. Double-click **Smart Card** and select **Define this policy setting**. + +1. Select **Automatic**, then click **OK**. + +
+ ![Enable Smartcard](../../img/desktop-access/smartcard.png) +
+ +1. To ensure your GPO update takes effect immediately on this host, + open PowerShell and run the following command (optional): + + ```powershell + 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. + +1. Expand **`Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections`**. + +1. Right-click **Allow users to connect remotely by using Remote Desktop Services**, + select **Edit**, select **Enabled**, then click **OK**. + +1. Under Remote Desktop Session Host, select **Security**. + +1. Right-click **Require user authentication for remote connections by using + Network Level Authentication**, select **Edit**, select **Disabled**, then click **OK**. + +
+ ![Disable Require](../../img/desktop-access/disable.png) +
+ +1. 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. + +1. Expand Computer Configuration, Policies, Windows Settings, Security Settings to select + **Windows Firewall with Advanced Security**. + +1. 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](../../img/desktop-access/firewall.png) +
+ +1. To ensure your GPO update takes effect immediately on this host, + open PowerShell and run the following command (optional): + + ```powershell + 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. + +1. Expand **`Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment > RemoteFX for Windows Server 2008 R2`** + +1. Right-click **Configure RemoteFX**, select **Edit**, select **Enabled**, then click **OK**. + +1. 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](../../img/desktop-access/enable-remotefx.png) +
+ +1. 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**. + +1. Open PowerShell and run the following command to update your Teleport + group policy object: + + ```powershell + 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](#step-57-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**. + +1. Open your CA computer, right-click **Certificate Templates**, then select **Manage**. + +1. Select the *Computer* template, right-click, then select **Duplicate Template**. + +1. 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**. + +1. Select the **General** tab: + + - Change **Template display name** to **RemoteDesktopAccess**. + - Verify that **Template name** is also **RemoteDesktopAccess**. + +1. Select the **Cryptography** tab: + + - Change **Provider Category** to **Key Storage Provider**. + - Change **Algorithm name** to **ECDH_P384**. + - Change **Request hash** to **SHA384**. + +1. Select the **Extensions** tab: + + - Select **Application Polices**, then click **Edit**. + - Remove all entries from the list. + +1. Select the **Security** tab: + + - Select **Domain Computers** and give the group **Read** and **Enroll** permissions. + +1. Click **OK** to create the Template. + +1. Go back to the Certificate Authority console, right-click **Certificate Templates**. + +1. Click **New**, select **Certificate Template to Issue**, then select **RemoteDesktopAccess**. + +1. 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. + +1. Expand **`Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security`**. + +1. Right-click **Server authentication certificate template**, select **Edit**, select + **Enabled**, then set the Certificate Template Name to **RemoteDesktopAccess**. + +
+ ![RDP Certificate Template](../../img/desktop-access/rdp-certificate-template.png) +
+ +1. Expand Computer Configuration, Policies, and Windows Settings to select + **Public Key Policies**. + +1. Double-click **Certificate Services Client - Auto-Enrollment**, then select + **Enabled** in the Configuration Model. + +1. Open PowerShell and run the following command to update your Teleport + group policy object: + + ```powershell + 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: + +{/* Adapted from https://www.ibm.com/docs/it/rds/5.2.1?topic=security-exporting-certificate-from-active-directory-server */} + +1. Click Start, Control Panel, and Administrative Tools to select **Certificate Authority**. +1. Select your CA computer, right-click, then select **Properties**. +1. One the General tab, click **View Certificate**. +1. Select **Details**, then click **Copy to File**. +1. Click *Next* in the Certificate Export Wizard, and ensure that **DER encoded binary X.509 (.CER)** + is selected. +1. Select a name and location for the certificate and click through the wizard. +1. 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: + + (!docs/pages/includes/install-linux.mdx!) + +1. Sign in to your Teleport cluster from your administrative workstation. + +1. Generate an invitation token for the cluster with the following command: + + ```code + $ tctl tokens add --type=windowsdesktop + ``` + +1. Copy the invitation token to a file on the Linux host that will run the Windows Desktop + Service. + +1. 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: + + ```yaml + version: v3 + teleport: + auth_token: + proxy_server: # 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: + 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](./reference/configuration.mdx). + +1. (!docs/pages/includes/start-teleport.mdx service="the Teleport Desktop Service"!) + +### 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: + + ```yaml + 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. + +1. Create the role: + + ```code + $ tctl create -f windows-desktop-admins.yaml + ``` + +1. (!docs/pages/includes/add-role-to-user.mdx role="windows-desktop-admins"!) + + 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. + +1. Select **Resources**. + +1. Click **Type**, then select **Desktops**. + +1. Click **Connect** for the Windows computer you want to access, then select the + login to use for the connection. + + ![Connect to a Windows desktop from the Teleport Web UI](../../img/desktop-access/passwordless-desktop.png) + + 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**. + + ![Disconnect from a Windows desktop ](../../img/desktop-access/desktop-disconnect.png) + + 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. +1. Right-click **Default Domain Controller Policy**, then select **Edit**. +1. 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**. +1. 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`. + +## Next steps + +If you encounter any issues, see [Troubleshooting](./troubleshooting.mdx) for common problems and +solutions. +For information about configuring Windows-specific role permissions, see +[Role-Based Access Control for Desktops](./rbac.mdx). diff --git a/docs/pages/desktop-access/reference/clipboard.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/clipboard.mdx similarity index 100% rename from docs/pages/desktop-access/reference/clipboard.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/clipboard.mdx diff --git a/docs/pages/desktop-access/directory-sharing.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/directory-sharing.mdx similarity index 100% rename from docs/pages/desktop-access/directory-sharing.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/directory-sharing.mdx diff --git a/docs/pages/desktop-access/getting-started.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/getting-started.mdx similarity index 100% rename from docs/pages/desktop-access/getting-started.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/getting-started.mdx diff --git a/docs/pages/desktop-access/introduction.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/introduction.mdx similarity index 100% rename from docs/pages/desktop-access/introduction.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/introduction.mdx diff --git a/docs/pages/desktop-access/reference/sessions.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/sessions.mdx similarity index 97% rename from docs/pages/desktop-access/reference/sessions.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/sessions.mdx index 7e4903e2287d5..92450ace27b84 100644 --- a/docs/pages/desktop-access/reference/sessions.mdx +++ b/docs/pages/admin-guides/protect-resources/desktop-access/sessions.mdx @@ -62,7 +62,7 @@ Recorded sessions can be viewed in the *Session Recordings* page under the *Activity* section in the *Management* area. Desktop recordings show a desktop icon in the first column to distinguish them from SSH recordings. -![Desktop Session Recording](../../../img/desktop-access/session-recording@2x.png) +![Desktop Session Recording](../../../../img/desktop-access/session-recording@2x.png) Click the play button to open the player in a new tab. To export desktop session recordings to video for playback outside of Teleport, use the diff --git a/docs/pages/desktop-access/troubleshooting.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/troubleshooting.mdx similarity index 100% rename from docs/pages/desktop-access/troubleshooting.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/troubleshooting.mdx diff --git a/docs/pages/desktop-access/reference/user-creation.mdx b/docs/pages/admin-guides/protect-resources/desktop-access/user-creation.mdx similarity index 100% rename from docs/pages/desktop-access/reference/user-creation.mdx rename to docs/pages/admin-guides/protect-resources/desktop-access/user-creation.mdx diff --git a/docs/pages/kubernetes-access.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access.mdx similarity index 84% rename from docs/pages/kubernetes-access.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access.mdx index b7a273b80abb8..96d63052885d4 100644 --- a/docs/pages/kubernetes-access.mdx +++ b/docs/pages/admin-guides/protect-resources/kubernetes-access.mdx @@ -7,10 +7,8 @@ description: Protect Kubernetes clusters with Teleport - [Access Kubernetes Clusters with Teleport](kubernetes-access/introduction.mdx): Learn how Teleport can protect your Kubernetes clusters with RBAC, audit logging, and more. - [Enroll a Kubernetes Cluster](kubernetes-access/getting-started.mdx): Demonstrates how to enroll a Kubernetes cluster as a resource protected by Teleport. -- [Kubernetes Access FAQ](kubernetes-access/faq.mdx): Frequently asked questions about Teleport Kubernetes Access - [Kubernetes Access Troubleshooting](kubernetes-access/troubleshooting.mdx): Troubleshooting common issues with Kubernetes access - [Setting Up Teleport Access Controls for Kubernetes](kubernetes-access/manage-access.mdx): How to configure Teleport roles to access clusters, groups, users, and resources in Kubernetes. -- [Teleport Kubernetes Access Controls](kubernetes-access/controls.mdx): How the Teleport Kubernetes Service applies RBAC to manage access to Kubernetes ## Registering Kubernetes Clusters with Teleport diff --git a/docs/pages/kubernetes-access/getting-started.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/getting-started.mdx similarity index 100% rename from docs/pages/kubernetes-access/getting-started.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/getting-started.mdx diff --git a/docs/pages/kubernetes-access/introduction.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/introduction.mdx similarity index 100% rename from docs/pages/kubernetes-access/introduction.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/introduction.mdx diff --git a/docs/pages/kubernetes-access/manage-access.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/manage-access.mdx similarity index 100% rename from docs/pages/kubernetes-access/manage-access.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/manage-access.mdx diff --git a/docs/pages/kubernetes-access/register-clusters.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters.mdx similarity index 100% rename from docs/pages/kubernetes-access/register-clusters.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters.mdx diff --git a/docs/pages/kubernetes-access/register-clusters/dynamic-registration.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/dynamic-registration.mdx similarity index 100% rename from docs/pages/kubernetes-access/register-clusters/dynamic-registration.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/dynamic-registration.mdx diff --git a/docs/pages/kubernetes-access/register-clusters/iam-joining.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/iam-joining.mdx similarity index 100% rename from docs/pages/kubernetes-access/register-clusters/iam-joining.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/iam-joining.mdx diff --git a/docs/pages/kubernetes-access/register-clusters/static-kubeconfig.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/static-kubeconfig.mdx similarity index 100% rename from docs/pages/kubernetes-access/register-clusters/static-kubeconfig.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/register-clusters/static-kubeconfig.mdx diff --git a/docs/pages/kubernetes-access/troubleshooting.mdx b/docs/pages/admin-guides/protect-resources/kubernetes-access/troubleshooting.mdx similarity index 100% rename from docs/pages/kubernetes-access/troubleshooting.mdx rename to docs/pages/admin-guides/protect-resources/kubernetes-access/troubleshooting.mdx diff --git a/docs/pages/desktop-access.mdx b/docs/pages/desktop-access.mdx deleted file mode 100644 index ef4a1dc460154..0000000000000 --- a/docs/pages/desktop-access.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Teleport Desktop Access -description: How to proctect Windows Desktops with Teleport ---- - -{/*TOPICS*/} - -- [Configure access for Active Directory manually](desktop-access/active-directory.mdx): Explains how to manually connect Teleport to an Active Directory domain. -- [Configure access for local Windows users](desktop-access/getting-started.mdx): Use Teleport to configure passwordless access for local Windows users. -- [Directory Sharing](desktop-access/directory-sharing.mdx): Teleport desktop Directory Sharing lets you easily send files to a remote desktop. -- [Manage Access to Windows Resources](desktop-access/introduction.mdx): Demonstrates how you can manage access to Windows desktops with Teleport. -- [Role-Based Access Control for Desktops](desktop-access/rbac.mdx): Role-based access control (RBAC) for desktops protected by Teleport. -- [Troubleshooting Desktop Access](desktop-access/troubleshooting.mdx): Common issues and resolutions for Teleport's desktop access - -## Desktop Access Reference - -Comprehensive guides to configuring and auditing desktop access. ([more info](desktop-access/reference.mdx)) - -- [Automatic User Creation](desktop-access/reference/user-creation.mdx): Using Automatic User Creation with Teleport desktop access. -- [Clipboard Sharing](desktop-access/reference/clipboard.mdx): Using Clipboard Sharing with Teleport desktop access. -- [Desktop Access Audit Events Reference](desktop-access/reference/audit.mdx): Audit events reference for Teleport desktop access. -- [Desktop Access CLI Reference](desktop-access/reference/cli.mdx): CLI reference for Teleport desktop access. -- [Desktop Access Configuration Reference](desktop-access/reference/configuration.mdx): Configuration reference for Teleport desktop access. -- [Session Recording and Playback](desktop-access/reference/sessions.mdx): Recording and playing back Teleport desktop access sessions. diff --git a/docs/pages/desktop-access/reference.mdx b/docs/pages/desktop-access/reference.mdx deleted file mode 100644 index 1b203b73119c0..0000000000000 --- a/docs/pages/desktop-access/reference.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Desktop Access Reference -description: Comprehensive guides to configuring and auditing desktop access. -layout: tocless-doc ---- - -{/*TOPICS*/} - -- [Automatic User Creation](reference/user-creation.mdx): Using Automatic User Creation with Teleport desktop access. -- [Clipboard Sharing](reference/clipboard.mdx): Using Clipboard Sharing with Teleport desktop access. -- [Desktop Access Audit Events Reference](reference/audit.mdx): Audit events reference for Teleport desktop access. -- [Desktop Access CLI Reference](reference/cli.mdx): CLI reference for Teleport desktop access. -- [Desktop Access Configuration Reference](reference/configuration.mdx): Configuration reference for Teleport desktop access. -- [Session Recording and Playback](reference/sessions.mdx): Recording and playing back Teleport desktop access sessions. diff --git a/docs/pages/reference.mdx b/docs/pages/reference.mdx index 09b2afed55c95..5bfa87df09f5d 100644 --- a/docs/pages/reference.mdx +++ b/docs/pages/reference.mdx @@ -9,6 +9,7 @@ description: Comprehensive guides to commands, configuration options, and other Contains guides to frequently asked questions for various Teleport features and use cases. ([more info](reference/faq.mdx)) +- [Kubernetes Access FAQ](reference/faq/kubernetes-access.mdx): Frequently asked questions about Teleport Kubernetes Access - [Teleport Enterprise Cloud FAQ](reference/faq/cloud-hosting.mdx): Teleport cloud frequently asked questions. - [Teleport FAQ](reference/faq/faq.mdx): Frequently Asked Questions About Using Teleport @@ -29,6 +30,8 @@ References for concepts and tools available for operating Teleport. ([more info] Available options for configuring access to Teleport privileges and infrastructure resources. ([more info](reference/rbac.mdx)) - [Access Controls for Servers](reference/rbac/server-rbac.mdx): Role-based access control (RBAC) for Teleport server access. +- [Role-Based Access Control for Desktops](reference/rbac/desktop-access.mdx): Role-based access control (RBAC) for desktops protected by Teleport. +- [Teleport Kubernetes Access Controls](reference/rbac/controls.mdx): How the Teleport Kubernetes Service applies RBAC to manage access to Kubernetes ## Teleport Architecture Guides @@ -52,6 +55,7 @@ Guides to the inner workings of components within a Teleport cluster. ([more inf Comprehensive lists of commands, arguments, and flags for Teleport CLI tools. ([more info](reference/cli.mdx)) - [CLI Reference Introduction](reference/cli/overview.mdx): Detailed guide and reference documentation for Teleport's command line interface (CLI) tools. +- [Desktop Access CLI Reference](reference/cli/desktop-access.mdx): CLI reference for Teleport desktop access. - [tbot CLI reference](reference/cli/tbot.mdx): Comprehensive reference of subcommands, flags, and arguments for the tbot CLI tool. - [tctl CLI reference](reference/cli/tctl.mdx): Comprehensive reference of subcommands, flags, and arguments for the tctl CLI tool. - [teleport CLI Reference](reference/cli/teleport.mdx): Comprehensive reference of subcommands, flags, and arguments for the teleport CLI tool. @@ -61,6 +65,7 @@ Comprehensive lists of commands, arguments, and flags for Teleport CLI tools. ([ Comprehensive guides to configuring Teleport. ([more info](reference/config-references.mdx)) +- [Desktop Access Configuration Reference](reference/config-references/database-access-config.mdx): Configuration reference for Teleport desktop access. - [Helm Chart Reference (section)](reference/config-references/helm-reference.mdx): Comprehensive lists of configuration values in Teleport's Helm charts - [Predicate Language](reference/config-references/predicate-language.mdx): How to use Teleport's predicate language to define filter conditions. - [Teleport Configuration Reference](reference/config-references/config.mdx): The detailed guide and reference documentation for configuring Teleport for SSH and Kubernetes access. @@ -71,9 +76,9 @@ Comprehensive guides to configuring Teleport. ([more info](reference/config-refe How to obtain information about activity in your Teleport cluster. ([more info](reference/monitoring.mdx)) -- [Audit Events and Records](reference/monitoring/audit.mdx): Reference of Teleport Audit Events and Session Records - [Distributed Tracing Configuration Reference](reference/monitoring/configuration.mdx): Configuration reference for Distributed Tracing. - [Distributed Tracing](reference/monitoring/tracing.mdx): How to enable tracing within Teleport. - [Health Monitoring](reference/monitoring/monitoring.mdx): Monitoring health and readiness. - [Metrics](reference/monitoring/metrics.mdx): How to enable and consume metrics - [Profiling](reference/monitoring/profiles.mdx): Collecting pprof profiles. +- [Teleport Audit Event References (section)](reference/monitoring/audit.mdx): Reference guides to audit events that you can export and track in Teleport. diff --git a/docs/pages/reference/cli.mdx b/docs/pages/reference/cli.mdx index 8fbebebcceb21..4839854a4974a 100644 --- a/docs/pages/reference/cli.mdx +++ b/docs/pages/reference/cli.mdx @@ -6,6 +6,7 @@ description: Comprehensive lists of commands, arguments, and flags for Teleport {/*TOPICS*/} - [CLI Reference Introduction](cli/overview.mdx): Detailed guide and reference documentation for Teleport's command line interface (CLI) tools. +- [Desktop Access CLI Reference](cli/desktop-access.mdx): CLI reference for Teleport desktop access. - [tbot CLI reference](cli/tbot.mdx): Comprehensive reference of subcommands, flags, and arguments for the tbot CLI tool. - [tctl CLI reference](cli/tctl.mdx): Comprehensive reference of subcommands, flags, and arguments for the tctl CLI tool. - [teleport CLI Reference](cli/teleport.mdx): Comprehensive reference of subcommands, flags, and arguments for the teleport CLI tool. diff --git a/docs/pages/desktop-access/reference/cli.mdx b/docs/pages/reference/cli/desktop-access.mdx similarity index 100% rename from docs/pages/desktop-access/reference/cli.mdx rename to docs/pages/reference/cli/desktop-access.mdx diff --git a/docs/pages/reference/config-references.mdx b/docs/pages/reference/config-references.mdx index fbee02639d660..9d552d34e094c 100644 --- a/docs/pages/reference/config-references.mdx +++ b/docs/pages/reference/config-references.mdx @@ -5,6 +5,7 @@ description: Comprehensive guides to configuring Teleport. {/*TOPICS*/} +- [Desktop Access Configuration Reference](config-references/database-access-config.mdx): Configuration reference for Teleport desktop access. - [Predicate Language](config-references/predicate-language.mdx): How to use Teleport's predicate language to define filter conditions. - [Teleport Configuration Reference](config-references/config.mdx): The detailed guide and reference documentation for configuring Teleport for SSH and Kubernetes access. - [Teleport Resource Reference](config-references/resources.mdx): Reference documentation for Teleport resources diff --git a/docs/pages/desktop-access/reference/configuration.mdx b/docs/pages/reference/config-references/database-access-config.mdx similarity index 100% rename from docs/pages/desktop-access/reference/configuration.mdx rename to docs/pages/reference/config-references/database-access-config.mdx diff --git a/docs/pages/reference/faq.mdx b/docs/pages/reference/faq.mdx index 5329523b3b715..b823f0150e789 100644 --- a/docs/pages/reference/faq.mdx +++ b/docs/pages/reference/faq.mdx @@ -5,5 +5,6 @@ description: Contains guides to frequently asked questions for various Teleport {/*TOPICS*/} +- [Kubernetes Access FAQ](faq/kubernetes-access.mdx): Frequently asked questions about Teleport Kubernetes Access - [Teleport Enterprise Cloud FAQ](faq/cloud-hosting.mdx): Teleport cloud frequently asked questions. - [Teleport FAQ](faq/faq.mdx): Frequently Asked Questions About Using Teleport diff --git a/docs/pages/kubernetes-access/faq.mdx b/docs/pages/reference/faq/kubernetes-access.mdx similarity index 100% rename from docs/pages/kubernetes-access/faq.mdx rename to docs/pages/reference/faq/kubernetes-access.mdx diff --git a/docs/pages/reference/monitoring.mdx b/docs/pages/reference/monitoring.mdx index 2af6110da6786..2584229eb70db 100644 --- a/docs/pages/reference/monitoring.mdx +++ b/docs/pages/reference/monitoring.mdx @@ -5,9 +5,15 @@ description: How to obtain information about activity in your Teleport cluster. {/*TOPICS*/} -- [Audit Events and Records](monitoring/audit.mdx): Reference of Teleport Audit Events and Session Records - [Distributed Tracing Configuration Reference](monitoring/configuration.mdx): Configuration reference for Distributed Tracing. - [Distributed Tracing](monitoring/tracing.mdx): How to enable tracing within Teleport. - [Health Monitoring](monitoring/monitoring.mdx): Monitoring health and readiness. - [Metrics](monitoring/metrics.mdx): How to enable and consume metrics - [Profiling](monitoring/profiles.mdx): Collecting pprof profiles. + +## Teleport Audit Event References + +Reference guides to audit events that you can export and track in Teleport. ([more info](monitoring/audit.mdx)) + +- [Audit Events and Records](monitoring/audit/audit.mdx): Reference of Teleport Audit Events and Session Records +- [Desktop Access Audit Events Reference](monitoring/audit/desktop-events.mdx): Audit events reference for Teleport desktop access. diff --git a/docs/pages/reference/monitoring/audit.mdx b/docs/pages/reference/monitoring/audit.mdx index ff45f06ef67a5..85e774c784cc6 100644 --- a/docs/pages/reference/monitoring/audit.mdx +++ b/docs/pages/reference/monitoring/audit.mdx @@ -1,234 +1,9 @@ --- -title: Audit Events and Records -description: Reference of Teleport Audit Events and Session Records +title: Teleport Audit Event References +description: Reference guides to audit events that you can export and track in Teleport. --- -Teleport logs cluster activity by emitting various events into its audit log. -There are two components of the audit log: +{/*TOPICS*/} - - - -- **Cluster Events:** Teleport logs events like successful user logins along - with metadata like remote IP address, time, and the session ID. -- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and - can be replayed later. By default, the recording is done by Teleport Nodes, - but can be configured to be done by the proxy. - - - - -- **Cluster Events:** Teleport logs events like successful user logins along - with metadata like remote IP address, time, and the session ID. -- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and - can be replayed later. Teleport Cloud manages the storage of session - recording data. - - - - - - -You can use -[Enhanced Session Recording with BPF](../server-access/guides/bpf-session-recording.mdx) -to get even more comprehensive audit logs with advanced security. - - - -## Events - - - - -Teleport supports multiple storage backends for storing audit events. The `dir` -backend uses the local filesystem of an Auth Service host. When this backend is -used, events are written to the filesystem in JSON format. The `dir` backend rotates -the event file approximately once every 24 hours, but never deletes captured events. - -For High Availability configurations, users can refer to our -[Athena](./backends.mdx#athena), [DynamoDB](./backends.mdx#dynamodb) or -[Firestore](./backends.mdx#firestore) chapters for information on how to -configure the SSH events and recorded sessions to be stored on network storage. -When these backends are in use, audit events will eventually expire and be -removed from the log. The default retention period is 1 year, but this can be -overridden using the `retention_period` configuration parameter. - -It is even possible to store audit logs in multiple places at the same time. For -more information on how to configure the audit log, refer to the `storage` -section of the example configuration file in the -[Teleport Configuration Reference](./config.mdx). - -Let's examine the Teleport audit log using the `dir` backend. The event log is -stored in Teleport's data dir under the `log` directory. This is usually -`/var/lib/teleport/log`. Each day is represented as a file: - -```code -$ ls -l /var/lib/teleport/log/ - -# total 104 -# -rw-r----- 1 root root 31638 Jan 22 20:00 2017-01-23.00:00:00.log -# -rw-r----- 1 root root 91256 Jan 31 21:00 2017-02-01.00:00:00.log -# -rw-r----- 1 root root 15815 Feb 32 22:54 2017-02-03.00:00:00.log -``` - - - - -Teleport Enterprise Cloud manages the storage of audit logs for you. You can -access your audit logs via the Teleport Web UI by clicking: - -**Activity** > **Audit Log** - - - - -Audit logs use JSON format. They are human readable but can also be -programmatically parsed. Each line represents an event and has the following -format: - -```javascript -{ - // Event type. See below for the list of all possible event types. - "event": "session.start", - // A unique ID for the event log. Useful for deduplication. - "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef", - // Teleport user name - "user": "ekontsevoy", - // OS login - "login": "root", - // Server namespace. This field is reserved for future use. - "namespace": "default", - // Unique server ID - "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f", - // Server Labels - "server_labels": { - "datacenter": "us-east-1", - "label-b": "x" - } - // Session ID. Can be used to replay the session. - "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931", - // Address of the SSH node - "addr.local": "10.5.l.15:3022", - // Address of the connecting client (user) - "addr.remote": "73.223.221.14:42146", - // Terminal size - "size": "80:25", - // Timestamp - "time": "2017-02-03T06:54:05Z" -} -``` - -## Event types - -Below are some possible types of audit events. - - - -This list is not comprehensive. We recommend exporting audit events to a -platform that automatically parses event payloads so you can group and filter -them by their `event` key and discover trends. To set up audit event exporting, -read [Exporting Teleport Audit Events](../management/export-audit-events.mdx). - - - -| Event Type | Description | -| - | - | -| auth | Authentication attempt. Adds the following fields: `{"success": "false", "error": "access denied"}` | -| session.start | Started an interactive shell session. | -| session.end | An interactive shell session has ended. | -| session.join | A new user has joined the existing interactive shell session. | -| session.leave | A user has left the session. | -| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. | -| session.network | A list of network connections made during the session. *Requires Enhanced Session Recording*. | -| session.command | A list of commands ran during the session. *Requires Enhanced Session Recording*. | -| session.recording.access | A session recording has been accessed. | -| exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /`. The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` | -| scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` | -| resize | Terminal has been resized. | -| user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` . | -| app.session.start | A user accessed an application | -| app.session.chunk | A record of activity during an app session | -| join_token.create | A new join token has been created. Adds the following fields: `{"roles": ["Node", "Db"], "join_method": "token"}` | - -## Recorded sessions - -In addition to logging start and end events, Teleport can also record the entire session. -For SSH or Kubernetes sessions this captures the entire stream of bytes from the PTY. -For desktop sessions the recording includes the contents of the screen. - - - - -Teleport can store the recorded sessions in an [AWS S3 bucket](./backends.mdx#s3) -or in a local filesystem (including NFS). - -The recorded sessions are stored as raw bytes in the `sessions` directory under -`log`. Each session is a protobuf-encoded stream of binary data. - -You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) -command or the Web UI. - -For example, replay a session via CLI: - -```code -$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 -``` - -Print the session events in JSON to stdout: - -```code -$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json -``` - - - - -Teleport Enterprise Cloud automatically stores recorded sessions. - -You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) -command or the Web UI. - -For example, replay a session via CLI: - -```code -$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 -``` - -Print the session events in JSON to stdout: - -```code -$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json -``` - - - - -### Modes - - -Available only for SSH sessions and when Teleport is configured with -`auth_service.session_recording: node`. - - -Modes define how Teleport deals with recording failures, such as a full disk -error. They are configured per-service at the role level, where the strictest -value takes precedence. The available modes are: - -|Mode|After a recording failure| -|----|-------------------------| -|Best effort (`best_effort`)|Disables recording without terminating the session.| -|Strict (`strict`)|Immediately terminates the session.| - -If the user role doesn’t specify a recording mode, `best_effort` will be used. Here -is an example of a role configured to use strict mode for SSH sessions: - -```yaml -kind: role -version: v5 -metadata: - name: ssh-strict -spec: - options: - record_session: - ssh: strict -``` +- [Audit Events and Records](audit/audit.mdx): Reference of Teleport Audit Events and Session Records +- [Desktop Access Audit Events Reference](audit/desktop-events.mdx): Audit events reference for Teleport desktop access. diff --git a/docs/pages/reference/monitoring/audit/audit.mdx b/docs/pages/reference/monitoring/audit/audit.mdx new file mode 100644 index 0000000000000..ff45f06ef67a5 --- /dev/null +++ b/docs/pages/reference/monitoring/audit/audit.mdx @@ -0,0 +1,234 @@ +--- +title: Audit Events and Records +description: Reference of Teleport Audit Events and Session Records +--- + +Teleport logs cluster activity by emitting various events into its audit log. +There are two components of the audit log: + + + + +- **Cluster Events:** Teleport logs events like successful user logins along + with metadata like remote IP address, time, and the session ID. +- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and + can be replayed later. By default, the recording is done by Teleport Nodes, + but can be configured to be done by the proxy. + + + + +- **Cluster Events:** Teleport logs events like successful user logins along + with metadata like remote IP address, time, and the session ID. +- **Recorded Sessions:** Every SSH, desktop, or Kubernetes shell session is recorded and + can be replayed later. Teleport Cloud manages the storage of session + recording data. + + + + + + +You can use +[Enhanced Session Recording with BPF](../server-access/guides/bpf-session-recording.mdx) +to get even more comprehensive audit logs with advanced security. + + + +## Events + + + + +Teleport supports multiple storage backends for storing audit events. The `dir` +backend uses the local filesystem of an Auth Service host. When this backend is +used, events are written to the filesystem in JSON format. The `dir` backend rotates +the event file approximately once every 24 hours, but never deletes captured events. + +For High Availability configurations, users can refer to our +[Athena](./backends.mdx#athena), [DynamoDB](./backends.mdx#dynamodb) or +[Firestore](./backends.mdx#firestore) chapters for information on how to +configure the SSH events and recorded sessions to be stored on network storage. +When these backends are in use, audit events will eventually expire and be +removed from the log. The default retention period is 1 year, but this can be +overridden using the `retention_period` configuration parameter. + +It is even possible to store audit logs in multiple places at the same time. For +more information on how to configure the audit log, refer to the `storage` +section of the example configuration file in the +[Teleport Configuration Reference](./config.mdx). + +Let's examine the Teleport audit log using the `dir` backend. The event log is +stored in Teleport's data dir under the `log` directory. This is usually +`/var/lib/teleport/log`. Each day is represented as a file: + +```code +$ ls -l /var/lib/teleport/log/ + +# total 104 +# -rw-r----- 1 root root 31638 Jan 22 20:00 2017-01-23.00:00:00.log +# -rw-r----- 1 root root 91256 Jan 31 21:00 2017-02-01.00:00:00.log +# -rw-r----- 1 root root 15815 Feb 32 22:54 2017-02-03.00:00:00.log +``` + + + + +Teleport Enterprise Cloud manages the storage of audit logs for you. You can +access your audit logs via the Teleport Web UI by clicking: + +**Activity** > **Audit Log** + + + + +Audit logs use JSON format. They are human readable but can also be +programmatically parsed. Each line represents an event and has the following +format: + +```javascript +{ + // Event type. See below for the list of all possible event types. + "event": "session.start", + // A unique ID for the event log. Useful for deduplication. + "uid": "59cf8d1b-7b36-4894-8e90-9d9713b6b9ef", + // Teleport user name + "user": "ekontsevoy", + // OS login + "login": "root", + // Server namespace. This field is reserved for future use. + "namespace": "default", + // Unique server ID + "server_id": "f84f7386-5e22-45ff-8f7d-b8079742e63f", + // Server Labels + "server_labels": { + "datacenter": "us-east-1", + "label-b": "x" + } + // Session ID. Can be used to replay the session. + "sid": "8d3895b6-e9dd-11e6-94de-40167e68e931", + // Address of the SSH node + "addr.local": "10.5.l.15:3022", + // Address of the connecting client (user) + "addr.remote": "73.223.221.14:42146", + // Terminal size + "size": "80:25", + // Timestamp + "time": "2017-02-03T06:54:05Z" +} +``` + +## Event types + +Below are some possible types of audit events. + + + +This list is not comprehensive. We recommend exporting audit events to a +platform that automatically parses event payloads so you can group and filter +them by their `event` key and discover trends. To set up audit event exporting, +read [Exporting Teleport Audit Events](../management/export-audit-events.mdx). + + + +| Event Type | Description | +| - | - | +| auth | Authentication attempt. Adds the following fields: `{"success": "false", "error": "access denied"}` | +| session.start | Started an interactive shell session. | +| session.end | An interactive shell session has ended. | +| session.join | A new user has joined the existing interactive shell session. | +| session.leave | A user has left the session. | +| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. | +| session.network | A list of network connections made during the session. *Requires Enhanced Session Recording*. | +| session.command | A list of commands ran during the session. *Requires Enhanced Session Recording*. | +| session.recording.access | A session recording has been accessed. | +| exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /`. The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` | +| scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` | +| resize | Terminal has been resized. | +| user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` . | +| app.session.start | A user accessed an application | +| app.session.chunk | A record of activity during an app session | +| join_token.create | A new join token has been created. Adds the following fields: `{"roles": ["Node", "Db"], "join_method": "token"}` | + +## Recorded sessions + +In addition to logging start and end events, Teleport can also record the entire session. +For SSH or Kubernetes sessions this captures the entire stream of bytes from the PTY. +For desktop sessions the recording includes the contents of the screen. + + + + +Teleport can store the recorded sessions in an [AWS S3 bucket](./backends.mdx#s3) +or in a local filesystem (including NFS). + +The recorded sessions are stored as raw bytes in the `sessions` directory under +`log`. Each session is a protobuf-encoded stream of binary data. + +You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) +command or the Web UI. + +For example, replay a session via CLI: + +```code +$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 +``` + +Print the session events in JSON to stdout: + +```code +$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json +``` + + + + +Teleport Enterprise Cloud automatically stores recorded sessions. + +You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) +command or the Web UI. + +For example, replay a session via CLI: + +```code +$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 +``` + +Print the session events in JSON to stdout: + +```code +$ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json +``` + + + + +### Modes + + +Available only for SSH sessions and when Teleport is configured with +`auth_service.session_recording: node`. + + +Modes define how Teleport deals with recording failures, such as a full disk +error. They are configured per-service at the role level, where the strictest +value takes precedence. The available modes are: + +|Mode|After a recording failure| +|----|-------------------------| +|Best effort (`best_effort`)|Disables recording without terminating the session.| +|Strict (`strict`)|Immediately terminates the session.| + +If the user role doesn’t specify a recording mode, `best_effort` will be used. Here +is an example of a role configured to use strict mode for SSH sessions: + +```yaml +kind: role +version: v5 +metadata: + name: ssh-strict +spec: + options: + record_session: + ssh: strict +``` diff --git a/docs/pages/desktop-access/reference/audit.mdx b/docs/pages/reference/monitoring/audit/desktop-events.mdx similarity index 100% rename from docs/pages/desktop-access/reference/audit.mdx rename to docs/pages/reference/monitoring/audit/desktop-events.mdx diff --git a/docs/pages/reference/rbac.mdx b/docs/pages/reference/rbac.mdx index 471300b42865e..4eb98953919b7 100644 --- a/docs/pages/reference/rbac.mdx +++ b/docs/pages/reference/rbac.mdx @@ -6,3 +6,5 @@ description: Available options for configuring access to Teleport privileges and {/*TOPICS*/} - [Access Controls for Servers](rbac/server-rbac.mdx): Role-based access control (RBAC) for Teleport server access. +- [Role-Based Access Control for Desktops](rbac/desktop-access.mdx): Role-based access control (RBAC) for desktops protected by Teleport. +- [Teleport Kubernetes Access Controls](rbac/controls.mdx): How the Teleport Kubernetes Service applies RBAC to manage access to Kubernetes diff --git a/docs/pages/kubernetes-access/controls.mdx b/docs/pages/reference/rbac/controls.mdx similarity index 99% rename from docs/pages/kubernetes-access/controls.mdx rename to docs/pages/reference/rbac/controls.mdx index 92fccb3b6b821..c1c36b4285f45 100644 --- a/docs/pages/kubernetes-access/controls.mdx +++ b/docs/pages/reference/rbac/controls.mdx @@ -201,7 +201,7 @@ headers](https://kubernetes.io/docs/reference/access-authn-authz/authentication/ to send requests to the API server with one Kubernetes user and zero or more Kubernetes groups. -![Impersonation](../../img/k8s/auth.svg) +![Impersonation](../../../../img/k8s/auth.svg) The `kubernetes_users` and `kubernetes_groups` fields indicate which users and groups to allow a user to assume when they send requests to a Kubernetes API diff --git a/docs/pages/desktop-access/rbac.mdx b/docs/pages/reference/rbac/desktop-access.mdx similarity index 100% rename from docs/pages/desktop-access/rbac.mdx rename to docs/pages/reference/rbac/desktop-access.mdx diff --git a/package.json b/package.json index 8b6232cdf6713..c0fce57d436fa 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "teleport-ui", "version": "1.0.0", "scripts": { - "all-topics": "node docs/gen-topic-pages/index.js --in docs/pages/admin-guides,docs/pages/database-access,docs/pages/access-controls,docs/pages/desktop-access,docs/pages/kubernetes-access,docs/pages/connect-your-client,docs/pages/machine-id,docs/pages/reference,docs/pages/application-access", + "all-topics": "node docs/gen-topic-pages/index.js --in docs/pages/admin-guides,docs/pages/database-access,docs/pages/access-controls,docs/pages/connect-your-client,docs/pages/machine-id,docs/pages/reference,docs/pages/application-access", "build-ui": "yarn build-ui-oss && yarn build-ui-e", "build-ui-oss": "yarn workspace @gravitational/teleport build", "build-ui-e": "yarn workspace @gravitational/teleport.e build",