Skip to content

Commit

Permalink
Fix Vale issues in 36 docs guides
Browse files Browse the repository at this point in the history
Fix Vale warnings

Fix Vale warnings across several guides within the
`docs/pages/admin-guides` section.

This includes removing the `teleport-cluster` migration guide, which
includes some Vale issues. This was an overdue TODO item.
  • Loading branch information
ptgott committed Jan 14, 2025
1 parent afc0042 commit fe24ade
Showing 41 changed files with 121 additions and 359 deletions.
8 changes: 1 addition & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1231,9 +1231,6 @@ The “teleport-cluster” Helm chart underwent significant refactoring in Telep
deployments and the new “scratch” chart mode makes it easier to provide a custom
Teleport config.

“Custom” mode users should follow the [migration
guide](docs/pages/admin-guides/deploy-a-cluster/helm-deployments/migration-v12.mdx).

### Dropped support for SHA1 in Teleport-protected servers

Newer OpenSSH clients connecting to Teleport 12 clusters no longer need the
@@ -1256,10 +1253,7 @@ Teleport 12 before upgrading.

#### Helm charts

The teleport-cluster Helm chart underwent significant changes in Teleport 12. To
upgrade from an older version of the Helm chart deployed in “custom” mode,
follow
the [migration guide](docs/pages/admin-guides/deploy-a-cluster/helm-deployments/migration-v12.mdx).
The teleport-cluster Helm chart underwent significant changes in Teleport 12.

Additionally, PSPs are removed from the chart when installing on Kubernetes 1.23
and higher to account for the deprecation/removal of PSPs by Kubernetes.
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@ layout: tocless-doc
---

Access Lists allow Teleport users to be granted long term access to resources
managed within Teleport. With Access Lists, administrators and access list
managed within Teleport. With Access Lists, administrators and Access List
owners can regularly audit and control membership to specific roles and
traits, which then tie easily back into Teleport's existing RBAC system.

Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@ description: Learn how to use Access Lists to manage and audit long lived access
---

This guide will help you:
- Create an access list
- Create an Access List
- Assign a member to it
- Verify permissions granted through the list membership

@@ -47,7 +47,7 @@ Try logging into the cluster with the test user to verify that no resources show

## Step 3/4. Create an Access List

Next, we'll create a simple access list that will grant the `access` role to its members.
Next, we'll create a simple Access List that will grant the `access` role to its members.
Login as the administrative user mentioned in the prerequisites. Click on "Add New" in the left pane, and then "Create an Access List."

![Navigate to create new Access List](../../../../img/access-controls/access-lists/create-new-access-list.png)
@@ -64,10 +64,10 @@ not be able to manage the list, though they will still be reflected as an owner.

![Select an owner](../../../../img/access-controls/access-lists/select-owner.png)

Under "Members" select `requester` as a required role, then add your test user to the access list. Similar to
Under "Members" select `requester` as a required role, then add your test user to the Access List. Similar to
the owner requirements, this will ensure that any member of the list must have the `requester` role in order to
be granted the access described in this list. If the user loses this role later, they will not be granted the
roles or traits described in the access list.
roles or traits described in the Access List.

![Add a member](../../../../img/access-controls/access-lists/add-member.png)

Original file line number Diff line number Diff line change
@@ -35,7 +35,7 @@ Once enrolled you can download the required `app.zip` file from the integrations
- An Azure resource group in the same directory. This will host resources for
the Microsoft Teams Access Request plugin. You should have enough
permissions to create and edit Azure Bot Services in this resource group.
- Someone with Global Admin rights on the Azure Active Directory that will grant
- Someone with Global Admin rights on Microsoft Entra ID in order to grant
permissions to the plugin.
- Someone with the `Teams administrator` role that can approve installation
requests for Microsoft Teams Apps.
Original file line number Diff line number Diff line change
@@ -35,11 +35,10 @@ by the `device_trust_mode` authentication setting:

(!docs/pages/includes/device-trust/prereqs.mdx!)

