Single Sign-On (SSO) for SSH

The commercial edition of Teleport allows users to login and retrieve their SSH credentials through a Single Sign-On (SSO) system used by the rest of the organization.

Examples of supported SSO systems include commercial solutions like Okta, Auth0, SailPoint, OneLogin or Active Directory, as well as open source products like Keycloak. Other identity management systems are supported as long as they provide an SSO mechanism based on either SAML or OAuth2/OpenID Connect.

SSO Setup Guides

How does SSO work with SSH?

From the user's perspective they need to execute the following command login:

# this command will automatically open the default web browser and take a user
# through the login process with an SSO provider:
$ tsh login

# output:
If browser window does not open automatically, open it by clicking on the link:

Teleport will wait for up to 3 minutes for a user to authenticate. If authentication succeeds, Teleport will retrieve an SSH certificate and will store it in ~/.tsh/keys/ directory and also will add it to an SSH agent if there's one running.

Configuring SSO

Teleport works with SSO providers by relying on a concept called "authentication connector". An auth connector is a plugin which controls how a user logs in and which group he or she belongs to.

The following connectors are supported:

To configure SSO, a Teleport administrator must:

# snippet from /etc/teleport.yaml on the auth server:
    # defines the default authentication connector type:
        type: saml

An example of a connector:

# connector.yaml
kind: saml
version: v2
  name: corporate
  # display allows to set the caption of the "login" button
  # in the Web interface
  display: "Okta"

    - {name: "groups", value: "okta-admin", roles: ["admin"]}
    - {name: "groups", value: "okta-dev", roles: ["dev"]}

     # note that wildcards can also be used. the next line instructs Teleport
     # to assign "admin" role to any user who has the SAML attribute that begins with "admin":
     - { name: "group", value: "admin*", roles: ["admin"] }
     # regular expressions with capture are also supported. the next line instructs Teleport
     # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1':
     - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] }

  entity_descriptor: |
    <paste SAML XML contents here>

User Logins

Often it is required to restrict SSO users to their unique UNIX logins when they connect to Teleport nodes. To support this:

kind: role
version: v3
  name: sso_user
    - '{{external.unix_login}}'
      '*': '*'

Working with External Email Identity

Along with sending groups, an SSO provider will also provide a user's email address. In many organizations, the username that a person uses to log into a system is the same as the first part of their email address - the 'local' part. For example, [email protected] might log in with the username dave.smith. Teleport 4.2.6+ adds an easy way to extract the first part of an email address so it can be used as a username - this is the {{email.local}} function.

If the email claim from the identity provider (which can be accessed via {{}}) is sent and contains an email address, you can extract the 'local' part of the email address before the @ sign like this: {{email.local(}}

Here's how this looks in a Teleport role:

kind: role
version: v3
  name: sso_user
    # Extracts the local part of [email protected], so the login will
    # now support dave.smith.
    - '{{email.local(}}'
      '*': '*'

Multiple SSO Providers

Teleport can also support multiple connectors, i.e. a Teleport administrator can define and create multiple connector resources using tctl create as shown above.

To see all configured connectors, execute this on the auth server:

$ tctl get connectors

To delete/update connectors, use the usual tctl rm and tctl create commands as described in the Resources section in the Admin Manual.

If multiple authentication connectors exist, the clients must supply a connector name to tsh login via --auth argument:

# use "okta" SAML connector:
$ tsh login --auth=okta

# use local Teleport user DB:
$ tsh login --auth=local --user=admin

Refer to the following guides to configure authentication connectors of both SAML and OIDC types:

SSO Customization

Provider YAML Example
Github display: Github github
Microsoft display: Microsoft microsoft
Google display: Google google
BitBucket display: Bitbucket bitbucket
OpenID display: Okta Okta


Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

If something is not working, we recommend to:

Try Teleport Today

In the Cloud, Self-hosted, or Open Source

View Developer Docs