Skip to content

Commit

Permalink
Fix Vale issues in 36 docs guides
Browse files Browse the repository at this point in the history
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 3, 2025
1 parent 8ea5516 commit d6fc85f
Show file tree
Hide file tree
Showing 36 changed files with 112 additions and 336 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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](
Expand Down
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
Expand Up @@ -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.

Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
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
Expand Up @@ -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.
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
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
Expand Up @@ -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

Expand Down
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
Expand Up @@ -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
Expand Down
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
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/admin-guides/api/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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>

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ here. The license file isn't used in Teleport Community Edition installs.)
$ export TF_VAR_route53_zone="example.com"
```

Our Terraform setup requires you to have your domain provisioned in AWS Route 53 - it will automatically add
Our Terraform setup requires you to have your domain provisioned in Amazon Route 53 - it will automatically add
DNS records for [`route53_domain`](#route53\_domain) as set up below. You can list these with this command:

```code
Expand Down Expand Up @@ -367,7 +367,7 @@ $ export TF_VAR_enable_auth_asg_instance_refresh="false"
```

This variable can be used to enable automatic instance refresh on the Teleport
**auth server** AWS Autoscaling Group (ASG) - the refresh is triggered by
**Auth Service** AWS Autoscaling Group (ASG) - the refresh is triggered by
changes to the launch template or configuration.
Enable the auth ASG instance refresh with caution - upgrading the version of
Teleport will trigger an instance refresh and **auth servers must be scaled down
Expand Down
Loading

0 comments on commit d6fc85f

Please sign in to comment.