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

  • local connector type uses the built-in user database. This database can be manipulated by tctl users command.
  • saml connector type uses the SAML protocol to authenticate users and query their group membership.
  • oidc connector type uses the OpenID Connect protocol to authenticate users and query their group membership.

To configure SSO, a Teleport administrator must:

  • Update /etc/teleport.yaml on the auth server to set the default authentication connector.
  • Define the connector resource and save it into a YAML file (like connector.yaml)
  • Create the connector using tctl create connector.yaml.
# 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://teleprot-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"]}
  entity_descriptor: |
    <paste SAML XML contents here>

Multiple SSO Providers

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

$ tsh --proxy=proxy.example.com login --auth=corporate

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