- We expect your Teleport cluster to be on version 13.3.6 and above, which has
the preset `require-trusted-device` role. The preset `require-trusted-device`
role does not enforce the use of a trusted device for
[Apps](#web-application-support) or [Desktops](#desktop-support). Refer to
their corresponding sections for instructions.
This guide makes use of the preset `require-trusted-device` role, which does not
enforce the use of a trusted device for [Apps](#web-application-support) or
[Desktops](#desktop-support). Refer to their corresponding sections for
instructions.

## Role-based trusted device enforcement

@@ -111,7 +110,7 @@ metadata:
name: cluster-auth-preference
spec:
type: local
second_factor: "on"
second_factors: ["webauthn"]
webauthn:
rp_id: (=clusterDefaults.clusterName=)
device_trust:
@@ -140,8 +139,8 @@ leaf clusters.

## Web application support

The Teleport App Service may enforce Device Trust via [role-based enforcement](
#role-based-trusted-device-enforcement).
The Teleport App Service may enforce Device Trust via [role-based
enforcement](#role-based-trusted-device-enforcement).

To access apps protected by Device Trust using the Web UI (Teleport v16 or
later), make sure your device is [registered and enrolled](
Original file line number Diff line number Diff line change
@@ -255,7 +255,7 @@ Make sure that the touch and PIN policy satisfy the hardware key requirement for

### `ERROR: private key policy not met`

This error is returned by the Auth and Proxy services if a user does not meet the required private key policy.
This error is returned by the Auth Service and Proxy Service if a user does not meet the required private key policy.
Both `tsh` and Teleport Connect automatically catch these errors and require the user to sign in again with a valid hardware-based private key.

### `ERROR: authenticating with management key: auth challenge: smart card error 6982: security status not satisfied`
Original file line number Diff line number Diff line change
@@ -26,7 +26,7 @@ For example:
## Prerequisites

- A Teleport cluster with WebAuthn configured.
See the [Second Factor: WebAuthn](./webauthn.mdx) guide.
See the [Harden your Cluster Against IdP Compromises](./webauthn.mdx) guide.
- WebAuthn hardware device, such as YubiKey.
- Machines for Headless WebAuthn activities have [Linux](../../../installation.mdx), [macOS](../../../installation.mdx) or [Windows](../../../installation.mdx) `tsh` binary installed.
- Machines used to approve Headless WebAuthn requests have a Web browser with [WebAuthn support](
4 changes: 2 additions & 2 deletions docs/pages/admin-guides/access-controls/guides/locking.mdx
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@ title: Session and Identity Locking
description: How to lock compromised users or agents
---

System administrators can disable a compromised user or Teleport agent—or
System administrators can disable a compromised user or Teleport Agent—or
prevent access during cluster maintenance—by placing a lock
on a session, user or host identity.

@@ -19,7 +19,7 @@ A lock can target the following objects or attributes:
../device-trust/enforcing-device-trust.mdx#locking-a-device) by the device ID
- an MFA device by the device's UUID
- an OS/UNIX login
- a Teleport agent by the agent's server UUID (effectively unregistering it from the
- a Teleport Agent by the Agent's server UUID (effectively unregistering it from the
cluster)
- a Windows desktop by the desktop's name
- an [Access Request](../access-requests/access-requests.mdx) by UUID
Original file line number Diff line number Diff line change
@@ -13,7 +13,7 @@ Examples of administrative actions include, but are not limited to:
- Inviting new users
- Updating cluster configuration resources
- Modifying access management resources
- Approving access requests
- Approving Access Requests
- Generating new join tokens
- Impersonation
- Creating new bots for Machine ID
@@ -41,15 +41,15 @@ their on-disk Teleport certificates.

- (!docs/pages/includes/tctl.mdx!)
- [WebAuthn configured](webauthn.mdx) on this cluster
- Second factor hardware device, such as YubiKey or SoloKey
- Multi-factor authentication hardware device, such as YubiKey or SoloKey
- A Web browser with [WebAuthn support](
https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) (if using
SSH or desktop sessions from the Teleport Web UI).

## Require MFA for administrative actions

MFA for administrative actions is automatically enforced for clusters where
WebAuthn is the only form of second factor allowed.
WebAuthn is the only form of multi-factor authentication allowed.

<Notice type="note">
In a future major version, Teleport may enforce MFA for administrative actions
24 changes: 13 additions & 11 deletions docs/pages/admin-guides/access-controls/guides/passwordless.mdx
Original file line number Diff line number Diff line change
@@ -11,16 +11,18 @@ usernameless authentication for Teleport.

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- Teleport must be configured for WebAuthn. See the [Second Factor:
WebAuthn](./webauthn.mdx) guide.
- A hardware device with support for WebAuthn and resident keys.
As an alternative, you can use a Mac with biometrics / Touch ID or device that
- Teleport must be configured for WebAuthn. See the [Harden your Cluster Against
IdP Compromises](./webauthn.mdx) guide.
- A hardware device with support for WebAuthn and resident keys. As an
alternative, you can use a Mac with biometrics / Touch ID or device that
supports Windows Hello (Windows 10 19H1 or later).
- A web browser with WebAuthn support. To see if your browser supports
WebAuthn, check the [WebAuthn
Compatibility](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) page.
- A signed and notarized version of `tsh` is required for Touch ID. This means versions
installed from Homebrew or compiled from source will not work. [Download the macOS tsh installer](../../../installation.mdx#macos).
- A web browser with WebAuthn support. To see if your browser supports WebAuthn,
check the [WebAuthn
Compatibility](https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/)
page.
- A signed and notarized version of `tsh` is required for Touch ID. This means
versions installed from Homebrew or compiled from source will not work.
[Download the macOS tsh installer](../../../installation.mdx#macos).
- (!docs/pages/includes/tctl.mdx!)

A Teleport cluster capable of WebAuthn is automatically capable of passwordless.
@@ -46,8 +48,8 @@ If you are using a hardware device, a passwordless registration will occupy a
resident key slot. Resident keys, also called discoverable credentials, are
stored in persistent memory in the authenticator (i.e., the device that is used
to authenticate). In contrast, MFA keys are encrypted by the authenticator and
stored in the Teleport Auth Server. Regardless of your device type, passwordless
registrations may also be used for regular MFA.
stored in the Teleport Auth Service backend. Regardless of your device type,
passwordless registrations may also be used for regular MFA.

<Admonition type="tip" title="Important">
If you plan on relying exclusively on passwordless, it's recommended to register
Original file line number Diff line number Diff line change
@@ -29,7 +29,7 @@ their on-disk Teleport certificates.

- (!docs/pages/includes/tctl.mdx!)
- [WebAuthn configured](webauthn.mdx) on this cluster
- Second factor hardware device, such as YubiKey or SoloKey
- Hardware device for multi-factor authentication, such as YubiKey or SoloKey
- A Web browser with [WebAuthn support](
https://developers.yubico.com/WebAuthn/WebAuthn_Browser_Support/) (if using
SSH or desktop sessions from the Teleport Web UI).
Original file line number Diff line number Diff line change
@@ -79,7 +79,7 @@ resource ID for workforce pool and workforce pool provider, respectively.
</Admonition>


## Step 2/3 Add workforce pool To Teleport
## Step 2/3. Add workforce pool To Teleport

Proceed to the next step in the UI by clicking the **Next** button.

@@ -95,7 +95,7 @@ values or attribute mapping in GCP, you must also updated the respective SAML se
</Admonition>


## Step 3/3 Create GCP IAM policy
## Step 3/3. Create GCP IAM policy

Once a pool and pool provider is configured in the GCP, and its respective configuration is added
to Teleport as a SAML service provider resource, users can sign in into the GCP web console, as
@@ -252,7 +252,7 @@ Save the spec as **pool_provider_name.yaml** file. And create the saml service p
$ tctl create pool_provider_name.yaml
```

## Step 3/3: Create GCP IAM policy
## Step 3/3. Create GCP IAM policy

This step is similar to Step 3 in the guided configuration flow.
You will need to create a GCP IAM policy representing the workforce principal.
22 changes: 12 additions & 10 deletions docs/pages/admin-guides/access-controls/sso/azuread.mdx
Original file line number Diff line number Diff line change
@@ -3,34 +3,36 @@ title: Teleport Authentication with Azure Active Directory (AD)
description: How to configure Teleport access with Azure Active Directory.
---

This guide will cover how to configure Microsoft Azure Active Directory to issue
credentials to specific groups of users with a SAML Authentication Connector.
When used in combination with role-based access control (RBAC), it allows Teleport
This guide will cover how to configure Microsoft Entra ID to issue credentials
to specific groups of users with a SAML Authentication Connector. When used in
combination with role-based access control (RBAC), it allows Teleport
administrators to define policies like:

- Only members of the "DBA" Azure AD group can connect to PostgreSQL databases.
- Only members of the "DBA" Microsoft Entra ID group can connect to PostgreSQL
databases.
- Developers must never SSH into production servers.

The following steps configure an example SAML authentication connector matching
Azure AD groups with security roles. You can choose to configure other options.
Microsoft Entra ID groups with security roles. You can choose to configure other
options.

## Prerequisites

Before you get started, you’ll need:

- An Azure AD admin account with access to creating non-gallery applications
(P2 License).
- A Microsoft Entra ID admin account with access to creating non-gallery
applications (P2 License).
- To register one or more users in the directory.
- To create at least two security groups in Azure AD and assign one or more
users to each group.
- To create at least two security groups in Microsoft Entra ID and assign one or
more users to each group.
- A Teleport role with access to maintaining `saml` resources. This is available
in the default `editor` role.

(!docs/pages/includes/commercial-prereqs-tabs.mdx!)

- (!docs/pages/includes/tctl.mdx!)

## Step 1/3. Configure Azure AD
## Step 1/3. Configure Microsoft Entra ID

### Create an enterprise application

2 changes: 1 addition & 1 deletion docs/pages/admin-guides/access-controls/sso/gitlab.mdx
Original file line number Diff line number Diff line change
@@ -183,7 +183,7 @@ spec:
- Developers also do not have any "allow rules" i.e. they will not be able to
see/replay past sessions or re-configure the Teleport cluster.

Create both roles on the auth server:
Create both roles on the Auth Service:

```code
$ tctl create -f admin.yaml
4 changes: 2 additions & 2 deletions docs/pages/admin-guides/access-controls/sso/sso.mdx
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@ Teleport users can log in to servers, Kubernetes clusters, databases, web
applications, and Windows desktops through their organization's Single Sign-On
(SSO) provider.

- [Azure Active Directory (AD)](azuread.mdx): Configure Azure Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps.
- [Microsoft Entra ID](azuread.mdx): Configure Microsoft Entra ID SSO for SSH, Kubernetes, databases, desktops and web apps.
- [Active Directory (ADFS)](adfs.mdx): Configure Windows Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps.
- [Google Workspace](google-workspace.mdx): Configure Google Workspace SSO for SSH, Kubernetes, databases, desktops and web apps.
- [GitHub](github-sso.mdx): Configure GitHub SSO for SSH,
@@ -449,7 +449,7 @@ Teleport can also support multiple connectors. For example, a Teleport
administrator can define and create multiple connector resources using
`tctl create` as shown above.

To see all configured connectors, execute this command on the Auth Server:
To see all configured connectors, execute this command on the Auth Service:

```code
$ tctl get connectors
2 changes: 1 addition & 1 deletion docs/pages/admin-guides/api/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -113,7 +113,7 @@ func main() {
}
```

Now you can run the program and connect the client to the Teleport Auth Server to fetch the server version.
Now you can run the program and connect the client to the Teleport Auth Service to fetch the server version.

```code
$ go run main.go
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@ description: "Deploying a high-availability Teleport cluster using Proxy Peering

This deployment architecture features two important design decisions:

- AWS Route 53 latency-based routing is used for global server load balancing
- Amazon Route 53 latency-based routing is used for global server load balancing
([GSLB](https://www.cloudflare.com/learning/cdn/glossary/global-server-load-balancing-gslb/)).
This allows for efficient distribution of traffic across resources that are globally distributed.
- Teleport's [Proxy Peering](../../../reference/architecture/proxy-peering.mdx) is used to reduce the total number of tunnel connections in the Teleport cluster.
@@ -22,12 +22,12 @@ entry while also ensuring minimal latency when accessing connected resources.
- Deployed exclusively in the AWS ecosystem
- High-availability Auto Scaling group of Auth Service instances that must remain in a single region
- High-availability Auto Scaling group of Proxy Service instances deployed across multiple regions
- [AWS Route 53 latency-based routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy-latency.html)
- [Amazon Route 53 latency-based routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy-latency.html)
- [GSLB](https://www.cloudflare.com/learning/cdn/glossary/global-server-load-balancing-gslb/)
- [Teleport TLS Routing](../../../reference/architecture/tls-routing.mdx) to reduce the number of ports needed to use Teleport
- [Teleport Proxy Peering](../../../reference/architecture/proxy-peering.mdx) for reducing the number of resource connections
- [AWS Network Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html)
- [AWS DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) for cluster state storage
- [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) for cluster state storage
- [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) for session recording storage

## Advantages of this deployment architecture
@@ -37,7 +37,7 @@ entry while also ensuring minimal latency when accessing connected resources.
- Provides a highly resilient, redundant HA architecture for Teleport that can quickly
scale with an organization's needs.
- All required Teleport components can be provisioned within the AWS ecosystem.
- Using load balancers for the Proxy and Auth Services allows for increased availability
- Using load balancers for the Proxy Service and Auth Service allows for increased availability
during Teleport cluster upgrades.

## Disadvantages of this deployment architecture
@@ -61,7 +61,7 @@ In other words, this must be a Layer 4 load balancer, not a Layer 7
type="warning"
title="Note"
>
Cross-zone load balancing is required for the Auth and Proxy service NLB configurations to route
Cross-zone load balancing is required for the Auth Service and Proxy Service NLB configurations to route
traffic across multiple zones. Doing this improves resiliency against localized AWS zone outages.
</Admonition>

@@ -182,7 +182,7 @@ additional settings.
In this deployment architecture, [Proxy Peering](../../../reference/architecture/proxy-peering.mdx) is used to restrict the number of connections made from
resources to proxies in the Teleport Cluster.

This guide covers the necessary Proxy Peering settings for deploying an HA Teleport Cluster routing resource
This guide covers the necessary Proxy Peering settings for deploying an HA Teleport cluster routing resource
traffic with GSLB.

### Auth Service Proxy Peering configuration
@@ -196,7 +196,7 @@ auth_service:
type: proxy_peering
agent_connection_count: 2
```
Reference the [Auth Server configuration](../../../reference/config.mdx) reference page
Reference the [Auth Service configuration](../../../reference/config.mdx) reference page
for additional settings.

### Proxy Service Proxy Peering configuration
Loading

0 comments on commit fe24ade

Please sign in to comment.