# Authentication Options Teleport authenticates users either via the Proxy Service or with an identity provider via **authentication connectors**. --- TIP This guide explains authentication options for human users. For AI agents and machines, see [Machine & Workload ID](https://goteleport.com/docs/machine-workload-identity/introduction.md). --- ## Local (no authentication connector) Local authentication is used to authenticate against a local Teleport user database. This database is managed by the [`tctl users`](https://goteleport.com/docs/reference/cli/tctl.md) command. Teleport also supports multi-factor authentication (MFA) for the local connector. There are several possible values (types) of MFA: - `otp` is the default for self-hosted Teleport deployments. 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` is the default for cloud-hosted Teleport Enterprise accounts. It implements the [Web Authentication standard](https://webauthn.guide) for utilizing multi-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 [Harden your Cluster Against IdP Compromises](https://goteleport.com/docs/zero-trust-access/management/security/idp-compromise.md) 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. --- 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. --- **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. ``` auth_service: authentication: type: local second_factors: ["webauthn"] # Possible values: "otp", "webauthn", and "sso". webauthn: rp_id: example.teleport.sh ``` ### Dynamic resource Edit your `cluster_auth_preference` resource: ``` $ tctl edit cap ``` Ensure that the resource includes the following content: ``` kind: cluster_auth_preference metadata: name: cluster-auth-preference spec: type: local second_factors: ["webauthn"] webauthn: rp_id: example.teleport.sh version: v2 ``` Save and close the file in your editor to apply changes. **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: ``` $ tsh login --proxy=myinstance.teleport.sh $ tctl status ``` Edit your `cluster_auth_preference` resource: ``` $ tctl edit cap ``` Ensure that `cap.yaml` includes the following content: ``` kind: cluster_auth_preference metadata: name: cluster-auth-preference spec: type: local second_factors: ["webauthn"] # Possible values: "otp", "webauthn", and "sso". webauthn: rp_id: example.teleport.sh version: v2 ``` Save and close the file in your editor to apply changes. ### 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. Open the user resource in your editor, assigning username to the name of your Teleport user: ``` $ tctl edit users/username ``` The resource should resemble the following: ``` 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`, save the file, and close your editor. The user will now be unblocked from login attempts and can attempt to authenticate again. ## Authentication connectors **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: ``` kind: cluster_auth_preference metadata: name: cluster-auth-preference spec: type: github version: v2 ``` See [GitHub OAuth 2.0](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/github-sso.md) 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: ``` 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: ``` kind: cluster_auth_preference metadata: name: cluster-auth-preference spec: type: oidc version: v2 ``` **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` : ``` auth_service: authentication: type: github ``` See [GitHub OAuth 2.0](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/github-sso.md) 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` : ``` 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` : ``` auth_service: authentication: type: oidc ``` **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` : ``` auth_service: authentication: type: github ``` See [GitHub OAuth 2.0](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/github-sso.md) for details on how to configure it. ## Require displaying a message of the day Teleport can display a custom message of the day (MOTD) for users prior to authenticating in the Teleport Web UI and CLI. ### Self-Hosted Add the following to your Teleport configuration file, which is stored in `/etc/teleport.yaml` by default. ``` auth_service: message_of_the_day: | Welcome to the Example Teleport Cluster All activity is monitored and should follow organization policies ``` Restart the Teleport Auth Service instances to apply this change. ### Teleport Enterprise Cloud/Dynamic Edit your `cluster_auth_preference` resource: ``` $ tctl edit cap ``` Ensure that the resource includes the `message_of_the_day` field: ``` kind: cluster_auth_preference metadata: name: cluster-auth-preference spec: message_of_the_day: | Welcome to the Example Teleport Cluster All activity is monitored and should follow organization policies type: local second_factor: "on" webauthn: rp_id: example.teleport.sh version: v2 ``` Save and close the file in your editor to apply changes.