Single Sign-On (SSO) for SSH

Users of the Enterprise edition of Teleport can login with SSH, Kubernetes, Databases and Web applications through a Single Sign-On (SSO) provider used the rest of the organization.

How does SSO work?

Users need to execute the following command login in the CLI or login using UI:

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

# output:
If browser window does not open automatically, open it by clicking on the link:
http://127.0.0.1:45235/055a310a-1099-43ea-8cf6-ffc41d88ad1f

Teleport will wait for up to 3 minutes for a user to authenticate. If authentication succeeds, Teleport will retrieve an SSH and X.509 certificates and will store them in ~/.tsh/keys/proxy.example.com directory. The tool will also will add SSH cert 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:

• local connector type uses the built-in user database. This database can be manipulated by the 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: "Okta"

  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>

• See examples/resources directory in the Teleport Github repository for examples of possible connectors.
• You may use entity_descriptor_url, in lieu of entity_descriptor, to fetch the entity descriptor from your IDP. Though, we recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL.

User Logins

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

• Use the SSO provider to create a field called "unix_login" (you can use another name).
• Make sure it's exposed as a claim via SAML/OIDC.
• Update a Teleport SSH role to include {{external.unix_login}} variable into the list of allowed logins:

kind: role
version: v4
metadata:
  name: sso_user
spec:
  allow:
    logins:
    - '{{external.unix_login}}'
    node_labels:
      '*': '*'

Provider-Specific Workarounds

Certain SSO providers may require or benefit from changes to Teleport's SSO flow. These provider-specific changes can be enabled by setting the spec.provider property of the connector definition to one of the following values to match your identity provider:

• adfs (SAML): Required for compatibility with Active Directory (ADFS); refer to the full ADFS guide for details.
• netiq (OIDC): Used to enable NetIQ-specific ACR value processing; refer to the OIDC guide for details.
• ping (SAML): Required for compatibility with Ping Identity (including PingOne and PingFederate) when "Enforced Signed Authn Requests" is enabled in the application settings.

At this time, the spec.provider field should not be set for any other identity providers.

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 provides 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 {{external.email}}) is sent and contains an email address, you can extract the 'local' part of the email address before the @ sign like this: {{email.local(external.email)}}

Here's how this looks in a Teleport role:

kind: role
version: v4
metadata:
  name: sso_user
spec:
  allow:
    logins:
    # Extracts the local part of [email protected], so the login will
    # now support dave.smith.
    - '{{email.local(external.email)}}'
    node_labels:
      '*': '*'

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 Reference.

If multiple authentication connectors exist, the clients must supply 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:

• SSH Authentication with Okta
• SSH Authentication with OneLogin
• SSH Authentication with ADFS
• SSH Authentication with OAuth2 / OpenID Connect

SSO Customization

Provider	YAML	Example
Github	display: Github
Microsoft	display: Microsoft
Google	display: Google
BitBucket	display: Bitbucket
OpenID	display: Okta

Troubleshooting

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

• Ensure that HTTP/TLS certificates are configured properly for both Teleport proxy and the SSO provider.
• Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
• Be able to see how Teleport maps the received claims to role mappings as defined in the connector.

If something is not working, we recommend to:

• Double-check the host names, tokens and TCP ports in a connector definition.
• Look into Teleport's audit log for claim mapping problems. It is usually stored on the auth server in the /var/lib/teleport/log directory.ad