mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-02 23:31:08 +08:00
Paul Gottschling
176935cbfa
- Remove the `team` scope from config.json. - Edit the Edition comparison table to remove the "Team" column. - Change the Teleport Team getting started guide to a Teleport Enterprise Cloud getting started guide. - Remove other Teleport Team mentions from the docs.
279 lines
7.4 KiB
Plaintext
279 lines
7.4 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/tctl.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
|
|
```
|
|
|
|
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","team"]} label="Cloud-Hosted">
|
|
|
|
You can modify these settings using dynamic configuration resources.
|
|
|
|
Log in to Teleport from your local machine so you can use 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
|
|
```
|
|
|
|
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>
|
|
|
|
### Local user login failure rules
|
|
|
|
A local user is blocked from attempting logins if, within a 30 minute window, a local user has multiple:
|
|
|
|
- failed login attempts or
|
|
- failed password resets
|
|
|
|
The block lasts 30 minutes. After the block has expired the user may attempt to log in again.
|
|
|
|
Overriding a block is available to users with rights to maintain `user` resources,
|
|
available in the built-in `editor` role. To turn off a block, update the user entry,
|
|
following these steps.
|
|
|
|
Retrieve the user entry so you can edit the status:
|
|
|
|
```code
|
|
$ tctl get users/<Var name="username" /> > user.yaml
|
|
```
|
|
|
|
The file `user.yaml` should resemble the following:
|
|
|
|
```yaml
|
|
kind: user
|
|
metadata:
|
|
name: jeff
|
|
spec:
|
|
roles:
|
|
- access
|
|
status:
|
|
is_locked: true
|
|
lock_expires: "2023-04-22T01:55:02.228158166Z"
|
|
locked_message: user has exceeded maximum failed login attempts
|
|
version: v2
|
|
```
|
|
|
|
Update the `is_locked` field under `status` to `false` and save the file. Now
|
|
update the user entry with the command below:
|
|
|
|
```code
|
|
$ tctl create -f user.yaml
|
|
```
|
|
|
|
The user will now be unblocked from login attempts and can attempt to authenticate again.
|
|
|
|
## Authentication connectors
|
|
|
|
<Tabs>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise 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>
|