diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx index dd454cd75d2a0..365a1c23f58ba 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx @@ -323,9 +323,7 @@ should still check the Teleport audit log to ensure that the right users are reviewing the right requests. When auditing Access Request reviews, check for events with the type `Access -Request Reviewed` in the Teleport Web UI and `access_request.review` if reviewing the audit log on the -Auth Service host. +Request Reviewed` in the Teleport Web UI. diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx index 4e923f594a163..5feb9c74f246c 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx @@ -29,20 +29,23 @@ Requests in the Proxy or Auth Service. ## Step 2/8. Install the Teleport Mattermost plugin - + + We recommend installing Teleport plugins on the same host as the Teleport Proxy Service. This is an ideal location as plugins have a low memory footprint, and will require both public internet access and Teleport Auth Service access. - + - + Install the Teleport Mattermost plugin on a host that can access both your Teleport Proxy Service and your Mattermost deployment. - + + + (!docs/pages/includes/plugins/install-access-request.mdx name="mattermost"!) @@ -314,9 +317,7 @@ Requests, you should still check the Teleport audit log to ensure that the right users are reviewing the right requests. When auditing Access Request reviews, check for events with the type `Access -Request Reviewed` in the Teleport Web UI and `access_request.review` if reviewing the audit log on the -Auth Service host. +Request Reviewed` in the Teleport Web UI. diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx index bcb27862b7e08..5dccb043cf33a 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx @@ -509,9 +509,7 @@ should still check the Teleport audit log to ensure that the right users are reviewing the right requests. When auditing Access Request reviews, check for events with the type `Access -Request Reviewed` in the Teleport Web UI and `access_request.review` if reviewing the audit log on the -Auth Service host. +Request Reviewed` in the Teleport Web UI. diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx index d4799fe6aac0c..164b43f9d78a7 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx @@ -272,8 +272,9 @@ As with all Teleport users, the Teleport Auth Service authenticates the will need to request the credentials manually by *impersonating* the `access-plugin` role and user. -If you are using `tctl` from the Auth -Service host, you will already have impersonation privileges. +If you are running a self-hosted Teleport Enterprise cluster and are using +`tctl` from the Auth Service host, you will already have impersonation +privileges. To grant your user impersonation privileges for `access-plugin`, define a role called `access-plugin-impersonator` by pasting the following YAML document into @@ -568,9 +569,7 @@ should still check the Teleport audit log to ensure that the right users are reviewing the right requests. When auditing Access Request reviews, check for events with the type `Access -Request Reviewed` in the Teleport Web UI and `access_request.review` if reviewing the audit log on the -Auth Service host. +Request Reviewed` in the Teleport Web UI. diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx index bea801f1ea80e..4ffa6d0eaa80c 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx @@ -365,9 +365,7 @@ should still check the Teleport audit log to ensure that the right users are reviewing the right requests. When auditing Access Request reviews, check for events with the type `Access -Request Reviewed` in the Teleport Web UI and `access_request.review` if reviewing the audit log on the -Auth Service host. +Request Reviewed` in the Teleport Web UI. diff --git a/docs/pages/access-controls/access-requests/resource-requests.mdx b/docs/pages/access-controls/access-requests/resource-requests.mdx index f7b3514f5f7fd..49dd0578df16d 100644 --- a/docs/pages/access-controls/access-requests/resource-requests.mdx +++ b/docs/pages/access-controls/access-requests/resource-requests.mdx @@ -13,16 +13,12 @@ under the hood. The Access Request API makes it easy to dynamically approve or deny these requests. - - Just-in-time Access Requests are a feature of Teleport Enterprise. Open-source Teleport users can get a preview of how Access Requests work by requesting a role via the Teleport CLI. Full Access Request functionality, including Resource Access Requests and an intuitive and searchable UI are available in Teleport Enterprise. - - ## Prerequisites (!docs/pages/includes/commercial-prereqs-tabs.mdx!) diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx index 0e308d1cb921e..02b201c75a98f 100644 --- a/docs/pages/access-controls/getting-started.mdx +++ b/docs/pages/access-controls/getting-started.mdx @@ -56,7 +56,8 @@ will be able to act as a system administrator and auditor at the same time. Next, follow the instructions to set up an authentication connector that maps users within your SSO solution to Teleport roles. - + + Save the file below as `github.yaml` and update the fields. You will need to set up a @@ -93,9 +94,9 @@ users within your SSO solution to Teleport roles. $ tctl create github.yaml ``` - + - + Create a SAML or OIDC application that Teleport can integrate with, then create an authentication connector that maps users within your application to @@ -152,7 +153,8 @@ users within your SSO solution to Teleport roles. - + + ## Step 3/3. Create a custom role @@ -215,3 +217,4 @@ $ tctl get roles --format text - [Mapping SSO and local users traits with role templates](./guides/role-templates.mdx) - [Create certs for CI/CD using impersonation](./guides/impersonation.mdx) + diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx index b9c9d1ef61be1..fb5b4d65d3bbc 100644 --- a/docs/pages/access-controls/guides/dual-authz.mdx +++ b/docs/pages/access-controls/guides/dual-authz.mdx @@ -208,13 +208,10 @@ Bob can also assume granted Access Request roles using Web UI: ![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png) -{/* TODO: This H2 will show up in the table of contents when this section is invisible. -We need a way to hide invisible H2s from the TOC. */} - ## Troubleshooting -### Cert errors in self-hosted deployments +### Certificate errors in self-hosted deployments You may be getting certificate errors if Teleport's Auth Service is missing an address in the server certificate: @@ -232,5 +229,3 @@ To fix the problem, update the Auth Service with a public address, and restart T auth_service: public_addr: ['localhost:3025', 'example.com:3025'] ``` - - diff --git a/docs/pages/access-controls/guides/hardware-key-support.mdx b/docs/pages/access-controls/guides/hardware-key-support.mdx index 3ad81d9b18ac8..e0090a85f78d3 100644 --- a/docs/pages/access-controls/guides/hardware-key-support.mdx +++ b/docs/pages/access-controls/guides/hardware-key-support.mdx @@ -129,8 +129,6 @@ role or to that cluster must use their hardware key for all Teleport requests. Affected users will be prompted to connect and touch their YubiKey to sign in. The first time users sign in with their hardware key they might be required to immediately sign in again. - - ```code $ tsh login --user=dev --proxy=proxy.example.com:3080 # Enter password for Teleport user dev: @@ -142,28 +140,8 @@ $ tsh login --user=dev --proxy=proxy.example.com:3080 # Logged in as: dev # Cluster: example.com # ... - ``` - - - - -```code -$ tsh login --user=dev --proxy=proxy.example.com:3080 -# Enter password for Teleport user dev: -# Unmet private key policy "hardware_key_touch". -# Relogging in with hardware-backed private key. -# Enter password for Teleport user dev: -# Tap your YubiKey -# > Profile URL: https://example.com -# Logged in as: dev -# Cluster: example.com -# ... -``` - - - Affected users with existing sessions that aren't backed by a hardware key are prompted to sign in again on their next request. For example: @@ -258,4 +236,4 @@ Detected security key tap Logged in as: dev Cluster: root.example.com ... -``` \ No newline at end of file +``` diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx index 9ee8285164a2e..f158ffcaf0357 100644 --- a/docs/pages/access-controls/guides/impersonation.mdx +++ b/docs/pages/access-controls/guides/impersonation.mdx @@ -118,22 +118,25 @@ $ tctl users add alice --roles=impersonator,access Alice can log in using `tsh` and issue a cert for `jenkins`: - + + ```code $ tsh login --proxy=proxy.example.com --user=alice --auth=local $ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local $ tctl auth sign --user=jenkins --format=openssh --out=jenkins --ttl=240h ``` - + + + Here is an example of how Alice can use the keys: @@ -310,7 +313,8 @@ scanner. Alice will need to log in again to receive the newly updated traits: - + + ```code # Once Alice logs in again, she will receive a new certificate with updated roles. @@ -319,8 +323,8 @@ $ tsh login --proxy=teleport.example.com --user=alice --auth=local $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h ``` - - + + ```code # Once Alice logs in again, she will receive a new certificate with updated roles. @@ -329,7 +333,9 @@ $ tsh login --proxy=mytenant.teleport.sh --user=alice --auth=local $ tctl auth sign --user=security-scanner --format=openssh --out=security-scanner --ttl=10h ``` - + + + ### Filter fields @@ -343,3 +349,4 @@ Here is an explanation of the fields used in the `where` conditions within this Check out our [predicate language](../../reference/predicate-language.mdx#scoping-allowdeny-rules-in-role-resources) guide for a more in depth explanation of the language. + diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx index e51edd869103e..5abea47a7fb2e 100644 --- a/docs/pages/access-controls/guides/locking.mdx +++ b/docs/pages/access-controls/guides/locking.mdx @@ -199,7 +199,8 @@ the last known locks. This decision strategy is encoded as one of the two modes: guaranteed to be up to date - `best_effort` mode keeps relying on the most recent locks - + + The cluster-wide mode defaults to `best_effort`. You can set up the default locking mode via API or CLI using a `cluster_auth_preference` resource or static @@ -240,8 +241,8 @@ configuration file: - - + + The cluster-wide mode defaults to `best_effort`. You can set up the default locking mode via API or CLI using a `cluster_auth_preference` resource: @@ -265,7 +266,9 @@ $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - + + + It is also possible to configure the locking mode for a particular role: @@ -285,3 +288,4 @@ there is no user involved, the mode is taken from the cluster-wide setting. With multiple potentially conflicting locking modes (the cluster-wide default and the individual per-role settings) a single occurrence of `strict` suffices for the local lock view to become evaluated strictly. + diff --git a/docs/pages/access-controls/guides/passwordless.mdx b/docs/pages/access-controls/guides/passwordless.mdx index b365b4e6c40f7..f7eef63677514 100644 --- a/docs/pages/access-controls/guides/passwordless.mdx +++ b/docs/pages/access-controls/guides/passwordless.mdx @@ -102,7 +102,8 @@ passwordless registration. To enable passwordless by default, add `connector_name: passwordless` to your cluster configuration: - + + Auth Server `teleport.yaml` file: @@ -142,9 +143,9 @@ cluster configuration: ``` - + - + Create a `cap.yaml` file or get the existing configuration using `tctl get cluster_auth_preference`: @@ -167,7 +168,9 @@ Update the configuration: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - + + + ## Troubleshooting @@ -241,7 +244,8 @@ $ tsh webauthnwin diag If you want to forbid passwordless access to your cluster, add `passwordless: false` to your configuration: - + + Auth Server `teleport.yaml` file: @@ -282,9 +286,9 @@ false` to your configuration: ``` - + - + Create a `cap.yaml` file or get the existing configuration using `tctl get cluster_auth_preference`: @@ -307,4 +311,7 @@ Update the configuration: $ tctl create -f cap.yaml # cluster auth preference has been updated ``` - + + + + diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index eb4f8aa49e4a3..79f67f0e66564 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -70,7 +70,8 @@ Per-session MFA can be enforced cluster-wide or only for some specific roles. ### Cluster-wide - + + To enforce MFA checks for all roles, edit your cluster authentication configuration: @@ -118,8 +119,8 @@ $ tctl create -f cap.yaml - - + + Obtain your existing `cluster_auth_preference` resource: @@ -146,7 +147,9 @@ Create the resource: $ tctl create -f cap.yaml ``` - + + + ### Per role diff --git a/docs/pages/access-controls/guides/role-templates.mdx b/docs/pages/access-controls/guides/role-templates.mdx index 999e6a7fc5d88..ca5c599dd8978 100644 --- a/docs/pages/access-controls/guides/role-templates.mdx +++ b/docs/pages/access-controls/guides/role-templates.mdx @@ -152,7 +152,8 @@ $ tctl create -f traits.yaml Once Alice logs in, she will receive SSH and X.509 certificates with a new role. SSH logins and Kubernetes groups will also be set: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -168,8 +169,8 @@ $ tsh login --proxy=teleport.example.com --user=alice # Extensions: permit-port-forwarding, permit-pty ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -185,7 +186,9 @@ $ tsh login --proxy=mytenant.teleport.sh --user=alice # Extensions: permit-port-forwarding, permit-pty ``` - + + + ## SSO users @@ -260,7 +263,8 @@ $ tctl create -f github.yaml Once Bob logs in using SSO, he will receive SSH and X.509 certificates with a new role and SSH logins generated using the `sso-users` role template: - + + ```code $ tsh login --proxy=teleport.example.com --auth=github @@ -276,8 +280,8 @@ $ tsh login --proxy=teleport.example.com --auth=github # Extensions: permit-port-forwarding, permit-pty ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --auth=github @@ -293,7 +297,9 @@ $ tsh login --proxy=mytenant.teleport.sh --auth=github # Extensions: permit-port-forwarding, permit-pty ``` - + + + ## Interpolation rules @@ -440,3 +446,4 @@ In this case, Alice would be allowed to request access to the RBAC roles `access role list) and `alpha-admin` and `beta-admin` (from the `claims_to_roles` mapping). The same syntax applies for Review Requests. + diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index 243483cfe8085..c608e5f4ba07c 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -179,31 +179,11 @@ Reference](../../reference/cli/tsh.mdx#tsh-global-flags) page. Once a WebAuthn device is registered, the user will be prompted for it on login: - - ```code -$ tsh login --proxy=example.com +$ tsh login --proxy=example.teleport.sh # Enter password for Teleport user codingllama: # Tap any security key or enter a code from a OTP device: -# > Profile URL: https://example.com -# Logged in as: codingllama -# Cluster: example.com -# Roles: access, editor -# Logins: codingllama -# Kubernetes: enabled -# Valid until: 2021-10-04 23:32:29 -0700 PDT [valid for 12h0m0s] -# Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -``` - - - - - -```code -$ tsh login --proxy=mytenant.teleport.sh -# Enter password for Teleport user codingllama: -# Tap any security key or enter a code from a OTP device: -# > Profile URL: https://mytenant.teleport.sh +# > Profile URL: https://example.teleport.sh # Logged in as: codingllama # Cluster: mytenant.teleport.sh # Roles: access, editor @@ -213,8 +193,6 @@ $ tsh login --proxy=mytenant.teleport.sh # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - WebAuthn for logging in to Teleport is only required for [local users]( ../../reference/authentication.mdx#local-no-authentication-connector). @@ -254,7 +232,8 @@ auth_service: The migrated WebAuthn configuration is: - + + @@ -299,9 +278,9 @@ The migrated WebAuthn configuration is: - + - + ```yaml kind: cluster_auth_preference @@ -322,9 +301,12 @@ spec: - "/path/to/u2f_attestation_ca.pem" ``` - + + + ## Next steps - [Passwordless](./passwordless.mdx) - [Set up per-session MFA checks](./per-session-mfa.mdx) + diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index 8b08ce465818c..9eefaa33916ee 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -34,7 +34,8 @@ To manage cluster roles, a Teleport administrator can use the Web UI or the command line using [tctl resource commands](../reference/resources.mdx). To see the list of roles in a Teleport cluster, an administrator can execute: - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -44,8 +45,8 @@ $ tsh login --user=myuser --proxy=teleport.example.com $ tctl get roles ``` - - + + ```code # Log in to your cluster with tsh so you can use tctl. @@ -53,7 +54,9 @@ $ tsh login --user=myuser --proxy=mytenant.teleport.sh $ tctl get roles ``` - + + + (!docs/pages/includes/backup-warning.mdx!) @@ -373,3 +376,4 @@ Here is an explanation of the fields used in the `where` and `filter` conditions Check out our [predicate language](../reference/predicate-language.mdx#scoping-allowdeny-rules-in-role-resources) guide for a more in depth explanation of the language. + diff --git a/docs/pages/access-controls/sso.mdx b/docs/pages/access-controls/sso.mdx index 7510983f447c5..686f5ecc049c3 100644 --- a/docs/pages/access-controls/sso.mdx +++ b/docs/pages/access-controls/sso.mdx @@ -46,7 +46,8 @@ information about the temporary user. You can inspect a temporary `user` resource created via your SSO integration by using the `tctl` command: - + + ```code # Log in to your cluster with tsh so you can use tctl remotely @@ -54,8 +55,8 @@ $ tsh login --proxy=proxy.example.com --user=myuser $ tctl get users/ ``` - - + + ```code # Log in to your cluster with tsh so you can use tctl remotely @@ -63,7 +64,9 @@ $ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl get users ``` - + + + Here is an example of a temporary `user` resource created when the GitHub user `myuser` signed in to GitHub to authenticate to Teleport. This resource @@ -210,7 +213,8 @@ users. The following authentication connectors are supported: - + + |Type|Description| |---|---| @@ -219,26 +223,29 @@ The following authentication connectors are supported: |`oidc`| The OIDC connector type uses the [OpenID Connect protocol](https://en.wikipedia.org/wiki/OpenID_Connect) to authenticate users
and query their group membership.| |`github`| The GitHub connector uses GitHub SSO to authenticate users and query their group membership.| - - + + |Type|Description| |---|---| |None|If no authentication connector is created, Teleport will use local authentication based user information stored in the Auth Service backend. You can manage user data via the `tctl users` command. | |`github`| The GitHub connector uses GitHub SSO to authenticate users and query their group membership.| - + + + ### Creating an authentication connector - + + Before you can create an authentication connector, you must enable authentication via that connector's protocol. -To set the default authentication type as `saml` or `oidc`, either modify your Auth Service configuration file -or create a `cluster_auth_preference` resource. +To set the default authentication type as `saml` or `oidc`, either modify your +Auth Service configuration file (if using a self-hosted edition of Teleport) or +create a `cluster_auth_preference` resource. @@ -266,53 +273,16 @@ or create a `cluster_auth_preference` resource. Create the resource: - - ```code # Log in to your cluster with tsh so you can run tctl commands. - # You can also run tctl directly on the Auth Service host. - $ tsh login --proxy=teleport.example.com --user=myuser + $ tsh login --proxy= --user=myuser $ tctl create -f cap.yaml ``` - - - - ```code - # Log in to your cluster with tsh so you can run tctl commands. - $ tsh login --proxy=mytenant.teleport.sh --user=myuser - $ tctl create -f cap.yaml - ``` - - (!docs/pages/includes/sso/idp-initiated.mdx!) - - - - -Next, define an authentication connector. Create a file called `connector.yaml` -with the following content: - -```yaml -kind: cluster_auth_preference -metadata: - name: cluster-auth-preference -spec: - type: github - webauthn: - # Replace with the address of your Teleport cluster - rp_id: 'example.teleport.sh' -version: v2 - -``` - - - - - Next, define an authentication connector. Create a file called `connector.yaml` based on one of the following examples. @@ -415,7 +385,27 @@ the entity descriptor from your IDP. We recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL. - + + + +Next, define an authentication connector. Create a file called `connector.yaml` +with the following content: + +```yaml +kind: cluster_auth_preference +metadata: + name: cluster-auth-preference +spec: + type: github + webauthn: + # Replace with the address of your Teleport cluster + rp_id: 'example.teleport.sh' +version: v2 + +``` + + + Create the connector: @@ -423,6 +413,8 @@ Create the connector: $ tctl create -f connector.yaml ``` + + ### User logins Often it is required to restrict SSO users to their unique UNIX logins when they @@ -546,10 +538,13 @@ of SSO buttons in the Teleport Web UI. Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to: - + + - Ensure that HTTP/TLS certificates are configured properly for both Teleport proxy and the SSO provider. - + + + - Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport. - Be able to see how Teleport maps the received claims to role mappings as defined @@ -602,3 +597,4 @@ spec: 'env': 'dev' version: v5 ``` + diff --git a/docs/pages/access-controls/sso/github-sso.mdx b/docs/pages/access-controls/sso/github-sso.mdx index 400a1aad3de64..e037a2e34fcbd 100644 --- a/docs/pages/access-controls/sso/github-sso.mdx +++ b/docs/pages/access-controls/sso/github-sso.mdx @@ -10,11 +10,15 @@ Teleport. ## Prerequisites -- A GitHub organization with at least one team. This - organization must not have external SSO set up, or Teleport will refuse to - create the GitHub authentication connector.This organization can be hosted from either - GitHub Cloud or GitHub Enterprise Server. +- A GitHub organization with at least one team. + + In Teleport Community Edition and Teleport Team, this organization must not + have external SSO set up, or Teleport will refuse to create the GitHub + authentication connector. + + In Teleport Enterprise and Enterprise Cloud, organization can be hosted from + either GitHub Cloud or GitHub Enterprise Server. + - Teleport role with access to maintaining `github` resources for using `tctl` from the Desktop. This is available in the default `editor` role. @@ -31,9 +35,8 @@ App's "Authentication callback URL" is the following: https://PROXY_ADDRESS/v1/webapi/github/ ``` -`PROXY_ADDRESS` must be the public -address of the Teleport Proxy Serviceyour Teleport Cloud tenant address. +Replace `PROXY_ADDRESS` with be the public address of the Teleport Proxy Service +or your Teleport Cloud workspace URL (e.g., `example.teleport.sh`). The app must have the `read:org` scope in order to be able to read org and team membership details. @@ -224,7 +227,8 @@ Here is an example role configuration snippet using the trait variable: You can now log in with Teleport using GitHub SSO. Run the following to log out of Teleport and log in again using GitHub SSO. - + + ```code $ tsh logout @@ -234,8 +238,8 @@ If browser window does not open automatically, open it by clicking on the link: http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158 ``` - - + + ```code $ tsh logout @@ -245,7 +249,9 @@ If browser window does not open automatically, open it by clicking on the link: http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158 ``` - + + + You can also log to the web UI using GitHub by clicking **Other sign-in options** at the login screen. @@ -263,29 +269,10 @@ After logging in successfully, you will see the following: You will receive the details of your user session within the CLI: - - -```code -> Profile URL: https://tele.example.com:443 - Logged in as: jeff - Cluster: tele.example.com - Roles: access - Logins: jeff, ubuntu, debian, -teleport-internal-join - Kubernetes: enabled - Kubernetes users: dev - Kubernetes groups: developer - Valid until: 2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s] - Extensions: permit-port-forwarding, permit-pty, private-key-policy -``` - - - - - ```code -> Profile URL: https://mytenant.teleport.sh:443 +> Profile URL: https://example.teleport.sh:443 Logged in as: jeff - Cluster: mytenant.teleport.sh + Cluster: example.teleport.sh Roles: access Logins: jeff, ubuntu, debian, -teleport-internal-join Kubernetes: enabled @@ -295,8 +282,6 @@ You will receive the details of your user session within the CLI: Extensions: permit-port-forwarding, permit-pty, private-key-policy ``` - - ## Step 4/4. Configure authentication preference In the previous step we signed in to Teleport using GitHub credentials by @@ -324,7 +309,8 @@ spec: version: v2 ``` -For `rp_id`, use the public address of your Teleport Proxy ServiceTeleport Cloud tenant. +For `rp_id`, use the public address of your Teleport Proxy Service or Teleport +Cloud workspace. When you save and close the temporary file, `tctl` will update the resource: @@ -351,3 +337,4 @@ After logging out of `tsh`, you can log back in without specifying ## Troubleshooting (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!) + diff --git a/docs/pages/api/automatically-register-agents.mdx b/docs/pages/api/automatically-register-agents.mdx index 0132cd5d34fca..cce89fe9e2104 100644 --- a/docs/pages/api/automatically-register-agents.mdx +++ b/docs/pages/api/automatically-register-agents.mdx @@ -127,8 +127,9 @@ As with all Teleport users, the Teleport Auth Service authenticates the will request the credentials manually by *impersonating* the `register-apps` role and user. -If you are using `tctl` from the Auth -Service host, you will already have impersonation privileges. +If you are running a self-hosted Teleport Enterprise deployment and are using +`tctl` from the Auth Service host, you will already have impersonation +privileges. To grant your user impersonation privileges for `register-apps`, create a file called `register-apps-impersonator.yaml` defining a role: diff --git a/docs/pages/api/rbac.mdx b/docs/pages/api/rbac.mdx index 8d09ff8a7c52b..caf72aa1a5f75 100644 --- a/docs/pages/api/rbac.mdx +++ b/docs/pages/api/rbac.mdx @@ -277,8 +277,9 @@ As with all Teleport users, the Teleport Auth Service authenticates the case, we will request the credentials manually by *impersonating* the `sync-kubernetes-rbac` role and user. -If you are using `tctl` from the Auth -Service host, you will already have impersonation privileges. +If you are running a self-hosted Teleport Enterprise deployment and are using +`tctl` from the Auth Service host, you will already have impersonation +privileges. To grant your user impersonation privileges for `sync-kubernetes-rbac`, define a role called `sync-kubernetes-rbac-impersonator` by pasting the following YAML document into diff --git a/docs/pages/application-access/guides/api-access.mdx b/docs/pages/application-access/guides/api-access.mdx index f8e9044b78300..9115f377151c9 100644 --- a/docs/pages/application-access/guides/api-access.mdx +++ b/docs/pages/application-access/guides/api-access.mdx @@ -73,10 +73,13 @@ target application's API through Teleport App Access. title="CA and Key Pair Files" > Note the paths to your user's certificate/key pair in the command - `curl` will use a client certificate to authenticate with Teleport. + + The Teleport Proxy Service is usually configured with a wildcard certificate + issued by a public certificate authority such as Let's Encrypt. If you are + running a self-hosted Teleport cluster, and your Teleport Proxy Service has + been configured to use a self-signed certificate instead, you will need to + include it in your `curl` command using `--cacert `. - - The Teleport Proxy Service is usually configured with a wildcard certificate issued by a public certificate authority such as Let's Encrypt. If your Teleport Proxy Service has been configured to use a self-signed certificate instead, you will need to include it in your `curl` command using `--cacert `. - As Grafana's API requires authentication, let's update the `curl` command to diff --git a/docs/pages/application-access/guides/dynamic-registration.mdx b/docs/pages/application-access/guides/dynamic-registration.mdx index 5d84fc1f769ef..3dd86e04eab89 100644 --- a/docs/pages/application-access/guides/dynamic-registration.mdx +++ b/docs/pages/application-access/guides/dynamic-registration.mdx @@ -72,7 +72,8 @@ version: v5 To create an application resource, run: - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -82,8 +83,8 @@ $ tsh login --proxy=teleport.example.com --user=myuser $ tctl create app.yaml ``` - - + + ```code # Log in to your Teleport cluster so you can use tctl remotely. @@ -91,7 +92,9 @@ $ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl create app.yaml ``` - + + + After the resource has been created, it will appear among the list of available apps (in `tsh apps ls` or UI) as long as at least one Application Service diff --git a/docs/pages/application-access/guides/dynamodb.mdx b/docs/pages/application-access/guides/dynamodb.mdx index 5fbe30bee5a88..f7f0646f45ea6 100644 --- a/docs/pages/application-access/guides/dynamodb.mdx +++ b/docs/pages/application-access/guides/dynamodb.mdx @@ -20,12 +20,15 @@ This guide will help you to: - Set up the Teleport Application Service to access the AWS Console and API. - Connect to your DynamoDB databases through the Teleport Application Service. - + + ![DynamoDB Self-Hosted](../../../img/application-access/guides/dynamodb_selfhosted.png) - - + + ![DynamoDB Cloud](../../../img/application-access/guides/dynamodb_cloud.png) - + + + ## Prerequisites @@ -346,3 +349,4 @@ $ tsh apps logout aws-dynamodb ## Next steps - More information on [AWS Management and API with Teleport Application Access](../../application-access/cloud-apis/aws-console.mdx). - Learn more about [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). + diff --git a/docs/pages/application-access/guides/tcp.mdx b/docs/pages/application-access/guides/tcp.mdx index 494f0472cd246..6c73be13338e2 100644 --- a/docs/pages/application-access/guides/tcp.mdx +++ b/docs/pages/application-access/guides/tcp.mdx @@ -41,7 +41,8 @@ $ docker run --name postgres -p 5432:5432 -e POSTGRES_PASSWORD= -d postgre Teleport Application Service requires a valid auth token to join the cluster. - + + To generate one, run the following command on your Auth Service node: ```code @@ -54,16 +55,18 @@ connect to cluster applications: ```code $ tctl users add --roles=access alice ``` - + - + To generate one, log into your Cloud tenant and run the following command: ```code $ tsh login --proxy=mytenant.teleport.sh $ tctl tokens add --type=app ``` - + + + Save the generated token in `/tmp/token` on the node where Application Service will run. @@ -146,3 +149,4 @@ $ psql postgres://postgres@localhost:55868/postgres ## Next steps - Learn about [access controls](../controls.mdx) for applications. + diff --git a/docs/pages/application-access/reference.mdx b/docs/pages/application-access/reference.mdx index 0aa333db59923..92db3706e319f 100644 --- a/docs/pages/application-access/reference.mdx +++ b/docs/pages/application-access/reference.mdx @@ -107,7 +107,8 @@ spec: You can create a new `app` resource by running the following commands, which assume that you have created a YAML file called `app.yaml` with your configuration: - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -118,8 +119,8 @@ $ tsh login --proxy=teleport.example.com --user=myuser $ tctl create -f app.yaml ``` - - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -128,7 +129,9 @@ $ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl create -f app.yaml ``` - + + + ## CLI @@ -210,3 +213,4 @@ To run this command, one of the user's roles must include the Application Service. To learn how to set up secure access to Azure via Teleport, read [Protect the Azure CLI with Teleport Application Access](cloud-apis/azure.mdx). + diff --git a/docs/pages/architecture/authorization.mdx b/docs/pages/architecture/authorization.mdx index 41db7ead8f275..6f1ca0c374681 100644 --- a/docs/pages/architecture/authorization.mdx +++ b/docs/pages/architecture/authorization.mdx @@ -351,15 +351,12 @@ options, Teleport will choose `strict` option. ### Just in Time Access Requests - - - The full version of Just In Time Access Requests is available only in Teleport Cloud or Enterprise. - - + The full version of Just In Time Access Requests is available only in Teleport + Enterprise (including Enterprise Cloud). + + Roles allow requesting elevated privileges - other roles or individual resources. @@ -396,3 +393,4 @@ spec: - [Teleport Auth](authentication.mdx) - [Teleport Nodes](nodes.mdx) - [Teleport Proxy](proxy.mdx) + diff --git a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx index c2beadc4af1b9..6ab9eec455b7a 100644 --- a/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx +++ b/docs/pages/choose-an-edition/teleport-enterprise/hsm.mdx @@ -7,12 +7,6 @@ h1: Teleport HSM Support This guide will show you how to set up the Teleport Auth Service to use a hardware security module (HSM) to store and handle private keys. - - -This guide is intended for Teleport Enterprise users. - - - ## Prerequisites - Teleport v(=teleport.version=) Enterprise (self-hosted). @@ -361,3 +355,4 @@ You are all set! Check the teleport logs for `Creating new HSM key pair` to confirm that the feature is working. You can also check that keys were created in your HSM using your HSM's admin tool. + diff --git a/docs/pages/connect-your-client/gui-clients.mdx b/docs/pages/connect-your-client/gui-clients.mdx index 3810337540069..a4d8bfc8ee01d 100644 --- a/docs/pages/connect-your-client/gui-clients.mdx +++ b/docs/pages/connect-your-client/gui-clients.mdx @@ -19,7 +19,8 @@ work with Teleport. ### Get connection information - + + @@ -96,8 +97,8 @@ TLS authentication. - - + + Use the following command to start a local TLS proxy your GUI database client will be connecting to: @@ -116,7 +117,9 @@ Use the displayed local proxy host/port and credentials paths when configuring your GUI client below. When entering the hostname, use `localhost` rather than `127.0.0.1`. - + + + ## MongoDB Compass @@ -418,3 +421,4 @@ Use the SQL Server Authentication option and keep the Password field empty: ![DBeaver connection options](../../img/database-access/guides/sqlserver/dbeaver-connection@2x.png) Click OK to connect. + diff --git a/docs/pages/connect-your-client/introduction.mdx b/docs/pages/connect-your-client/introduction.mdx index e1d693f0acfb6..2b34a716db196 100644 --- a/docs/pages/connect-your-client/introduction.mdx +++ b/docs/pages/connect-your-client/introduction.mdx @@ -70,9 +70,7 @@ server and database access within a single window. ![A new instance of Teleport Connect](../../img/teleport-connect-init.png) 1. Provide the address of your Teleport Cluster (e.g. -`https://teleport.example.com` -`https://mytennant.teleport.sh` -) and click **NEXT**. + `https://example.teleport.sh`) and click **NEXT**. 1. Teleport Connect will ask you for your username, password, and MFA. @@ -85,13 +83,15 @@ server and database access within a single window. ### Web UI -Teleport provides a web interface for users to interact with Teleport, e.g., by accessing resources or creating Access Requests. This is usually -found at the same URL used to connect to Teleport with (e.g. -`https://teleport.example.com` -`https://mytenant.teleport.sh`), -but you should confirm the Web UI URL with the team that manages your Teleport deployment. The Web UI provides similar -access to resources as Teleport Connect, and additional access to to Request and -Activity logs for users with the right permissions. +Teleport provides a web interface for users to interact with Teleport, e.g., by +accessing resources or creating Access Requests. This is usually found at the +same URL used to connect to Teleport with (e.g. `https://example.teleport.sh`), +but you should confirm the Web UI URL with the team that manages your Teleport +deployment. + +The Web UI provides similar access to resources as Teleport Connect, and +additional access to to Request and Activity logs for users with the right +permissions. ## Protocols @@ -290,9 +290,7 @@ list those that are accessible to your user under `https://teleport.example.com` -`https://mytennant.teleport.sh` -). +`https://example.teleport.sh`). 1. From the menu on the right, select **Desktops**. 1. Next to the desktop you want to access, click **CONNECT**. Select or type in a username available to your Teleport user. @@ -317,3 +315,4 @@ either directly or through proxy tunnels. {/*lint ignore messaging for page title*/} - [Database Access GUI Clients](./gui-clients.mdx) details how to connect many popular database GUI clients through Teleport. + diff --git a/docs/pages/connect-your-client/tsh.mdx b/docs/pages/connect-your-client/tsh.mdx index 51efe97ab46b5..1922c6dfa4a3d 100644 --- a/docs/pages/connect-your-client/tsh.mdx +++ b/docs/pages/connect-your-client/tsh.mdx @@ -23,7 +23,8 @@ terminal for the CLI reference. For the impatient, here's an example of how a user would typically use [`tsh`](../reference/cli/tsh.mdx): - + + ```code # Log into a Teleport cluster. This command retrieves the user's certificates @@ -47,8 +48,8 @@ $ ssh user@host $ tsh logout ``` - - + + ```code # Login into a Teleport cluster. This command retrieves the user's certificates @@ -72,7 +73,9 @@ $ ssh user@host $ tsh logout ``` - + + + In other words, Teleport was designed to be fully compatible with existing SSH-based workflows and does not require users to learn anything new, other than @@ -95,7 +98,8 @@ login and the OS login. A Teleport identity will have to be passed via the `--user` flag while the OS login will be passed as `login@host` using syntax compatible with the traditional `ssh` command. - + + ```code # Authenticate against the "work" cluster as joe and then @@ -103,8 +107,8 @@ compatible with the traditional `ssh` command. $ tsh ssh --proxy=work.example.com --user=joe root@node ``` - - + + ```code # Authenticate against the "work" cluster as joe and then @@ -112,7 +116,9 @@ $ tsh ssh --proxy=work.example.com --user=joe root@node $ tsh ssh --proxy=mytenant.teleport.sh --user=joe root@node ``` - + + + [CLI Docs - tsh ssh](../reference/cli/tsh.mdx#tsh-ssh) @@ -120,7 +126,8 @@ $ tsh ssh --proxy=mytenant.teleport.sh --user=joe root@node To retrieve a user's certificate, execute: - + + ```code # Full form: @@ -133,8 +140,8 @@ $ tsh login --proxy=work.example.com $ tsh login --proxy=work.example.com:5000 ``` - - + + ```code # Full form: @@ -143,7 +150,9 @@ $ tsh login --proxy=proxy_host: $ tsh login --proxy=mytenant.teleport.sh ``` - + + + [CLI Docs - tsh login](../reference/cli/tsh.mdx#tsh-login) @@ -165,7 +174,8 @@ This allows you to authenticate just once, maybe at the beginning of the day. Su A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via GitHub](../access-controls/sso/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use: - + + ```code # Log in using the local Teleport 'admin' user: @@ -175,8 +185,8 @@ $ tsh --proxy=proxy.example.com --auth=local --user=admin login $ tsh --proxy=proxy.example.com --auth=github login ``` - - + + ```code # Log in using the local Teleport 'admin' user: @@ -186,29 +196,34 @@ $ tsh --proxy=mytenant.teleport.sh --auth=local --user=admin login $ tsh --proxy=mytenant.teleport.sh --auth=github login ``` - + + + When using an external identity provider to log in, `tsh` will need to open a web browser to complete the authentication flow. By default, `tsh` will use your system's default browser. If you wish to suppress this behavior, you can use the `--browser=none` flag: - + + ```code # Don't open the system default browser when logging in $ tsh login --proxy=work.example.com --browser=none ``` - - + + ```code # Don't open the system default browser when logging in $ tsh login --proxy=mytenant.teleport.sh --browser=none ``` - + + + In this situation, a link will be printed on the screen. You can copy and paste this link into a browser of your choice to continue the login flow. @@ -220,7 +235,8 @@ a browser of your choice to continue the login flow. To inspect the SSH certificates in `~/.tsh`, a user may execute the following command: - + + ```code $ tsh status @@ -235,8 +251,8 @@ $ tsh status # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - + + ```code $ tsh status @@ -251,7 +267,9 @@ $ tsh status # Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - + + + [CLI Docs - tsh status](../reference/cli/tsh.mdx#tsh-status) @@ -277,7 +295,8 @@ variable to `false` in your shell profile to make this permanent. [`tsh login`](../reference/cli/tsh.mdx#tsh-login) can also save the user certificate into a file: - + + ```code # Authenticate the user against proxy.example.com and save the user @@ -288,8 +307,8 @@ $ tsh login --proxy=proxy.example.com --out=joe $ tsh ssh --proxy=proxy.example.com -i joe joe@db ``` - - + + ```code # Authenticate the user against mytenant.teleport.sh and save the user @@ -300,14 +319,17 @@ $ tsh login --proxy=mytenant.teleport.sh --out=joe $ tsh ssh --proxy=mytenant.teleport.sh -i joe joe@db ``` - + + + By default, the `--out` flag will create an identity file suitable for `tsh -i`. If compatibility with OpenSSH is needed, `--format=openssh` must be specified. In this case, the identity will be saved into two files, `joe` and `joe-cert.pub`: - + + ```code $ tsh login --proxy=proxy.example.com --out=joe --format=openssh @@ -318,8 +340,8 @@ $ ls -lh # -rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --out=joe --format=openssh @@ -330,7 +352,9 @@ $ ls -lh # -rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub ``` - + + + ### SSH certificates for automation @@ -350,7 +374,8 @@ In this example, we're creating a certificate with a TTL of one hour for the `jenkins` user and storing it in a `jenkins.pem` file, which can be later used with `-i` (identity) flag for `tsh`. - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -360,8 +385,8 @@ $ tsh login --proxy=teleport.example.com --user=myuser $ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem ``` - - + + ```code # Log in to your Teleport Cloud cluster so you can use tctl locally. @@ -369,7 +394,9 @@ $ tsh login --proxy=myinstance.teleport.sh --user=email@example.com $ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem ``` - + + + [CLI Docs - tctl auth sign](../reference/cli/tctl.mdx#tctl-auth-sign) @@ -427,7 +454,8 @@ the most popular `ssh` flags like `-p`, `-l` or `-L`. For example, if you have the following alias defined in your `~/.bashrc`: `alias ssh="tsh ssh"` then you can continue using familiar SSH syntax: - + + ```code # Have this alias configured, perhaps via ~/.bashrc @@ -443,8 +471,8 @@ $ ssh -o ForwardAgent=yes user@node $ ssh -o AddKeysToAgent=yes user@node ``` - - + + ```code # Have this alias configured, perhaps via ~/.bashrc @@ -460,9 +488,9 @@ $ ssh -o ForwardAgent=yes user@node $ ssh -o AddKeysToAgent=yes user@node ``` - + - + ### Proxy ports @@ -477,7 +505,9 @@ $ tsh --proxy=proxy.example.com:5000 This `tsh` command will use port `5000` of the Proxy Service. - + + + ### Port forwarding @@ -519,20 +549,23 @@ This command: While implementing `ProxyJump` for Teleport, we have extended the feature to `tsh`. - + + ```code $ tsh ssh -J proxy.example.com telenode ``` - - + + ```code $ tsh ssh -J mytenant.teleport.sh telenode ``` - + + + Known limitations: @@ -649,7 +682,8 @@ tunnels from behind-firewall environments into a Teleport Proxy Service you have These features are called **Trusted Clusters**. Refer to [the Trusted Clusters guide](../management/admin/trustedclusters.mdx) to learn how a Trusted Cluster can be configured. - + + Assuming the Teleport Proxy Server called `work` is configured with a few Trusted Clusters, a user may use the `tsh clusters` command to see a list of all Trusted Clusters on the server: @@ -663,8 +697,8 @@ $ tsh --proxy=work clusters # production offline ``` - - + + Assuming the Teleport Cloud tenant called `mytenant.teleport.sh` is configured with a few trusted clusters, a user may use the `tsh clusters` command to see a list of all Trusted Clusters on the server: @@ -678,13 +712,16 @@ $ tsh --proxy=mytenant.teleport.sh clusters # production offline ``` - + + + [CLI Docs - tsh clusters](../reference/cli/tsh.mdx#tsh-clusters) Now you can use the `--cluster` flag with any `tsh` command. For example, to list SSH nodes that are members of the `production` cluster, simply run: - + + ```code $ tsh --proxy=work ls --cluster=production @@ -695,8 +732,8 @@ $ tsh --proxy=work ls --cluster=production # db-2 xxxxxxxxx 10.0.20.41:3022 kernel:4.2 ``` - - + + ```code $ tsh --proxy=mytenant.teleport.sh ls --cluster=production @@ -707,11 +744,14 @@ $ tsh --proxy=mytenant.teleport.sh ls --cluster=production # db-2 xxxxxxxxx 10.0.20.41:3022 kernel:4.2 ``` - + + + Similarly, if you want to SSH into `db-1` inside the `production` cluster: - + + ```code $ tsh --proxy=work ssh --cluster=production db-1 @@ -722,8 +762,8 @@ firewall without open ports. This works because the `production` cluster establishes a reverse SSH tunnel back into the Proxy Service called `work`, and this tunnel is used to establish inbound SSH connections. - - + + ```code $ tsh --proxy=mytenant.teleport.sh ssh --cluster=production db-1 @@ -734,7 +774,9 @@ firewall without open ports. This works because the `production` cluster establishes a reverse SSH tunnel back into your Teleport Cloud tenant's Proxy Service, and this tunnel is used to establish inbound SSH connections. - + + + ## X11 forwarding diff --git a/docs/pages/contributing/documentation/reference.mdx b/docs/pages/contributing/documentation/reference.mdx index 321e891da435f..aeeccd16bc540 100644 --- a/docs/pages/contributing/documentation/reference.mdx +++ b/docs/pages/contributing/documentation/reference.mdx @@ -476,45 +476,6 @@ Here is an image: When including the partial, the docs engine will rewrite the link path to load the image in `docs/img/screenshot.png`. -## ScopedBlock - -Use the `ScopedBlock` component if you want to render some Markdown only for -users of open source Teleport, Teleport Cloud, or Teleport Enterprise. - -`ScopedBlock` has a single property, `scope`, that works the same as it does for -other components we use in the documentation. See our -[explanation](./reference.mdx#scopes) of how to use the `scope` property. - -Use this instead of the `Tabs` component when: - -- You want to conceal details that aren't relevant to the reader's scope. -- The components you use don't look presentable within a `TabItem`, e.g., you're - including a separate `Tabs` component for each scope. - - - -Readers may not notice that it is possible to adjust the scope of a docs page, -so only use this component if there is no risk of a reader losing important -information by not seeing a `ScopedBlock`. Otherwise, consider a `Details` block -with `scope` set and `scopeOnly={false}`. - - - -Any Markdown and MDX components can be included within a `ScopedBlock`. - -```jsx - - - Here are some options for installing the Teleport Auth and Proxy Services on - your own infrastructure. - - - {/* TabItems that vary between scopes */} - - - -``` - ## Scopes There are four editions of Teleport: `oss`, `enterprise`, `cloud`, and `team`. @@ -728,3 +689,4 @@ To embed a video in a docs page, use the `video` tag: Your browser does not support the video tag. ``` + diff --git a/docs/pages/database-access/architecture.mdx b/docs/pages/database-access/architecture.mdx index a701cbffdf12d..09d11372ec69d 100644 --- a/docs/pages/database-access/architecture.mdx +++ b/docs/pages/database-access/architecture.mdx @@ -15,21 +15,24 @@ databases: In it, we have the following Teleport components: - + + - [Teleport Proxy](../architecture/proxy.mdx). A stateless service that performs a function of an authentication gateway, serves the Web UI, and accepts database (and other) client connections. - - + + - [Teleport Proxy](../architecture/proxy.mdx). A stateless service that performs a function of an authentication gateway, serves the Web UI, and accepts database (and other) client connections. This service is accessible at your Teleport Cloud tenant URL, e.g., `mytenant.teleport.sh`. - + + + - [Teleport Auth Service](../architecture/authentication.mdx). Serves as cluster's certificate authority, handles user authentication/authorization @@ -145,3 +148,4 @@ for a more in-depth description of the feature scope and design. See [Core Concepts](../core-concepts.mdx) for general Teleport architecture principles. + diff --git a/docs/pages/database-access/getting-started.mdx b/docs/pages/database-access/getting-started.mdx index 71d84e05823c2..f4445d62669e2 100644 --- a/docs/pages/database-access/getting-started.mdx +++ b/docs/pages/database-access/getting-started.mdx @@ -12,12 +12,15 @@ In this guide, you will: 1. Join the Aurora database to your Teleport cluster. 1. Connect to the Aurora database via the Teleport Database Service. - + + ![Teleport Database Access RDS Self-Hosted](../../img/database-access/guides/rds_selfhosted.png) - - + + ![Teleport Database Access RDS Cloud](../../img/database-access/guides/rds_cloud.png) - + + + ## Prerequisites @@ -98,7 +101,8 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) - + + On the node where you will run the Teleport Database Service, start Teleport and point it to your Aurora database instance. Make sure to update the database @@ -115,8 +119,8 @@ $ teleport db start \ --aws-region=us-west-1 ``` - - + + On the node where you will run the Teleport Database Service, start Teleport and point it to your Aurora database instance. Make sure to update the database @@ -133,7 +137,9 @@ $ teleport db start \ --aws-region=us-west-1 ``` - + + + + + ```code $ tsh login --proxy=teleport.example.com --user=alice ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice ``` - + + + Now we can inspect available databases: @@ -218,3 +227,4 @@ Access use-case, for example: - Learn how to configure [GUI clients](../connect-your-client/gui-clients.mdx). - Learn about database access [role-based access control](./rbac.mdx). - See [frequently asked questions](./faq.mdx). + diff --git a/docs/pages/database-access/guides/aws-cassandra-keyspaces.mdx b/docs/pages/database-access/guides/aws-cassandra-keyspaces.mdx index 0a860ca91cd40..873b0850d40b9 100644 --- a/docs/pages/database-access/guides/aws-cassandra-keyspaces.mdx +++ b/docs/pages/database-access/guides/aws-cassandra-keyspaces.mdx @@ -19,12 +19,15 @@ This guide will help you to: - Set up Teleport to access AWS Keyspaces (Apache Cassandra). - Connect to your database through Teleport. - + + ![Teleport Database Access Redis Self-Hosted](../../../img/database-access/guides/cassandra_keyspaces_selfhosted.png) - - + + ![Teleport Database Access Redis Cloud](../../../img/database-access/guides/cassandra_keyspaces_cloud.png) - + + + ## Prerequisites @@ -45,7 +48,8 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) - + + Create a configuration for the Teleport Database Service, pointing the `--proxy` flag to the address of your Teleport Proxy Service: @@ -61,8 +65,8 @@ $ teleport db configure create \ --labels=env=dev ``` - - + + Create a configuration for the Teleport Database Service, pointing the `--proxy` flag to the address of your Teleport Proxy Service: @@ -78,7 +82,9 @@ $ teleport db configure create \ --labels=env=dev ``` - + + + (!docs/pages/includes/aws-credentials.mdx service="the Teleport Database Service"!) @@ -138,7 +144,8 @@ assume the IAM roles: Once the Database Service has joined the cluster, log in to see the available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -148,8 +155,8 @@ databases: # keyspaces [*] env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -159,7 +166,9 @@ databases: # keyspaces [*] env=dev ``` - + + + To connect to a particular database instance using the `KeyspacesReader` AWS IAM Keyspaces role as a database user: ```code @@ -187,3 +196,4 @@ $ tsh db logout ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/aws-dynamodb.mdx b/docs/pages/database-access/guides/aws-dynamodb.mdx index 0cd6435f0aa8a..1e81216d8c40b 100644 --- a/docs/pages/database-access/guides/aws-dynamodb.mdx +++ b/docs/pages/database-access/guides/aws-dynamodb.mdx @@ -13,12 +13,15 @@ This guide will help you to: - Set up the Teleport Database Service to access DynamoDB. - Connect to your DynamoDB databases through the Teleport Database Service. - + + ![DynamoDB Self-Hosted](../../../img/database-access/guides/aws-dynamodb_selfhosted.png) - - + + ![DynamoDB Cloud](../../../img/database-access/guides/aws-dynamodb_cloud.png) - + + + ## Prerequisites @@ -239,3 +242,4 @@ Type "help", "copyright", "credits" or "license" for more information. - See [Dynamic Database Registration](./dynamic-registration.mdx) to learn how to use resource labels to keep Teleport up to date with accessible databases in your infrastructure. + diff --git a/docs/pages/database-access/guides/azure-postgres-mysql.mdx b/docs/pages/database-access/guides/azure-postgres-mysql.mdx index d5108ffbd8ca6..dc42cefc78c2e 100644 --- a/docs/pages/database-access/guides/azure-postgres-mysql.mdx +++ b/docs/pages/database-access/guides/azure-postgres-mysql.mdx @@ -18,12 +18,15 @@ Teleport `12.0`. This guide will help you to set up secure access and connect through Teleport to Azure PostgreSQL and MySQL servers. - + + ![Teleport Database Access Azure PostgreSQL/MySQL Self-Hosted](../../../img/database-access/guides/azure_selfhosted.png) - - + + ![Teleport Database Access Azure PostgreSQL/MySQL Cloud](../../../img/database-access/guides/azure_cloud.png) - + + + ## Prerequisites @@ -372,7 +375,8 @@ You can create multiple database users identified by the same service principal. Log in to your Teleport cluster. Your Azure database should appear in the list of available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -382,8 +386,8 @@ $ tsh db ls # azure-db env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -393,7 +397,9 @@ $ tsh db ls # azure-db env=dev ``` - + + + To retrieve credentials for a database and connect to it: @@ -432,3 +438,4 @@ $ tsh db logout azure-db ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/azure-redis.mdx b/docs/pages/database-access/guides/azure-redis.mdx index 081183d2a1604..b817db496074d 100644 --- a/docs/pages/database-access/guides/azure-redis.mdx +++ b/docs/pages/database-access/guides/azure-redis.mdx @@ -9,13 +9,16 @@ This guide will help you to: - Set up access to Azure Cache for Redis. - Connect to the database server through Teleport. - + + ![Teleport Database Access Azure Cache for Redis Self-Hosted](../../../img/database-access/guides/azure/redis-self-hosted.png) - + - + ![Teleport Database Access Azure Cache for Redis Cloud](../../../img/database-access/guides/azure/redis-cloud.png) - + + + ## Prerequisites @@ -42,7 +45,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Create the Database Service configuration, specifying a region like this: - + + ```code $ teleport db configure create \ @@ -51,8 +55,8 @@ $ teleport db configure create \ --token=/tmp/token \ --azure-redis-discovery=eastus ``` - - + + ```code $ teleport db configure create \ @@ -61,7 +65,9 @@ $ teleport db configure create \ --token=/tmp/token \ --azure-redis-discovery=eastus ``` - + + + The command will generate a Database Service configuration with Azure Cache for Redis auto-discovery enabled in the `eastus` region and place it at the @@ -153,7 +159,8 @@ and replace the subscription in `assignableScopes` with your own subscription id Log in to your Teleport cluster. Your Azure Cache for Redis databases should appear in the list of available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -164,9 +171,9 @@ my-azure-redis Azure Redis server in East US [*] my-azure-redis-enterprise Azure Redis Enterprise server in East US [*] ... ``` - + - + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -177,7 +184,9 @@ my-azure-redis Azure Redis server in East US [*] my-azure-redis-enterprise Azure Redis Enterprise server in East US [*] ... ``` - + + + By default, Teleport uses the name of the Azure Cache for Redis resource as the @@ -213,3 +222,4 @@ $ tsh db logout my-azure-redis ## Further reading - [Understand Azure Role Definitions - AssignableScopes](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-definitions#assignablescopes) - [Azure RBAC custom roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles) + diff --git a/docs/pages/database-access/guides/azure-sql-server-ad.mdx b/docs/pages/database-access/guides/azure-sql-server-ad.mdx index 6545ed0c5c56a..6f1386ec8e849 100644 --- a/docs/pages/database-access/guides/azure-sql-server-ad.mdx +++ b/docs/pages/database-access/guides/azure-sql-server-ad.mdx @@ -25,12 +25,15 @@ This guide will help you to: - Set up access to Azure SQL Server using Azure Active Directory authentication. - Connect to Azure SQL Server through Teleport. - + + ![Teleport Database Access Azure SQL Server Azure Active Directory Self-Hosted](../../../img/database-access/guides/sqlserver/sql-aad.png) - - + + ![Teleport Database Access Azure SQL Server Azure Active Directory Cloud](../../../img/database-access/guides/sqlserver/cloud-sql-aad.png) - + + + ## Prerequisites @@ -191,7 +194,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Generate a configuration file at `/etc/teleport.yaml` for the Database Service: - + + ```code $ teleport db configure create \ @@ -201,8 +205,8 @@ $ teleport db configure create \ --azure-sqlserver-discovery=eastus ``` - - + + ```code $ teleport db configure create \ -o file \ @@ -210,7 +214,9 @@ $ teleport db configure create \ --proxy=mytenant.teleport.sh:443 \ --azure-sqlserver-discovery=eastus ``` - + + + The command will generate a Database Service configuration with Azure SQL Server auto-discovery enabled in the `eastus` region and place it at the @@ -234,7 +240,8 @@ Server auto-discovery enabled in the `eastus` region and place it at the Log in to your Teleport cluster. Your database should appear in the list of available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -245,8 +252,8 @@ sqlserver Azure SQL Server in westeurope [*] ... sqlserver-managed Azure Managed SQL Server in eastus [*] ... ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -257,7 +264,9 @@ sqlserver Azure SQL Server in westeurope [*] ... sqlserver-managed Azure Managed SQL Server in eastus [*] ... ``` - + + + To retrieve credentials for a database and connect to it: @@ -313,3 +322,4 @@ To check if the VM has access, you can do the following on the VM: ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/cassandra-self-hosted.mdx b/docs/pages/database-access/guides/cassandra-self-hosted.mdx index 18cb6099d4682..a3a5a31b3c3a7 100644 --- a/docs/pages/database-access/guides/cassandra-self-hosted.mdx +++ b/docs/pages/database-access/guides/cassandra-self-hosted.mdx @@ -19,12 +19,15 @@ This guide will help you to: - Set up Teleport to access your self-hosted Cassandra or ScyllaDB. - Connect to your database through Teleport. - + + ![Teleport Database Access Cassandra Self-Hosted](../../../img/database-access/guides/cassandra_selfhosted.png) - - + + ![Teleport Database Access Cassandra Cloud](../../../img/database-access/guides/cassandra_cloud.png) - + + + ## Prerequisites @@ -142,7 +145,8 @@ Follow the instructions for your database to enable TLS communication with your Once the Database Service has joined the cluster, log in to see the available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -152,8 +156,8 @@ databases: # cassandra Cassandra Example [*] env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -163,7 +167,9 @@ databases: # cassandra Cassandra Example [*] env=dev ``` - + + + To connect to a particular database instance : ```code @@ -187,3 +193,4 @@ $ tsh db logout ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx b/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx index 24ed5fba24923..03d069fdbb5c5 100644 --- a/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx +++ b/docs/pages/database-access/guides/cockroachdb-self-hosted.mdx @@ -9,12 +9,15 @@ In this guide, you will: - Configure mutual TLS authentication between Teleport and your CockroachDB cluster. - Connect to your CockroachDB cluster via Teleport. - + + ![Teleport Database Access CockroachDB Self-Hosted](../../../img/database-access/guides/cockroachdb_selfhosted.png) - - + + ![Teleport Database Access CockroachDB Cloud](../../../img/database-access/guides/cockroachdb_cloud.png) - + + + ## Prerequisites @@ -167,3 +170,4 @@ $ tsh db logout roach (!docs/pages/includes/database-access/guides-next-steps.mdx!) - [CockroachDB client authentication](https://www.cockroachlabs.com/docs/stable/authentication.html#client-authentication) + diff --git a/docs/pages/database-access/guides/elastic.mdx b/docs/pages/database-access/guides/elastic.mdx index 1c3597ceab5d0..b88456f9e0d2d 100644 --- a/docs/pages/database-access/guides/elastic.mdx +++ b/docs/pages/database-access/guides/elastic.mdx @@ -21,10 +21,9 @@ This guide will help you to configure secured access to an Elasticsearch databas - A self-hosted Elasticsearch database. Elastic Cloud [does not support client certificates](https://www.elastic.co/guide/en/cloud/current/ec-restrictions.html#ec-restrictions-security), which are required for setting up the Database Service. -- A host where you will run the Teleport Database Service. If you are already running the Teleport - Database Service, you must ensure that it uses Teleport version 10.3 or newer in order to connect - to Elasticsearch. This can also be the same instance - of Teleport running your Auth and/or Proxy service(s). +- A host where you will run the Teleport Database Service. If you are already + running the Teleport Database Service, you must ensure that it uses Teleport + version 10.3 or newer in order to connect to Elasticsearch. See [Installation](../../installation.mdx) for details. diff --git a/docs/pages/database-access/guides/mongodb-atlas.mdx b/docs/pages/database-access/guides/mongodb-atlas.mdx index 1a2be91801084..2a9f882f57199 100644 --- a/docs/pages/database-access/guides/mongodb-atlas.mdx +++ b/docs/pages/database-access/guides/mongodb-atlas.mdx @@ -10,12 +10,15 @@ In this guide, you will: - Configure MongoDB Atlas authentication. - Connect to your Atlas cluster through Teleport. - + + ![Teleport Database Access MongoDB Self-Hosted](../../../img/database-access/guides/mongodbatlas_selfhosted.png) - - + + ![Teleport Database Access MongoDB Cloud](../../../img/database-access/guides/mongodbatlas_cloud.png) - + + + ## Prerequisites @@ -36,7 +39,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Next, start the Database Service. - + + @@ -96,9 +100,9 @@ See the full [YAML reference](../reference/configuration.mdx) for details. - + - + @@ -146,7 +150,9 @@ See the full [YAML reference](../reference/configuration.mdx) for details. - + + + See below for details on how to configure the Teleport Database Service. diff --git a/docs/pages/database-access/guides/mongodb-self-hosted.mdx b/docs/pages/database-access/guides/mongodb-self-hosted.mdx index 5f5b591ac15c7..654f2705238f0 100644 --- a/docs/pages/database-access/guides/mongodb-self-hosted.mdx +++ b/docs/pages/database-access/guides/mongodb-self-hosted.mdx @@ -10,12 +10,15 @@ In this guide, you will: - Configure mutual TLS authentication between Teleport and your MongoDB cluster. - Connect to your MongoDB instance through Teleport. - + + ![Teleport Database Access MongoDB Self-Hosted](../../../img/database-access/guides/mongodb_selfhosted.png) - - + + ![Teleport Database Access MongoDB Cloud](../../../img/database-access/guides/mongodb_cloud.png) - + + + ## Prerequisites @@ -196,7 +199,8 @@ in the MongoDB documentation for more details. Log in to your Teleport cluster and see available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -206,8 +210,8 @@ $ tsh db ls # example-mongo Example MongoDB env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -217,7 +221,9 @@ $ tsh db ls # example-mongo Example MongoDB env=dev ``` - + + + To retrieve credentials for a database and connect to it: @@ -251,3 +257,4 @@ $ tsh db logout ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/mysql-cloudsql.mdx b/docs/pages/database-access/guides/mysql-cloudsql.mdx index 8c3a4d67ad8e5..85e8d0c460ed2 100644 --- a/docs/pages/database-access/guides/mysql-cloudsql.mdx +++ b/docs/pages/database-access/guides/mysql-cloudsql.mdx @@ -9,12 +9,15 @@ This guide will help you to: - Set up Teleport to access your MySQL on Google Cloud SQL. - Connect to your databases through Teleport. - + + ![Teleport Database Access CloudSQL Self-Hosted](../../../img/database-access/guides/cloudsql_selfhosted.png) - - + + ![Teleport Database Access CloudSQL Cloud](../../../img/database-access/guides/cloudsql_cloud.png) - + + + ## Prerequisites @@ -132,7 +135,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Below is an example of a Database Service configuration file that proxies a single Cloud SQL MySQL database. Save this file as `/etc/teleport.yaml`: - + + ```yaml version: v3 @@ -175,8 +179,8 @@ proxy_service: enabled: "no" ``` - - + + ```yaml version: v3 @@ -217,7 +221,9 @@ proxy_service: enabled: "no" ``` - + + + + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -259,8 +266,8 @@ $ tsh db ls # cloudsql GCP Cloud SQL MySQL env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -270,7 +277,9 @@ $ tsh db ls # cloudsql GCP Cloud SQL MySQL env=dev ``` - + + + Note that you will only be able to see databases your role has access to. See our [RBAC](../rbac.mdx) guide for more details. @@ -301,3 +310,4 @@ $ tsh db logout cloudsql # Remove credentials for all database instances. $ tsh db logout ``` + diff --git a/docs/pages/database-access/guides/mysql-self-hosted.mdx b/docs/pages/database-access/guides/mysql-self-hosted.mdx index 9ae2bf796f6e1..5e6f134f03e4f 100644 --- a/docs/pages/database-access/guides/mysql-self-hosted.mdx +++ b/docs/pages/database-access/guides/mysql-self-hosted.mdx @@ -9,12 +9,15 @@ This guide will help you to: - Set up Teleport to access your MySQL or MariaDB database. - Connect to your databases through Teleport. - + + ![Teleport Database Access MySQL Self-Hosted](../../../img/database-access/guides/mysql_selfhosted.png) - - + + ![Teleport Database Access MySQL Cloud](../../../img/database-access/guides/mysql_cloud.png) - + + + ## Prerequisites @@ -164,7 +167,8 @@ Install and configure Teleport where you will run the Teleport Database Service: Once the Database Service has joined the cluster, log in to see the available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -174,8 +178,8 @@ $ tsh db ls # example-mysql Example MySQL env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -185,7 +189,9 @@ $ tsh db ls # example-mysql Example MySQL env=dev ``` - + + + Note that you will only be able to see databases your role has access to. See the [RBAC](../rbac.mdx) guide for more details. @@ -216,3 +222,4 @@ $ tsh db logout example-mysql # Remove credentials for all database instances. $ tsh db logout ``` + diff --git a/docs/pages/database-access/guides/oracle-self-hosted.mdx b/docs/pages/database-access/guides/oracle-self-hosted.mdx index a5d54cabb74c3..a481ac0bf5e08 100644 --- a/docs/pages/database-access/guides/oracle-self-hosted.mdx +++ b/docs/pages/database-access/guides/oracle-self-hosted.mdx @@ -13,12 +13,15 @@ This guide will help you to: - Set up Teleport to access your self-hosted Oracle server 18c or later. - Connect to your database through Teleport. - + + ![Teleport Database Access Self-hosted Oracle](../../../img/database-access/guides/oracle_selfhosted.png) - - + + ![Teleport Database Access Oracle Cloud](../../../img/database-access/guides/oracle_selfhosted_cloud.png) - + + + ## Prerequisites @@ -264,3 +267,4 @@ $ tsh db logout (!docs/pages/includes/database-access/guides-next-steps.mdx!) - Learn more about `sqlnet.ora` and `listener.ora` configuration from the [Parameters for the sqlnet.ora File](https://docs.oracle.com/en/database/oracle/oracle-database/18/netrf/parameters-for-the-sqlnet-ora-file.html#GUID-28040885-6832-4FFC-9258-0EF19FE9A3AC) and [Oracle Net Listener Parameters in the listener.ora File](https://docs.oracle.com/en/database/oracle/oracle-database/18/netrf/Oracle-Net-Listener-parameters-in-listener-ora-file.html#GUID-F9FA0DF5-2FAF-45CA-B6A1-F0166C7BFE54) Oracle documentation. + diff --git a/docs/pages/database-access/guides/postgres-cloudsql.mdx b/docs/pages/database-access/guides/postgres-cloudsql.mdx index c421e7d7be98a..60fe0084a3246 100644 --- a/docs/pages/database-access/guides/postgres-cloudsql.mdx +++ b/docs/pages/database-access/guides/postgres-cloudsql.mdx @@ -10,12 +10,15 @@ This guide will help you to: - Set up Teleport to access your PostgreSQL on Google Cloud SQL. - Connect to your databases through Teleport. - + + ![Teleport Database Access CloudSQL Self-Hosted](../../../img/database-access/guides/cloudsql_selfhosted.png) - - + + ![Teleport Database Access CloudSQL Cloud](../../../img/database-access/guides/cloudsql_cloud.png) - + + + ## Prerequisites @@ -195,7 +198,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Below is an example of a Database Service configuration file that proxies a single Cloud SQL PostgreSQL database. Save this file as `/etc/teleport.yaml`: - + + ```yaml version: v3 @@ -239,8 +243,8 @@ proxy_service: enabled: "no" ``` - - + + ```yaml version: v3 @@ -282,7 +286,9 @@ proxy_service: enabled: "no" ``` - + + + + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -331,8 +338,8 @@ $ tsh db ls # cloudsql GCP Cloud SQL PostgreSQL env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -342,7 +349,9 @@ $ tsh db ls # cloudsql GCP Cloud SQL PostgreSQL env=dev ``` - + + + Note that you will only be able to see databases your role has access to. See our [RBAC](../rbac.mdx) guide for more details. @@ -381,3 +390,4 @@ $ tsh db logout cloudsql # Remove credentials for all database instances. $ tsh db logout ``` + diff --git a/docs/pages/database-access/guides/postgres-redshift.mdx b/docs/pages/database-access/guides/postgres-redshift.mdx index b9e5ad7f0c4eb..1c5b546ffe292 100644 --- a/docs/pages/database-access/guides/postgres-redshift.mdx +++ b/docs/pages/database-access/guides/postgres-redshift.mdx @@ -10,12 +10,15 @@ This guide will help you to: - Set up Teleport to access your AWS Redshift instances. - Connect to your databases through Teleport. - + + ![Teleport Database Access Redshift Self-Hosted](../../../img/database-access/guides/redshift_selfhosted.png) - - + + ![Teleport Database Access Redshift Cloud](../../../img/database-access/guides/redshift_cloud.png) - + + + ## Prerequisites @@ -44,7 +47,8 @@ Install Teleport on the host where you will run the Teleport Database Service: On the node that is running the Database Service, create a configuration file: - + + ```code $ teleport db configure create \ @@ -54,8 +58,8 @@ $ teleport db configure create \ --redshift-discovery=us-west-1 ``` - - + + ```code $ teleport db configure create \ @@ -65,7 +69,9 @@ $ teleport db configure create \ --redshift-discovery=us-west-1 ``` - + + + The command will generate a Database Service configuration with Redshift database auto-discovery enabled on the `us-west-1` region and place it at the @@ -96,7 +102,8 @@ may not propagate immediately and can take a few minutes to come into effect. ## Step 5/5. Connect - + + Once the Database Service has started and joined the cluster, log in to see the registered databases. Replace `--proxy` with the address of your Teleport Proxy @@ -110,8 +117,8 @@ $ tsh db ls # my-redshift Redshift cluster in us-east-1 ... ``` - - + + Once the Database Service has started and joined the cluster, log in to see the registered databases. Replace `--proxy` with the address of your Teleport Cloud @@ -125,7 +132,9 @@ $ tsh db ls # my-redshift Redshift cluster in us-east-1 ... ``` - + + + You can override the database name by applying the `TeleportDatabaseName` AWS tag to the resource. The value of the tag will be used as the database name. @@ -168,3 +177,4 @@ $ tsh db logout my-redshift - Learn how to [restrict access](../rbac.mdx) to certain users and databases. - View the [High Availability (HA)](../guides/ha.mdx) guide. - Take a look at the YAML configuration [reference](../reference/configuration.mdx). + diff --git a/docs/pages/database-access/guides/postgres-self-hosted.mdx b/docs/pages/database-access/guides/postgres-self-hosted.mdx index 0b82f4cd231fe..9a8b5fe6789a8 100644 --- a/docs/pages/database-access/guides/postgres-self-hosted.mdx +++ b/docs/pages/database-access/guides/postgres-self-hosted.mdx @@ -9,12 +9,15 @@ This guide will help you to: - Set up Teleport to access your self-hosted PostgreSQL. - Connect to your databases through Teleport. - + + ![Teleport Database Access PostgreSQL Self-Hosted](../../../img/database-access/guides/postgresqlselfhosted_selfhosted.png) - - + + ![Teleport Database Access PostgreSQL Cloud](../../../img/database-access/guides/postgresqlselfhosted_cloud.png) - + + + ## Prerequisites @@ -113,7 +116,8 @@ Install and configure Teleport where you will run the Teleport Database Service: Once the Database Service has joined the cluster, log in to see the available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -123,8 +127,8 @@ $ tsh db ls # example-postgres Example PostgreSQL env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -134,7 +138,9 @@ $ tsh db ls # example-postgres Example PostgreSQL env=dev ``` - + + + Note that you will only be able to see databases your role has access to. See [RBAC](../rbac.mdx) section for more details. diff --git a/docs/pages/database-access/guides/rds-proxy.mdx b/docs/pages/database-access/guides/rds-proxy.mdx index c027e0196191d..27eb0d7ad8775 100644 --- a/docs/pages/database-access/guides/rds-proxy.mdx +++ b/docs/pages/database-access/guides/rds-proxy.mdx @@ -5,12 +5,15 @@ description: How to configure Teleport database access with AWS RDS Proxy. This guide will help you to set up Teleport to access your AWS RDS proxies. - + + ![Teleport Database Access RDS Proxy Self-Hosted](../../../img/database-access/guides/rds-proxy_selfhosted.png) - - + + ![Teleport Database Access RDS Proxy Cloud](../../../img/database-access/guides/rds-proxy_cloud.png) - + + + Teleport currently supports RDS Proxy instances with engine family @@ -204,3 +207,4 @@ $ tsh db logout rds-proxy and [Setting up AWS Identity and Access Management (IAM) policies](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy-setup.html) for RDS Proxy + diff --git a/docs/pages/database-access/guides/rds.mdx b/docs/pages/database-access/guides/rds.mdx index 4ac787fe004e0..b092da7ec448d 100644 --- a/docs/pages/database-access/guides/rds.mdx +++ b/docs/pages/database-access/guides/rds.mdx @@ -10,12 +10,15 @@ This guide will help you to: - Set up Teleport to access your RDS instances and Aurora clusters. - Connect to your databases through Teleport. - + + ![Teleport Database Access RDS Self-Hosted](../../../img/database-access/guides/rds_selfhosted.png) - - + + ![Teleport Database Access RDS Cloud](../../../img/database-access/guides/rds_cloud.png) - + + + The following products are not compatible with database access as they don't support IAM authentication: @@ -53,29 +56,14 @@ Install Teleport on the host where you will run the Teleport Database Service: Create the Database Service configuration: - - ```code $ teleport db configure create \ -o file \ - --proxy=teleport.example.com:3080 \ + --proxy=example.teleport.sh:443 \ --token=/tmp/token \ --rds-discovery=us-west-1 ``` - - - -```code -$ teleport db configure create \ - -o file \ - --proxy=mytenant.teleport.sh:443 \ - --token=/tmp/token \ - --rds-discovery=us-west-1 -``` - - - The command will generate a Database Service configuration with RDS/Aurora database auto-discovery enabled on the `us-west-1` region and place it at the `/etc/teleport.yaml` location. @@ -145,10 +133,8 @@ for more information. Once the Database Service has started and joined the cluster, log in to see the registered databases: - - ```code -$ tsh login --proxy=teleport.example.com --user=alice +$ tsh login --proxy=example.teleport.sh --user=alice $ tsh db ls # Name Description Labels # ------------------------------ --------------------------------------------- -------- @@ -158,22 +144,6 @@ $ tsh db ls # aurora-mysql-reader Aurora cluster in us-west-1 (reader endpoint) ... ``` - - - -```code -$ tsh login --proxy=mytenant.teleport.sh --user=alice -$ tsh db ls -# Name Description Labels -# ------------------------------ --------------------------------------------- -------- -# postgres-rds RDS instance in us-west-1 ... -# aurora-mysql Aurora cluster in us-west-1 ... -# aurora-mysql-custom-myendpoint Aurora cluster in us-west-1 (custom endpoint) ... -# aurora-mysql-reader Aurora cluster in us-west-1 (reader endpoint) ... -``` - - - Primary, reader, and custom endpoints of Aurora clusters have names of ``, `-reader`, and diff --git a/docs/pages/database-access/guides/redis-aws.mdx b/docs/pages/database-access/guides/redis-aws.mdx index 73e56d2ee8e5c..45f40b9c9c943 100644 --- a/docs/pages/database-access/guides/redis-aws.mdx +++ b/docs/pages/database-access/guides/redis-aws.mdx @@ -9,12 +9,15 @@ This guide will help you to: - Set up Teleport to access your ElastiCache and MemoryDB for Redis clusters. - Connect to your clusters through Teleport. - + + ![Teleport Database Access RDS Self-Hosted](../../../img/database-access/guides/redis_elasticache_selfhosted.png) - - + + ![Teleport Database Access RDS Cloud](../../../img/database-access/guides/redis_elasticache_cloud.png) - + + + ## Prerequisites @@ -44,7 +47,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Create the Database Service configuration: - + + @@ -67,8 +71,8 @@ Create the Database Service configuration: - - + + @@ -91,7 +95,9 @@ Create the Database Service configuration: - + + + The command will generate a Database Service configuration with ElastiCache or MemoryDB database auto-discovery enabled on the `us-west-1` region and place it @@ -148,7 +154,8 @@ some time (up to 20 minutes) to discover this user once the tag is added. Once the Database Service has started and joined the cluster, log in to see the registered databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice $ tsh db ls @@ -160,8 +167,8 @@ $ tsh db ls # my-memorydb MemoryDB cluster in us-west-1 ... ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -174,7 +181,9 @@ $ tsh db ls # my-memorydb MemoryDB cluster in us-west-1 ... ``` - + + + You can override the database name by applying the `TeleportDatabaseName` AWS tag to the resource. The value of the tag will be used as the database name. @@ -237,3 +246,4 @@ $ tsh db logout ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/redis-cluster.mdx b/docs/pages/database-access/guides/redis-cluster.mdx index 6f80ab10dd161..c7e67d067e20d 100644 --- a/docs/pages/database-access/guides/redis-cluster.mdx +++ b/docs/pages/database-access/guides/redis-cluster.mdx @@ -11,12 +11,15 @@ This guide will help you to: - Configure mutual TLS authentication between Teleport and Redis Cluster. - Connect to Redis through Teleport. - + + ![Teleport Database Access Redis Cluster Self-Hosted](../../../img/database-access/guides/rediscluster_selfhosted.png) - - + + ![Teleport Database Access Redis Cluster Cloud](../../../img/database-access/guides/rediscluster_cloud.png) - + + + ## Prerequisites @@ -209,3 +212,4 @@ communicating with Redis Cluster: ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/redis.mdx b/docs/pages/database-access/guides/redis.mdx index 30406df5b3ef7..f9c7202130d80 100644 --- a/docs/pages/database-access/guides/redis.mdx +++ b/docs/pages/database-access/guides/redis.mdx @@ -11,12 +11,15 @@ This guide will help you to: - Configure mutual TLS authentication between Teleport and Redis. - Connect to Redis through Teleport. - + + ![Teleport Database Access Redis Self-Hosted](../../../img/database-access/guides/redis_selfhosted.png) - - + + ![Teleport Database Access Redis Cloud](../../../img/database-access/guides/redis_cloud.png) - + + + ## Prerequisites @@ -134,3 +137,4 @@ returns the `ERR Teleport: not supported by Teleport` error. ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/redshift-serverless.mdx b/docs/pages/database-access/guides/redshift-serverless.mdx index 1cb2065ac9fa6..98b9d57ed7801 100644 --- a/docs/pages/database-access/guides/redshift-serverless.mdx +++ b/docs/pages/database-access/guides/redshift-serverless.mdx @@ -8,12 +8,15 @@ This guide will help you to: - Set up Teleport to access your AWS Redshift Serverless workgroups. - Connect to your databases through Teleport. - + + ![Teleport Database Access Redshift Self-Hosted](../../../img/database-access/guides/redshift_selfhosted_serverless.png) - - + + ![Teleport Database Access Redshift Cloud](../../../img/database-access/guides/redshift_cloud_serverless.png) - + + + ## Prerequisites @@ -355,3 +358,4 @@ prior to logging in as this new IAM role to avoid or resolve user permission iss - Learn how to [restrict access](../rbac.mdx) to certain users and databases. - View the [High Availability (HA)](../guides/ha.mdx) guide. - Take a look at the YAML configuration [reference](../reference/configuration.mdx). + diff --git a/docs/pages/database-access/guides/snowflake.mdx b/docs/pages/database-access/guides/snowflake.mdx index 3dd72c5359021..cc441e9611041 100644 --- a/docs/pages/database-access/guides/snowflake.mdx +++ b/docs/pages/database-access/guides/snowflake.mdx @@ -19,12 +19,15 @@ This guide will help you to: - Assign Teleport's public key to a Snowflake user. - Connect to Snowflake through Teleport. - + + ![Teleport Database Access Snowflake Self-Hosted](../../../img/database-access/guides/snowflake_selfhosted.png) - - + + ![Teleport Database Access Snowflake Cloud](../../../img/database-access/guides/snowflake_cloud.png) - + + + ## Prerequisites @@ -157,3 +160,4 @@ $ tsh db logout ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) + diff --git a/docs/pages/database-access/guides/sql-server-ad.mdx b/docs/pages/database-access/guides/sql-server-ad.mdx index 3b124c0b2759e..98235e41b11be 100644 --- a/docs/pages/database-access/guides/sql-server-ad.mdx +++ b/docs/pages/database-access/guides/sql-server-ad.mdx @@ -14,12 +14,14 @@ This guide will help you to: - Set up access to SQL Server using Active Directory authentication. - Connect to SQL Server through Teleport. - + + ![Teleport Database Access SQL Server Self-Hosted](../../../img/database-access/guides/sqlserver_selfhosted.png) - - + + ![Teleport Database Access SQL Server Cloud](../../../img/database-access/guides/sqlserver_cloud.png) - + + This guide will focus on Amazon RDS for SQL Server using AWS-managed Active Directory authentication. @@ -213,7 +215,8 @@ Install Teleport on the host where you will run the Teleport Database Service: Active Directory domain as the SQL Server. - + + Configure the Teleport Database Service. Make sure to update `--proxy` to point to your Teleport Proxy Service address and `--uri` to the SQL Server @@ -233,8 +236,8 @@ endpoint. --labels=env=dev ``` - - + + Configure the Teleport Database Service. Make sure to update `--proxy` to point to your Teleport Cloud tenant address and `--uri` to the SQL Server @@ -254,7 +257,9 @@ endpoint. --labels=env=dev ``` - + + + Provide Active Directory parameters: @@ -317,7 +322,8 @@ master> CREATE LOGIN [EXAMPLE\alice] FROM WINDOWS WITH DEFAULT_DATABASE = [maste Log in to your Teleport cluster. Your SQL Server database should appear in the list of available databases: - + + ```code $ tsh login --proxy=teleport.example.com --user=alice @@ -327,8 +333,8 @@ $ tsh db ls # sqlserver env=dev ``` - - + + ```code $ tsh login --proxy=mytenant.teleport.sh --user=alice @@ -338,7 +344,9 @@ $ tsh db ls # sqlserver env=dev ``` - + + + To retrieve credentials for a database and connect to it: @@ -388,3 +396,4 @@ Add the Certificate Authority (CA) `ca_cert_file` into the `tls` section so Tele - [Manually join a Linux instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/join_linux_instance.html) in the AWS documentation. - [Introduction to `adutil`](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-ad-auth-adutil-introduction) in the Microsoft documentation. + diff --git a/docs/pages/database-access/reference/cli.mdx b/docs/pages/database-access/reference/cli.mdx index e6aa29766d698..08431c6dece2f 100644 --- a/docs/pages/database-access/reference/cli.mdx +++ b/docs/pages/database-access/reference/cli.mdx @@ -21,7 +21,8 @@ the Database Service, including: Starts Teleport Database Service. - + + ```code $ teleport db start \ @@ -32,8 +33,8 @@ $ teleport db start \ --uri=postgres.example.com:5432 ``` - - + + ```code $ teleport db start \ @@ -44,7 +45,9 @@ $ teleport db start \ --uri=postgres.mytenant.teleport.sh:5432 ``` - + + + | Flag | Description | | - | - | @@ -70,7 +73,8 @@ $ teleport db start \ Creates a sample Database Service configuration. - + + ```code $ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2 @@ -83,8 +87,8 @@ $ teleport db configure create \ --labels=env=prod ``` - - + + ```code $ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2 @@ -97,7 +101,9 @@ $ teleport db configure create \ --labels=env=prod ``` - + + + | Flag | Description | | - | - | @@ -347,3 +353,4 @@ $ tsh db config --format=cmd example | Flag | Description | | - | - | | `--format` | Output format: `text` is default, `cmd` to print native database client connect command. | + diff --git a/docs/pages/database-access/reference/configuration.mdx b/docs/pages/database-access/reference/configuration.mdx index 5e7208553cd7a..1395e9a706fb1 100644 --- a/docs/pages/database-access/reference/configuration.mdx +++ b/docs/pages/database-access/reference/configuration.mdx @@ -169,7 +169,8 @@ spec: You can create a new `db` resource by running the following commands, which assume that you have created a YAML file called `db.yaml` with your configuration: - + + ```code # Log in to your cluster with tsh so you can use tctl from your local machine. @@ -180,8 +181,8 @@ $ tsh login --proxy=teleport.example.com --user=myuser $ tctl create -f db.yaml ``` - - + + ```code # Log in to your Teleport cluster so you can use tctl from your local machine. @@ -190,4 +191,7 @@ $ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl create -f db.yaml ``` - + + + + diff --git a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx index 3a24ee770ca32..d3274679ea585 100644 --- a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx +++ b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx @@ -861,3 +861,4 @@ $ ./connect.sh node ### AWS quotas (!docs/pages/includes/aws-quotas.mdx!) + diff --git a/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx b/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx index 83102ec1f68f4..8ffef3aa7665c 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx @@ -261,7 +261,8 @@ Edit your `values.yaml` file to refer to the name of your secret: ## Step 4/6. Set values to configure the cluster - + + Before you can install Teleport in your Kubernetes cluster, you will need to create a secret that contains your Teleport license information. @@ -275,12 +276,15 @@ this secret as long as your file is named `license.pem`. $ kubectl -n teleport create secret generic license --from-file=license.pem ``` - + + + Next, configure the `teleport-cluster` Helm chart to use the `aws` mode. Create a file called `aws-values.yaml` and write the values you've chosen above to it: - + + @@ -341,8 +345,8 @@ podSecurityPolicy: - - + + @@ -405,7 +409,9 @@ podSecurityPolicy: - + + + Install the chart with the values from your `aws-values.yaml` file using this command: @@ -638,3 +644,4 @@ users and setting up RBAC. See the [high availability section of our Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx#highavailability) for more details on high availability. Read the [`cert-manager` documentation](https://cert-manager.io/docs/). + diff --git a/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx b/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx index ba8a1f60adeec..710e9c139434e 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx @@ -123,7 +123,9 @@ $ kubectl label namespace teleport 'pod-security.kubernetes.io/enforce=baseline' namespace/teleport labeled ``` - +If you are running a self-hosted Teleport Enterprise cluster, you will need to +create a secret that contains your Teleport license information before you can +install Teleport. Before you can install Teleport in your Kubernetes cluster, you will need to create a secret that contains your Teleport license information. @@ -133,11 +135,9 @@ create a secret that contains your Teleport license information. Create a secret from your license file. Teleport will automatically discover this secret as long as your file is named `license.pem`. -```code -$ kubectl -n teleport create secret generic license --from-file=license.pem -``` - - + ```code + $ kubectl -n teleport create secret generic license --from-file=license.pem + ``` Note that although the `proxy_service` listens on port 3080 inside the pod, @@ -265,3 +265,4 @@ users and setting up RBAC. To see all of the options you can set in the values file for the `teleport-cluster` Helm chart, consult our [reference guide](../../reference/helm-reference/teleport-cluster.mdx). + diff --git a/docs/pages/deploy-a-cluster/helm-deployments/digitalocean.mdx b/docs/pages/deploy-a-cluster/helm-deployments/digitalocean.mdx index a0174a050aa84..23f62b1be0c22 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/digitalocean.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/digitalocean.mdx @@ -248,3 +248,4 @@ Teleport: - [Set up Machine ID with Kubernetes](../../machine-id/guides/kubernetes.mdx) - [Federated Access using Trusted Clusters](../../kubernetes-access/manage-access/federation.mdx) - [Single-Sign On and Kubernetes Access Control](../../kubernetes-access/controls.mdx) + diff --git a/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx b/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx index 9582c3bb9eaf6..c958225c369f4 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx @@ -301,7 +301,8 @@ Next, configure the `teleport-cluster` Helm chart to use the `gcp` mode. Create file called `gcp-values.yaml` file and write the values you've chosen above to it: - + + ```yaml chartMode: gcp @@ -323,8 +324,8 @@ podSecurityPolicy: enabled: false ``` - - + + ```yaml chartMode: gcp @@ -343,7 +344,9 @@ highAvailability: enterprise: true # Indicate that this is a Teleport Enterprise deployment ``` - + + + Install the chart with the values from your `gcp-values.yaml` file using this command: @@ -494,3 +497,4 @@ Access](../../access-controls/introduction.mdx) section to get started enrolling users and setting up RBAC. See the [high availability section of our Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx#highavailability) for more details on high availability. + diff --git a/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx b/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx index cfb6228d71de1..b6422ed34315d 100644 --- a/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx +++ b/docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx @@ -5,12 +5,7 @@ description: Getting started with Teleport. Let's deploy Teleport in a Kubernete Teleport can provide secure, unified access to your Kubernetes clusters. This guide will show you how to: - -- Deploy Teleport Enterprise in a Kubernetes cluster. - - - Deploy Teleport in a Kubernetes cluster. - - Set up Single Sign-On (SSO) for authentication to your Teleport cluster. While completing this guide, you will deploy one Teleport pod each for the Auth Service and Proxy Service in your Kubernetes cluster, and a load balancer that allows outside traffic to your Teleport cluster. Users can then access your Kubernetes cluster via the Teleport cluster running within it. diff --git a/docs/pages/desktop-access/active-directory.mdx b/docs/pages/desktop-access/active-directory.mdx index dd8ea7133f77b..9c56fce113be2 100644 --- a/docs/pages/desktop-access/active-directory.mdx +++ b/docs/pages/desktop-access/active-directory.mdx @@ -67,11 +67,9 @@ In this step, you will use the Teleport Web UI to download and run two scripts: ### Install Active Directory In your web browser, access the Teleport Web UI at the address of your Proxy -Service host, e.g., -`teleport.example.com` -`mytennant.teleport.sh`. Go to the Desktops section, -then select **Add Desktop**. Select **Active Directory** resource to start -the guided enrollment from the **Enroll New Resource** section. +Service host, e.g., `example.teleport.sh`. Go to the Desktops section, then +select **Add Desktop**. Select **Active Directory** resource to start the guided +enrollment from the **Enroll New Resource** section. If you already have Active Directory installed on your Windows Server host, skip to the next step. Otherwise, copy and paste the first command provided into a diff --git a/docs/pages/includes/database-access/tctl-auth-sign.mdx b/docs/pages/includes/database-access/tctl-auth-sign.mdx index 7c596bdd90988..6eeca14de1b3d 100644 --- a/docs/pages/includes/database-access/tctl-auth-sign.mdx +++ b/docs/pages/includes/database-access/tctl-auth-sign.mdx @@ -3,11 +3,9 @@ databases must be configured with Teleport's certificate authority to be able to verify client certificates. They also need a certificate/key pair that Teleport can verify. - - -Your Teleport Cloud user -must be allowed to impersonate the system role `Db` in order to be able to -generate the database certificate. +If you are using Teleport Cloud, your Teleport user must be allowed to +impersonate the system role `Db` in order to be able to generate the database +certificate. Include the following `allow` rule in in your Teleport Cloud user's role: @@ -18,4 +16,3 @@ allow: roles: ["Db"] ``` - diff --git a/docs/pages/includes/enterprise/oidcauthentication.mdx b/docs/pages/includes/enterprise/oidcauthentication.mdx index ffe640a6c868c..5ecb3a6ce3b3a 100644 --- a/docs/pages/includes/enterprise/oidcauthentication.mdx +++ b/docs/pages/includes/enterprise/oidcauthentication.mdx @@ -1,12 +1,7 @@ Configure Teleport to use OIDC authentication as the default instead of the local user database. - - -You can either edit your Teleport configuration file or create a dynamic -resource. - - +Follow the instructions for your Teleport edition: @@ -41,3 +36,4 @@ resource. ``` + diff --git a/docs/pages/includes/enterprise/samlauthentication.mdx b/docs/pages/includes/enterprise/samlauthentication.mdx index ccef0885ac754..c955e985a14c7 100644 --- a/docs/pages/includes/enterprise/samlauthentication.mdx +++ b/docs/pages/includes/enterprise/samlauthentication.mdx @@ -52,3 +52,4 @@ auth_service: If you need to log in again before configuring your SAML provider, use the flag `--auth=local`. + diff --git a/docs/pages/includes/plugins/rbac-update.mdx b/docs/pages/includes/plugins/rbac-update.mdx index 855b6d114b3a0..39e1ece12a52c 100644 --- a/docs/pages/includes/plugins/rbac-update.mdx +++ b/docs/pages/includes/plugins/rbac-update.mdx @@ -38,8 +38,9 @@ As with all Teleport users, the Teleport Auth Service authenticates the will need to request the credentials manually by *impersonating* the `access-plugin` role and user. -If you are using `tctl` from the Auth -Service host, you will already have impersonation privileges. +If you are running a self-hosted Teleport Enterprise deployment and are using +`tctl` from the Auth Service host, you will already have impersonation +privileges. To grant your user impersonation privileges for `access-plugin`, define a role called `access-plugin-impersonator` by pasting the following YAML document into diff --git a/docs/pages/includes/plugins/rbac.mdx b/docs/pages/includes/plugins/rbac.mdx index 275519f6bb31b..a7a3740929738 100644 --- a/docs/pages/includes/plugins/rbac.mdx +++ b/docs/pages/includes/plugins/rbac.mdx @@ -38,8 +38,9 @@ As with all Teleport users, the Teleport Auth Service authenticates the will need to request the credentials manually by *impersonating* the `access-plugin` role and user. -If you are using `tctl` from the Auth -Service host, you will already have impersonation privileges. +If you are running a self-hosted Teleport Enterprise deployment and are using +`tctl` from the Auth Service host, you will already have impersonation +privileges. To grant your user impersonation privileges for `access-plugin`, define a role called `access-plugin-impersonator` by pasting the following YAML document into diff --git a/docs/pages/includes/sso/loginerrortroubleshooting.mdx b/docs/pages/includes/sso/loginerrortroubleshooting.mdx index 3e3fa0a839fd5..7c691e2dc93fa 100644 --- a/docs/pages/includes/sso/loginerrortroubleshooting.mdx +++ b/docs/pages/includes/sso/loginerrortroubleshooting.mdx @@ -1,14 +1,13 @@ Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to: - -- Ensure that HTTP/TLS certificates are configured properly for both the Teleport - Proxy Service and the SSO provider. - - Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport. - Be able to see how Teleport maps the received claims to role mappings as defined in the connector. +- For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS + certificates are configured properly for both the Teleport Proxy Service and + the SSO provider. If something is not working, we recommend to: @@ -58,3 +57,4 @@ spec: 'env': 'dev' version: v5 ``` + diff --git a/docs/pages/includes/tctl.mdx b/docs/pages/includes/tctl.mdx index 596ffa5e8ea88..1c6448dfbd94e 100644 --- a/docs/pages/includes/tctl.mdx +++ b/docs/pages/includes/tctl.mdx @@ -1,10 +1,8 @@ -You can sign in to your Teleport cluster using `tsh` and can use `tctl` -remotely: +Make sure you can connect to your Teleport cluster by authenticating with `tsh` +so you can execute commands with the `tctl` admin tool: -{/* Ignoring scope linting since we use this partial throughout the docs and -cannot guarantee that it will line up with a page's configured scopes*/} -{/*lint ignore scopes*/} - + + ```code $ tsh login --proxy=teleport.example.com --user=email@example.com @@ -15,11 +13,12 @@ $ tctl status ``` You can run subsequent `tctl` commands in this guide on your local machine. -For full privileges, you can also run `tctl` commands on your Teleport Auth Service host. - -{/*lint ignore scopes*/} - +For full privileges, you can also run `tctl` commands on your Teleport Auth +Service host. + + + ```code $ tsh login --proxy=myinstance.teleport.sh --user=email@example.com @@ -31,4 +30,6 @@ $ tctl status You must run subsequent `tctl` commands in this guide on your local machine. - + + + diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx index 6577bb358161f..72904d55bd9f9 100644 --- a/docs/pages/installation.mdx +++ b/docs/pages/installation.mdx @@ -81,7 +81,8 @@ Currently supported distributions (and `ID`) are: (!docs/pages/includes/install-linux.mdx!) - + +
@@ -97,13 +98,15 @@ We will also continue to maintain the legacy APT repo at Check the [Downloads](https://goteleport.com/download/) page for the most up-to-date information. - - + + Check the [Cloud Downloads](./choose-an-edition/teleport-cloud/downloads.mdx) page for the most up-to-date information on obtaining Teleport binaries compatible with Teleport Cloud. - + + + ## Docker @@ -472,3 +475,4 @@ infrastructure. Get started with: - [Application Access](application-access/introduction.mdx) - [Desktop Access](desktop-access/introduction.mdx) - [Machine ID](machine-id/introduction.mdx) + diff --git a/docs/pages/machine-id/getting-started.mdx b/docs/pages/machine-id/getting-started.mdx index a96ef9d17c602..c437f28ff32ca 100644 --- a/docs/pages/machine-id/getting-started.mdx +++ b/docs/pages/machine-id/getting-started.mdx @@ -44,14 +44,17 @@ Before you create a bot user, you need to determine which role(s) you want to assign to it. You can use the `tctl` command below to examine what roles exist on your system. - + + On your client machine, log in to Teleport using `tsh`, then use `tctl` to examine what roles exist on your system. - - + + Connect to the Teleport Auth Server and use `tctl` to examine what roles exist on your system. - + + + ```code $ tctl get roles --format=text @@ -137,21 +140,6 @@ the foreground to better understand how it works. - - - ```code - $ export TELEPORT_ANONYMOUS_TELEMETRY=1 - $ sudo tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=(=presets.tokens.first=) \ - --join-method=token \ - --auth-server=teleport.example.com:443 - ``` - - - - ```code $ export TELEPORT_ANONYMOUS_TELEMETRY=1 $ sudo tbot start \ @@ -162,29 +150,12 @@ the foreground to better understand how it works. --auth-server=example.teleport.sh:443 ``` - - - - ```code $ export TELEPORT_ANONYMOUS_TELEMETRY=1 $ sudo tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=iam-token \ - --join-method=iam \ - --auth-server=teleport.example.com:443 - ``` - - - - - ```code - $ export TELEPORT_ANONYMOUS_TELEMETRY=1 - $ tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=iam-token \ @@ -192,8 +163,6 @@ the foreground to better understand how it works. --auth-server=example.teleport.sh:443 ``` - - @@ -203,15 +172,16 @@ this by omitting this. Replace the following fields with values from your own cluster. - + + - `token` is the token output by the `tctl bots add` command or the name of your IAM method token. - `destination-dir` is where Machine ID writes user certificates that can be used by applications and tools. - `data-dir` is where Machine ID writes its private data, including its own short-lived renewable certificates. These should not be used by applications and tools. - `auth-server` is the address of your Teleport Cloud Proxy Server, for example `example.teleport.sh:443`. - - + + - `token` is the token output by the `tctl bots add` command or the name of your IAM method token. - `ca-pin` is the CA Pin for your Teleport cluster, and is output by the `tctl bots add` command. @@ -222,7 +192,9 @@ Replace the following fields with values from your own cluster. Auth Server is direct connectivity is available. `teleport.example.com:443`. - + + + Now that Machine ID has successfully started, let's investigate the `/opt/machine-id` directory to see what was written to disk. @@ -278,16 +250,19 @@ $ ssh -F /opt/machine-id/ssh_config root@node-name.example.com In addition to the `ssh` client you can use `tsh`. Replace the `--proxy` parameter with your proxy address. - + + ```code $ tsh ssh --proxy=teleport.example.com -i /opt/machine-id/identity root@node-name ``` - - + + ```code $ tsh ssh --proxy=mytenant.teleport.sh -i /opt/machine-id/identity root@node-name ``` - + + + The below error can occur when the bot does not have permission to log in to @@ -326,3 +301,4 @@ use-case, for example: - [Machine ID with Databases](./guides/databases.mdx) [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](./reference/telemetry.mdx) + diff --git a/docs/pages/machine-id/guides/applications.mdx b/docs/pages/machine-id/guides/applications.mdx index 1841a45d47851..2503ad48bac15 100644 --- a/docs/pages/machine-id/guides/applications.mdx +++ b/docs/pages/machine-id/guides/applications.mdx @@ -67,7 +67,8 @@ configured above. Be sure to note the bot join token and CA PIN. Next, on the bot node, create a Machine ID configuration file at `/etc/tbot.yaml`: - + + ```yaml auth_server: "example.teleport.sh:443" onboarding: @@ -81,8 +82,8 @@ destinations: - directory: /opt/machine-id app: grafana-example ``` - - + + ```yaml auth_server: "teleport.example.com:443" onboarding: @@ -96,7 +97,8 @@ destinations: - directory: /opt/machine-id app: grafana-example ``` - + + Be sure to configure the `token` and `ca_pins` fields to match the output from `tctl bots add ...`, and set `app` to match the desired name as shown in @@ -172,7 +174,8 @@ certificate files can be used: You may use these credentials with any client application that supports them. - + + The Teleport Proxy makes apps available via subdomains of its public web address. Given an app named `grafana-example` and a Teleport Proxy at `https://example.teleport.sh:443`, the app may be accessed at @@ -185,8 +188,8 @@ $ curl --user admin:admin \ --key /opt/machine-id/key \ https://grafana-example.example.teleport.sh/api/users ``` - - + + The Teleport Proxy makes apps available via subdomains of its public web address. Given an app named `grafana-example` and a Teleport Proxy at `https://teleport.example.com:443`, the app may be accessed at @@ -199,7 +202,9 @@ $ curl --user admin:admin \ --key /opt/machine-id/key \ https://grafana-example.teleport.example.com/api/users ``` - + + + Note that in the example above, we include `--user` to provide a local username and password to our Grafana instance. This is not necessary if your application @@ -220,16 +225,19 @@ Service, it's also possible to open a local proxy to the app using `tbot proxy app ...` in situations where the Teleport Proxy Service's app endpoints are unavailable: - + + ```code $ tbot proxy --destination-dir=/opt/machine-id --proxy=example.teleport.sh:443 app --port=1234 grafana-example ``` - - + + ```code $ tbot proxy --destination-dir=/opt/machine-id --proxy=teleport.example.com:443 app --port=1234 grafana-example ``` - + + + You may now connect to the app via a local proxy at `http://localhost:1234`: @@ -288,3 +296,4 @@ has been configured to use both the client certificate and key. Application to remove the need for additional login credentials. [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../reference/telemetry.mdx) + diff --git a/docs/pages/machine-id/guides/databases.mdx b/docs/pages/machine-id/guides/databases.mdx index 2eb80f2346540..79f3cdb82ec71 100644 --- a/docs/pages/machine-id/guides/databases.mdx +++ b/docs/pages/machine-id/guides/databases.mdx @@ -69,21 +69,24 @@ $ tctl create -f role.yaml With the role created, create a new bot and allow it to assume the new role. - + + On your client machine, log in to Teleport using `tsh` before using `tctl` to create the bot: ```code $ tctl bots add app --roles=machine-id-db ``` - - + + Connect to the Teleport Auth Server and use `tctl` to create the bot: ```code $ tctl bots add app --roles=machine-id-db ``` - + + + ## Step 2/3. Configure and start Machine ID @@ -92,7 +95,8 @@ credentials. Start by creating a configuration file for Machine ID at `/etc/tbot.yaml`: - + + ```yaml auth_server: "example.teleport.sh:443" onboarding: @@ -114,8 +118,8 @@ destinations: configs: - mongo ``` - - + + ```yaml auth_server: "teleport.example.com:443" onboarding: @@ -137,7 +141,8 @@ destinations: configs: - mongo ``` - + + Be sure to configure the `token` and `ca_pins` fields to match the output from `tctl bots add ...`. We've also included the `mongo` config template in the @@ -292,3 +297,4 @@ access controls. ## Next steps [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../reference/telemetry.mdx) + diff --git a/docs/pages/machine-id/guides/host-certificate.mdx b/docs/pages/machine-id/guides/host-certificate.mdx index 301b35d0764bd..63026ff04e3cf 100644 --- a/docs/pages/machine-id/guides/host-certificate.mdx +++ b/docs/pages/machine-id/guides/host-certificate.mdx @@ -170,21 +170,6 @@ First, create a basic configuration file using the following parameters: - - - ```code - $ tbot configure \ - --data-dir=/var/lib/teleport/bot \ - --token=(=presets.tokens.first=) \ - --join-method=token \ - --certificate-ttl=1h0m0s \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=auth.example.com:3025 - ``` - - - - ```code $ tbot configure \ --data-dir=/var/lib/teleport/bot \ @@ -195,26 +180,9 @@ First, create a basic configuration file using the following parameters: --auth-server=example.teleport.sh:443 ``` - - - - - ```code - $ tbot configure \ - --data-dir=/var/lib/teleport/bot \ - --token=iam-token \ - --join-method=iam \ - --certificate-ttl=1h0m0s \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=auth.example.com:3025 - ``` - - - - ```code $ tbot configure \ --data-dir=/var/lib/teleport/bot \ @@ -225,8 +193,6 @@ First, create a basic configuration file using the following parameters: --auth-server=example.teleport.sh:443 ``` - - diff --git a/docs/pages/machine-id/guides/jenkins.mdx b/docs/pages/machine-id/guides/jenkins.mdx index 28526225c6e69..900e2f0cee2a2 100644 --- a/docs/pages/machine-id/guides/jenkins.mdx +++ b/docs/pages/machine-id/guides/jenkins.mdx @@ -77,15 +77,16 @@ spec: "group": "api" ``` - + + On your client machine, log in to Teleport using `tsh` before using `tctl`. ```code $ tctl create -f api-workers.yaml $ tctl bots add jenkins --roles=api-workers ``` - - + + Connect to the Teleport Auth Server and use `tctl` to examine what roles exist on your system. @@ -93,7 +94,9 @@ your system. $ tctl create -f api-workers.yaml $ tctl bots add jenkins --roles=api-workers ``` - + + + Machine ID allows you to use Linux Access Control Lists (ACLs) to control access to certificates on disk. You will use this to limit the access Jenkins @@ -127,7 +130,8 @@ $ sudo tbot init \ Next, you need to start Machine ID in the background of each Jenkins worker. - + + First create a configuration file for Machine ID at `/etc/tbot.yaml`. ```yaml @@ -142,8 +146,8 @@ Next, you need to start Machine ID in the background of each Jenkins worker. destinations: - directory: /opt/machine-id ``` - - + + First create a configuration file for Machine ID at `/etc/tbot.yaml`. ```yaml auth_server: "auth.example.com:3025" @@ -157,7 +161,8 @@ First create a configuration file for Machine ID at `/etc/tbot.yaml`. destinations: - directory: /opt/machine-id ``` - + + Next, create a systemd.unit file at `/etc/systemd/system/machine-id.service`. @@ -208,3 +213,4 @@ familiar Teleport access controls. ## Next steps [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../reference/telemetry.mdx) + diff --git a/docs/pages/machine-id/guides/kubernetes.mdx b/docs/pages/machine-id/guides/kubernetes.mdx index 16412d7f1720c..fdd5335115540 100644 --- a/docs/pages/machine-id/guides/kubernetes.mdx +++ b/docs/pages/machine-id/guides/kubernetes.mdx @@ -152,7 +152,8 @@ note the bot join token and CA PIN. Next, on the bot node, create a Machine ID configuration file at `/etc/tbot.yaml`: - + + ```yaml auth_server: "example.teleport.sh:443" onboarding: @@ -166,8 +167,8 @@ destinations: - directory: /opt/machine-id kubernetes_cluster: example-k8s-cluster ``` - - + + ```yaml auth_server: "teleport.example.com:443" onboarding: @@ -181,7 +182,8 @@ destinations: - directory: /opt/machine-id kubernetes_cluster: example-k8s-cluster ``` - + + Be sure to configure the `token` and `ca_pins` fields to match the output from `tctl bots add ...`, and set `kubernetes_cluster` to match the cluster name as diff --git a/docs/pages/machine-id/troubleshooting.mdx b/docs/pages/machine-id/troubleshooting.mdx index 1f812f2d9bb83..5f755d63a7b1b 100644 --- a/docs/pages/machine-id/troubleshooting.mdx +++ b/docs/pages/machine-id/troubleshooting.mdx @@ -22,12 +22,12 @@ ERROR: failed direct dial to auth server: auth API: access denied [00] In particular, note the message `auth API: access denied`. - -The Teleport Auth Service will also provide some additional context: +In self-hosted Teleport deployments, the Teleport Auth Service will also provide +some additional context: + ```text [AUTH] WARN lock targeting User:"bot-example" is in force: The bot user "bot-example" has been locked due to a certificate generation mismatch, possibly indicating a stolen certificate. auth/apiserver.go:224 ``` - ### Explanation @@ -340,3 +340,4 @@ Kubernetes public address is populated in `proxy.kube.public_addr`. ```bash curl https://teleport.example.com:443/webapi/ping | jq ``` + diff --git a/docs/pages/management/admin/labels.mdx b/docs/pages/management/admin/labels.mdx index b54588ebc3a52..bac0ced1b92b4 100644 --- a/docs/pages/management/admin/labels.mdx +++ b/docs/pages/management/admin/labels.mdx @@ -100,7 +100,8 @@ starting Teleport. On the host where you will run your Node, paste the following content into `/etc/teleport.yaml` and adjust it for your environment: - + + ```yaml version: v3 @@ -125,8 +126,8 @@ ssh_service: environment: dev ``` - - + + ```yaml version: v3 @@ -147,7 +148,9 @@ ssh_service: environment: dev ``` - + + + Next, start Teleport with the invite token you created earlier: @@ -181,7 +184,8 @@ your Node. Run the following command to get the current logins for your user: - + + ```code $ tsh status @@ -195,8 +199,23 @@ $ tsh status Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - + + + +```code +$ tsh status +> Profile URL: https://teleport.example.com:443 + Logged in as: myuser + Cluster: teleport.example.com + Roles: access, editor, reviewer + Logins: -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe + Kubernetes: enabled + Valid until: 2022-04-27 22:26:50 -0400 EDT [valid for 11h40m0s] + Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + + + ```code tsh status @@ -210,7 +229,9 @@ tsh status Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - + + + In this example, `-teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe` means that no logins have been assigned to the user. @@ -264,7 +285,8 @@ Teleport configuration file. Edit `/etc/teleport.yaml` to define a `commands` array as shown below: - + + ```yaml version: v3 @@ -291,8 +313,8 @@ ssh_service: period: 1h0m0s ``` - - + + ```yaml version: v3 @@ -319,7 +341,9 @@ ssh_service: period: 1h0m0s ``` - + + + Notice that the `command` setting is an array where the first element is a valid executable and each subsequent element is an argument. @@ -389,3 +413,4 @@ For more information, see You can also use labels to limit the access that different roles have to specific classes of resources. For more information, see [Teleport Role Templates](../../access-controls/guides/role-templates.mdx). + diff --git a/docs/pages/management/admin/troubleshooting.mdx b/docs/pages/management/admin/troubleshooting.mdx index 7ec24a64765c4..479814bc07bf8 100644 --- a/docs/pages/management/admin/troubleshooting.mdx +++ b/docs/pages/management/admin/troubleshooting.mdx @@ -7,18 +7,13 @@ In this guide, we will explain how to address issues or unexpected behavior in y Teleport cluster. You can use these steps to get more visibility into the `teleport` process so -you can troubleshoot the Auth -Service, Proxy Service, and resource-specific services such as -the Application Service and Database Service. +you can troubleshoot the Auth Service, Proxy Service, and Teleport agent +services such as the Application Service and Database Service. ## Prerequisites (!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- A host where you have installed and configured the `teleport` binary. - - - (!docs/pages/includes/tctl.mdx!) ## Step 1/3. Enable verbose logging @@ -121,8 +116,6 @@ Teleport v8.3.7 git:v8.3.7-0-ga8d066935 go1.17.3 You can also collect the versions of the Teleport Auth Service, Proxy Service, and client tools to rule out version compatibility issues. - - To see the version of the Auth Service and Proxy Service, run the following command: @@ -136,8 +129,6 @@ Jwt CA never updated CA pin (=presets.ca_pin=) ``` - - Get the versions of your client tools: ```code @@ -200,3 +191,4 @@ does not explicitly indicate that something is misconfigured. ## `ssh: overflow reading version string` (!docs/pages/includes/tls-multiplexing-warnings.mdx!) + diff --git a/docs/pages/management/admin/trustedclusters.mdx b/docs/pages/management/admin/trustedclusters.mdx index 4b819d6551d59..5f83619a3074f 100644 --- a/docs/pages/management/admin/trustedclusters.mdx +++ b/docs/pages/management/admin/trustedclusters.mdx @@ -146,7 +146,8 @@ required for accessing a shell on the Node. On your local machine, log in to your leaf cluster using your Teleport username: - + + ```code # Log out of all clusters to begin this guide from a clean state @@ -154,8 +155,8 @@ $ tsh logout $ tsh login --proxy=leafcluster.teleport.sh --user=myuser ``` - - + + ```code # Log out of all clusters to begin this guide from a clean state @@ -163,7 +164,9 @@ $ tsh logout $ tsh login --proxy=leafcluster.example.com --user=myuser ``` - + + + Create a file called `visitor.yaml` with the following content: @@ -201,22 +204,25 @@ you can satisfy the conditions of the role and access the Node. Make sure that you are logged in to your root cluster. - + + ```code $ tsh logout $ tsh login --proxy=rootcluster.example.com --user=myuser ``` - - + + ```code $ tsh logout $ tsh login --proxy=rootcluster.teleport.sh --user=myuser ``` - + + + Create a file called `user.yaml` with your current user configuration. Replace `myuser` with your Teleport username: @@ -262,7 +268,8 @@ You can create a join token using the `tctl` tool. First, log out of all clusters and log in to the root cluster. - + + ```code $ tsh logout @@ -277,8 +284,24 @@ $ tsh login --user=myuser --proxy=rootcluster.example.com Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - - + + + +```code +$ tsh logout +$ tsh login --user=myuser --proxy=rootcluster.example.com +> Profile URL: https://rootcluster.example.com:443 + Logged in as: myuser + Cluster: rootcluster.example.com + Roles: access, auditor, editor, reviewer + Logins: root + Kubernetes: enabled + Valid until: 2022-04-29 03:07:22 -0400 EDT [valid for 12h0m0s] + Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + + + ```code $ tsh login --user=myuser --proxy=myrootclustertenant.teleport.sh @@ -292,7 +315,9 @@ $ tsh login --user=myuser --proxy=myrootclustertenant.teleport.sh Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty ``` - + + + Execute the following command on your development machine: @@ -369,8 +394,7 @@ Change the fields of `trusted_cluster.yaml` as follows: #### `metadata.name` -Use the name of your root cluster, e.g., `teleport.example.com``mytenant.teleport.sh`. +Use the name of your root cluster, e.g., `example.teleport.sh`. #### `spec.token` @@ -381,7 +405,8 @@ This is join token you created earlier. This is the reverse tunnel address of the Proxy Service in the root cluster. Run the following command to retrieve the value you should use: - + + ```code $ PROXY=rootcluster.example.com @@ -389,8 +414,8 @@ $ curl https://${PROXY?}/webapi/ping | jq 'if .proxy.tls_routing_enabled == true "rootcluster.example.com:443" ``` - - + + ```code $ PROXY=rootcluster.teleport.sh @@ -398,29 +423,34 @@ $ curl https://${PROXY?}/webapi/ping | jq 'if .proxy.tls_routing_enabled == true "rootcluster.teleport.sh:443" ``` - + + + #### `web_proxy_addr` This is the address of the Proxy Service on the root cluster. Obtain this with the following command: - + + ```code $ curl https://${PROXY?}/webapi/ping | jq .proxy.ssh.public_addr "teleport.example.com:443" ``` - - + + ```code $ curl https://${PROXY?}/webapi/ping | jq .proxy.ssh.public_addr "mytenant.teleport.sh:443" ``` - + + + #### `spec.role_map` @@ -549,20 +579,23 @@ $ tsh logout Log in to the leaf cluster: - + + ```code $ tsh login --user=myuser --proxy=leafcluster.example.com ``` - - + + ```code $ tsh login --user=myuser --proxy=leafcluster.teleport.sh ``` - + + + Create the Trusted Cluster: @@ -597,7 +630,8 @@ Log out of the leaf cluster and log back in to the root cluster. When you run `tsh clusters`, you should see listings for both the root cluster and the leaf cluster: - + + ```code $ tsh clusters @@ -607,8 +641,8 @@ Cluster Name Status Cluster Type Select rootcluster.example.com online root * leafcluster.example.com online leaf ``` - - + + ```code $ tsh clusters @@ -617,7 +651,9 @@ Cluster Name Status Cluster Type Select rootcluster.teleport.sh online root * leafcluster.teleport.sh online leaf ``` - + + + ## Step 3/5. Manage access to your Trusted Cluster @@ -653,7 +689,8 @@ version: v3 Still logged in to the root cluster, use `tctl` to update the labels on the leaf cluster: - + + ```code $ tctl update rc/leafcluster.teleport.sh --set-labels=env=demo @@ -661,8 +698,8 @@ $ tctl update rc/leafcluster.teleport.sh --set-labels=env=demo # Cluster leafcluster.teleport.sh has been updated ``` - - + + ```code $ tctl update rc/leafcluster.example.com --set-labels=env=demo @@ -670,7 +707,9 @@ $ tctl update rc/leafcluster.example.com --set-labels=env=demo # Cluster leafcluster.example.com has been updated ``` - + + + ### Change cluster access privileges @@ -731,22 +770,25 @@ Node in your leaf cluster as a user of your root cluster. First, make sure that you are logged in to root cluster: - + + ```code $ tsh logout $ tsh --proxy=rootcluster.example.com --user=myuser login ``` - - + + ```code $ tsh logout $ tsh --proxy=rootcluster.teleport.sh --user=myuser login ``` - + + + To log in to your Node, confirm that your Node is joined to your leaf cluster: @@ -831,20 +873,23 @@ cluster and editing the `trusted_cluster` resource you created earlier. Retrieve the Trusted Cluster resource you created earlier: - + + ```code $ tctl get trusted_cluster/rootcluster.example.com > trusted_cluster.yaml ``` - - + + ```code $ tctl get trusted_cluster/rootcluster.teleport.sh > trusted_cluster.yaml ``` - + + + Make the following change to the resource: @@ -878,39 +923,45 @@ On the leaf cluster, run the following command. This performs the same tasks as setting `enabled` to `false` in a `trusted_cluster` resource, but also removes the Trusted Cluster resource from the Auth Service backend: - + + ```code $ tctl rm trusted_cluster/rootcluster.example.com ``` - - + + ```code $ tctl rm trusted_cluster/rootcluster.teleport.sh ``` - + + + Next, run the following command on the root cluster. This command deletes the certificate authorities associated with the remote cluster and removes the `remote_cluster` resource from the root cluster's Auth Service backend. - + + ```code $ tctl rm rc/leafcluster.example.com ``` - - + + ```code $ tctl rm rc/leafcluster.teleport.sh ``` - + + + @@ -1002,3 +1053,4 @@ should check to see the following: - Read more about how Trusted Clusters fit into Teleport's overall architecture: [Architecture Introduction](../../architecture/trustedclusters.mdx). + diff --git a/docs/pages/management/admin/users.mdx b/docs/pages/management/admin/users.mdx index 8e016c21966e6..c75b0173d8e08 100644 --- a/docs/pages/management/admin/users.mdx +++ b/docs/pages/management/admin/users.mdx @@ -6,10 +6,6 @@ description: Learn how to manage local users in Teleport. Local users are stored In Teleport, **local users** are users managed directly via Teleport, rather than a third-party identity provider. -Local user accounts can be used alongside external user accounts managed via -GitHub as well as OIDC and SAML -2.0. - This guide shows you how to: - [Add local users](./users.mdx#adding-local-users) @@ -131,3 +127,4 @@ information, see [GitHub SSO](../../access-controls/sso/github-sso.mdx). + diff --git a/docs/pages/management/export-audit-events/elastic-stack.mdx b/docs/pages/management/export-audit-events/elastic-stack.mdx index cfec384611946..de91fb436d74a 100644 --- a/docs/pages/management/export-audit-events/elastic-stack.mdx +++ b/docs/pages/management/export-audit-events/elastic-stack.mdx @@ -17,12 +17,8 @@ stores them in Elasticsearch for visualization and alerting in Kibana. (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- Logstash version 8.4.1 or above running on a Linux host. Logstash must be - listening on a TCP port that is open to traffic from the Teleport Auth - Serviceyour Teleport Cloud - tenant. In this guide, you will also run the Event Handler - plugin on this host. +- Logstash version 8.4.1 or above running on a Linux host. In this guide, you + will also run the Event Handler plugin on this host. - Elasticsearch and Kibana version 8.4.1 or above, either running via an Elastic Cloud account or on your own infrastructure. You will need permissions to diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index bd9d11cfcf3bb..d9188329623cc 100644 --- a/docs/pages/reference/cli/tctl.mdx +++ b/docs/pages/reference/cli/tctl.mdx @@ -1056,7 +1056,8 @@ These flags are available for all commands `--debug, --config` . Run ### Examples - + + ```code $ tctl get users @@ -1070,8 +1071,8 @@ $ tctl get clusters,users $ tctl get all > state.yaml ``` - - + + ```code $ tctl get users @@ -1083,7 +1084,9 @@ $ tctl get cluster/east $ tctl get clusters,users ``` - + + + ## tctl edit @@ -1392,3 +1395,4 @@ Print the version of your `tctl` binary: tctl version ``` + diff --git a/docs/pages/server-access/getting-started.mdx b/docs/pages/server-access/getting-started.mdx index f48abd8dbced7..26e2a745f0a4e 100644 --- a/docs/pages/server-access/getting-started.mdx +++ b/docs/pages/server-access/getting-started.mdx @@ -89,7 +89,8 @@ server. On your Node, save `token.file` to an appropriate, secure, directory you have the rights and access to read. - + + Start the Node. Change `tele.example.com` to the address of your Teleport Proxy Service. Assign the `--token` flag to the path where you saved @@ -103,8 +104,8 @@ $ sudo teleport start \ --auth-server=tele.example.com:443 ``` - - + + Start the Node. Change `mytenant.teleport.sh` to your Teleport Cloud tenant address. Assign the `--token` flag to the path where you saved `token.file`. @@ -117,7 +118,9 @@ $ sudo teleport start \ --auth-server=mytenant.teleport.sh:443 ``` - + + + ### Access the Web UI @@ -153,7 +156,8 @@ We can use `tsh` to SSH into the cluster: ### Log in to the cluster - + + On your local machine, log in to your cluster through `tsh`, assigning the `--proxy` flag to the address of your Teleport Proxy Service: @@ -163,8 +167,8 @@ On your local machine, log in to your cluster through `tsh`, assigning the $ tsh login --proxy=tele.example.com --user=tele-admin ``` - - + + On your local machine, log in to your cluster through `tsh`, assigning the `--proxy` flag to the address of your Teleport Cloud tenant: @@ -174,13 +178,16 @@ On your local machine, log in to your cluster through `tsh`, assigning the $ tsh login --proxy=mytenant.teleport.sh --user=tele-admin ``` - + + + You'll be prompted to supply the password and second factor we set up previously. `tele-admin` will now see something similar to: - + + ```txt > Profile URL: https://tele.example.com:443 @@ -196,8 +203,8 @@ Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty In this example, `tele-admin` is now logged into the `tele.example.com` cluster through Teleport SSH. - - + + ```txt > Profile URL: https://mytenant.teleport.sh:443 @@ -213,8 +220,9 @@ Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty In this example, `tele-admin` is now logged into the `mytenant.teleport.sh` cluster through Teleport SSH. + - + ### Display cluster resources @@ -267,23 +275,11 @@ The `tsh ssh` command allows users to do anything they could if they were to SSH To use the `ssh` client generate a SSH configuration file and postfix the cluster name after the node name. - - ```code $ tsh config > ssh_config_teleport - $ ssh -F ssh_config_teleport root@ip-172-31-41-144.tele.example.com + $ ssh -F ssh_config_teleport root@ip-172-31-41-144.example.teleport.sh ``` - - - - ```code - $ tsh config > ssh_config_teleport - $ ssh -F ssh_config_teleport root@ip-172-31-41-144.mytenant.teleport.sh - ``` - - - @@ -365,3 +361,4 @@ Feel free to shut down, clean up, and delete your resources, or use them in furt - [How to SSH properly](https://goteleport.com/blog/how-to-ssh-properly/) - Consider whether [OpenSSH or Teleport SSH](https://goteleport.com/blog/openssh-vs-teleport/) is right for you. - [Labels](../management/admin/labels.mdx) + diff --git a/docs/pages/server-access/guides/openssh.mdx b/docs/pages/server-access/guides/openssh.mdx index e06468847c2ad..a97fcc8f5ecb6 100644 --- a/docs/pages/server-access/guides/openssh.mdx +++ b/docs/pages/server-access/guides/openssh.mdx @@ -188,7 +188,8 @@ generated earlier. First, make sure you are running OpenSSH's `ssh-agent` and have logged in to your Teleport cluster: - + + ```code $ tsh status @@ -200,12 +201,25 @@ $ tsh status Kubernetes: enabled Valid until: 2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s] Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty -$ eval `ssh-agent` -Agent pid 5931 ``` - - + + + +```code +$ tsh status +> Profile URL: https://teleport.example.com:443 + Logged in as: myuser + Cluster: teleport.example.com + Roles: access, auditor, editor, reviewer, host-certifier + Logins: ubuntu, root + Kubernetes: enabled + Valid until: 2022-05-06 22:54:01 -0400 EDT [valid for 11h53m0s] + Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty +``` + + + ```code $ tsh status @@ -221,7 +235,9 @@ $ eval `ssh-agent` Agent pid 5931 ``` - + + + The `ssh-agent` command prints additional commands to export the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` environment variables. These variables allow OpenSSH clients @@ -323,7 +339,8 @@ First, define environment variables for the address of your Teleport cluster, the username you will use to log in to your `sshd` host, and the port on your `sshd` host you are using for SSH traffic: - + + ```code # See the available logins you can use to access your sshd host @@ -334,8 +351,8 @@ $ CLUSTER=teleport.example.com $ PORT=22 ``` - - + + ```code # See the available logins you can use to access your sshd host @@ -346,7 +363,9 @@ $ CLUSTER=mytenant.teleport.sh $ PORT=22 ``` - + + + Next, SSH in to your remote host: @@ -422,4 +441,4 @@ are two options available for revoking access: CA rotations, and Teleport locks. roles, servers, desktops, or MFA devices. When a lock is created any existing sessions where the lock applies will be terminated, and new sessions will be rejected while the lock remains in force. For more information, read our - [Session and Identity Locking Guide](../../access-controls/guides/locking.mdx). \ No newline at end of file + [Session and Identity Locking Guide](../../access-controls/guides/locking.mdx). diff --git a/docs/pages/server-access/guides/ssh-pam.mdx b/docs/pages/server-access/guides/ssh-pam.mdx index 91da8c2063846..ab8593a13c370 100644 --- a/docs/pages/server-access/guides/ssh-pam.mdx +++ b/docs/pages/server-access/guides/ssh-pam.mdx @@ -115,7 +115,8 @@ include: ## Display a Message of the Day (MOTD) with Teleport - + + A cluster-wide Message of the Day can be set in the `auth_service` configuration. @@ -138,15 +139,17 @@ the traditional Unix `/etc/motd` file. The `/etc/motd` file is normally displayed by login(1) after a user has logged in but before the shell is run. It is generally used for important system-wide announcements. - - + + You can set a per-Node Message of the Day using the traditional Unix `/etc/motd` file. The `/etc/motd` file is normally displayed by login(1) after a user has logged in but before the shell is run. It is generally used for important system-wide announcements. - + + + This feature can help you inform users that activity on the Node is being audited and recorded. @@ -298,3 +301,4 @@ ssh_service: # use the "auth" modules in the PAM config use_pam_auth: true ``` +