mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-03 16:38:35 +08:00
Alex McGrath
65459e872e
* dont allow disabling second factor * update docs for 2fa change * add environmental variable to work around disabled 2fa * check if its cloud * update todos * add a test * introduce insecure test mode * fixes for tests
280 lines
7.5 KiB
Plaintext
280 lines
7.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/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: on
|
|
webauthn:
|
|
rp_id: example.teleport.sh
|
|
```
|
|
|
|
### 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 policies
|
|
|
|
Teleport requires that passwords for local users be at least 12 characters long.
|
|
|
|
Additionally, Teleport will lock local user accounts if there are multiple
|
|
failed login attempts within a 30-minute window. The account will remain locked
|
|
for 30 minutes before the user can 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>
|