Single Sign-On (SSO) for SSH

Introduction

The commercial edition of Teleport allows users to retreive 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.

How does SSO work with SSH?

From the user's perspective they need to execute the following command to retreive their SSH certificate.

$ tsh login

Teleport can be configured with a certificate TTL to determine how often a user needs to log in.

tsh login will print a URL into the console which, when opened with a web browser, will open an SSO login prompt, along with the 2FA, as enforced by the SSO provider. If user supplies valid credentials, Teleport will issue an SSH certificate.

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:
auth_service:
    # defines the default authentication connector type:
    authentication:
        type: saml

An example of a connector:

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

  acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs
  attributes_to_roles:
    - {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
metadata:
  name: sso_user
spec:
  allow:
    logins:
    - '{{external.unix_login}}'
    node_labels:
      '*': '*'

Multiple SSO Providers

Teleport can also support multiple connectors. This works by supplying a connector name to tsh login via --auth argument:

# use "okta" SAML connector:
$ tsh --proxy=proxy.example.com login --auth=okta

# use local Teleport user DB:
$ tsh --proxy=proxy.example.com login --auth=local --user=admin

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

Troubleshooting

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

If something is not working, we recommend to:

Teleport Enterprise

Teleport Enterprise is built around the open-source core, with premium support and additional, enterprise-grade features. It is for organizations that need to secure critical production infrastructure and meet compliance and audit requirements.

Demo Teleport Enterprise

Teleport Community

Teleport Community provides modern SSH best practices out of the box for managing elastic infrastructure. Teleport Community is open-source software that anyone can download and install for free.

Download Teleport Community