Get StartedContact Sales
Fork me on GitHub

Teleport

Authentication options

Version 14.x
  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

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 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 standard. You can use Google Authenticator, Authy or any other TOTP client.
  • webauthn implements the Web Authentication standard for utilizing second factor authenticators and hardware devices. You can use YubiKeys, SoloKeys or any other authenticator that implements FIDO2 or FIDO U2F standards. See our Second Factor - WebAuthn 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.

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_factor: off

Dynamic resource

Obtain your existing cluster_auth_preference resource:

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:

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:

tctl create -f cap.yaml

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

Obtain your existing cluster_auth_preference resource:

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:

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:

tctl create -f cap.yaml

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 20 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:

tctl get users/username > user.yaml

The file user.yaml 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 and save the file. Now update the user entry with the command below:

tctl create -f user.yaml

The user will now be unblocked from login attempts and can attempt to authenticate again.

Authentication connectors

GitHub

This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on 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 for details on how to configure it.

GitHub

This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on 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 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

GitHub

This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on 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 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

GitHub

This connector implements GitHub's OAuth 2.0 authentication flow. Please refer to GitHub's documentation on 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 for details on how to configure it.