mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-01 13:39:37 +08:00
Paul Gottschling
91c89b6126
* Organize docs guide sections chronologically This change aims to make docs navigation easier by organizing some docs sections according to the sequence of steps a user would take to set up Teleport. The current docs organization uses a variety of categories and schemes to organize the docs. For example, there is a "Home" section that includes the Changelog, Installation page, and Getting Started guides; a "Setup" section that includes references and admin guides; and edition-specific sections (Enterprise, Cloud). For a user who is setting up Teleport--or who has already done some setup work and wants more advanced instructions--it's difficult to know where in the docs to find the right information. This change organizes our how-to guides into the following categories that describe the process of setting up Teleport: - Try out Teleport - Deploy a Cluster (including choosing an edition) - Configure Access (including SSO, RBAC, and Access Requests) - Manage your Cluster (admin guides, operations, etc.) - Use Teleport (this section already exists) I moved the Reference section after this chronology, since users can access the reference guides anywhere in the setup process. As part of the change, I have also moved the content from the "Enterprise" and "Cloud" sections into "Deploy a Cluster", since this content has to do with how to deploy a specific edition of Teleport. Note that this change does _not_ attempt to reorganize our protocol-specific sections. While adding resources is part of the Teleport setup process, we have a lot of content in our protocol-specific sections, and moving it all into a single section related to adding resources to a cluster would (a) exceed the maximum depth for subsections in the nav bar and (b) cause more confusion than it alleviates. * Respond to PR feedback - Create a "Compliance Frameworks" section of "Configure Access" with the FedRAMP and SOC 2 guides - Rename "Use Teleport" to "Connect your Client" - Move the database GUI client guide into "Connect your Client" * Add redirects * Fix linter issues
241 lines
6.5 KiB
Plaintext
241 lines
6.5 KiB
Plaintext
---
|
|
title: Authentication options
|
|
description: A reference for Teleport's authentication connectors
|
|
---
|
|
|
|
Teleport authenticates users either via the Proxy Service or with an identity
|
|
provider via **authentication connectors**.
|
|
|
|
## Local (no authentication connector)
|
|
|
|
Local authentication is used to authenticate against a local Teleport user
|
|
database. This database is managed by the [`tctl users`](./cli.mdx#tctl-users-add)
|
|
command. Teleport also supports multi-factor authentication (MFA) for the local
|
|
connector. There are several possible values (types) of MFA:
|
|
|
|
- `otp` is the default. It implements the [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm)
|
|
standard. You can use [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator), [Authy](https://www.authy.com/) or any other TOTP client.
|
|
- `webauthn` implements the [Web Authentication standard](https://webauthn.guide) for utilizing
|
|
second factor authenticators and hardware devices.
|
|
You can use [YubiKeys](https://www.yubico.com/), [SoloKeys](https://solokeys.com/) or any other authenticator that
|
|
implements FIDO2 or FIDO U2F standards.
|
|
See our [Second Factor - WebAuthn](../access-controls/guides/webauthn.mdx) guide for detailed
|
|
instructions on setting up WebAuthn for Teleport.
|
|
- `on` enables both TOTP and WebAuthn, and all local users are required to have at least one MFA device registered.
|
|
- `optional` enables both TOTP and WebAuthn but makes it optional for users. Local users that register a MFA device will
|
|
be prompted for it during login. This option is useful when you need to gradually enable MFA usage before switching
|
|
the value to `on`.
|
|
- `off` turns off multi-factor authentication.
|
|
|
|
<Admonition type="note">
|
|
If you are using Teleport with a Single Sign-On solution, users can also register MFA devices, but Teleport will not prompt them for MFA during login. MFA for SSO users should be handled by the SSO provider.
|
|
</Admonition>
|
|
|
|
<Tabs>
|
|
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">
|
|
|
|
You can modify these settings either using a static configuration file or
|
|
dynamic configuration resources.
|
|
|
|
### Static configuration
|
|
|
|
Add the following to your Teleport configuration file, which is stored in
|
|
`/etc/teleport.yaml` by default.
|
|
|
|
```yaml
|
|
auth_service:
|
|
authentication:
|
|
type: local
|
|
second_factor: off
|
|
```
|
|
|
|
|
|
### Dynamic resource
|
|
|
|
Obtain your existing `cluster_auth_preference` resource:
|
|
|
|
```code
|
|
$ tctl get cap > cap.yaml
|
|
```
|
|
|
|
If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.
|
|
|
|
Ensure that `cap.yaml` includes the following content:
|
|
|
|
```yaml
|
|
kind: cluster_auth_preference
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
type: local
|
|
second_factor: "on"
|
|
webauthn:
|
|
rp_id: example.teleport.sh
|
|
version: v2
|
|
```
|
|
|
|
Create the `cluster_auth_preference` resource via `tctl`:
|
|
|
|
```code
|
|
$ tctl create -f cap.yaml
|
|
```
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Cloud">
|
|
|
|
You can modify these settings using dynamic configuration resources.
|
|
|
|
Log in to Teleport from your local machine so you can use the Enterprise
|
|
edition of the `tctl` admin tool:
|
|
|
|
```code
|
|
$ tsh login --proxy=myinstance.teleport.sh
|
|
$ tctl status
|
|
```
|
|
|
|
Obtain your existing `cluster_auth_preference` resource:
|
|
|
|
```code
|
|
$ tctl get cap > cap.yaml
|
|
```
|
|
|
|
If you have not defined a `cluster_auth_preference`, `cap.yaml` will be blank.
|
|
|
|
Ensure that `cap.yaml` includes the following content:
|
|
|
|
```yaml
|
|
kind: cluster_auth_preference
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
type: local
|
|
second_factor: "on"
|
|
webauthn:
|
|
rp_id: example.teleport.sh
|
|
version: v2
|
|
```
|
|
|
|
Create the `cluster_auth_preference` resource via `tctl`:
|
|
|
|
```code
|
|
$ tctl create -f cap.yaml
|
|
```
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
|
|
## Authentication connectors
|
|
|
|
<Tabs>
|
|
<TabItem scope={["cloud"]} label="Teleport Cloud">
|
|
|
|
### GitHub
|
|
|
|
This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/)
|
|
to learn how to create and register an OAuth app.
|
|
|
|
Here is an example of this setting in a `cluster_auth_preference` resource:
|
|
|
|
```yaml
|
|
kind: cluster_auth_preference
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
type: github
|
|
version: v2
|
|
```
|
|
|
|
See [GitHub OAuth 2.0](../access-controls/sso/github-sso.mdx) for details on how to configure it.
|
|
|
|
### SAML
|
|
|
|
This connector type implements SAML authentication. It can be configured against any external identity manager like Okta or Auth0.
|
|
|
|
Here is an example of this setting in a `cluster_auth_preference` resource:
|
|
|
|
```yaml
|
|
kind: cluster_auth_preference
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
type: saml
|
|
version: v2
|
|
```
|
|
|
|
### OIDC
|
|
|
|
Teleport implements OpenID Connect (OIDC) authentication.
|
|
|
|
Here is an example of this setting in a `cluster_auth_preference` resource:
|
|
|
|
```yaml
|
|
kind: cluster_auth_preference
|
|
metadata:
|
|
name: cluster-auth-preference
|
|
spec:
|
|
type: oidc
|
|
version: v2
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["enterprise"]} label="Enterprise">
|
|
|
|
### GitHub
|
|
|
|
This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/)
|
|
to learn how to create and register an OAuth app.
|
|
|
|
Here is an example of this setting in the `teleport.yaml` :
|
|
|
|
```yaml
|
|
auth_service:
|
|
authentication:
|
|
type: github
|
|
```
|
|
|
|
See [GitHub OAuth 2.0](../access-controls/sso/github-sso.mdx) for details on how to configure it.
|
|
|
|
### SAML
|
|
|
|
This connector type implements SAML authentication. It can be configured against any external identity manager like Okta or Auth0.
|
|
|
|
Here is an example of this setting in the `teleport.yaml` :
|
|
|
|
```yaml
|
|
auth_service:
|
|
authentication:
|
|
type: saml
|
|
```
|
|
|
|
### OIDC
|
|
|
|
Teleport implements OpenID Connect (OIDC) authentication, which is similar to SAML in principle.
|
|
|
|
Here is an example of this setting in the `teleport.yaml` :
|
|
|
|
```yaml
|
|
auth_service:
|
|
authentication:
|
|
type: oidc
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["oss"]} label="Open Source">
|
|
|
|
### GitHub
|
|
|
|
This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/)
|
|
to learn how to create and register an OAuth app.
|
|
|
|
Here is an example of this setting in the `teleport.yaml` :
|
|
|
|
```yaml
|
|
auth_service:
|
|
authentication:
|
|
type: github
|
|
```
|
|
|
|
See [GitHub OAuth 2.0](../access-controls/sso/github-sso.mdx) for details on how to configure it.
|
|
|
|
</TabItem>
|
|
</Tabs>
|