Configure Single Sign-On

Report an Issue

Is this page helpful?

How can we improve this page?

Users can log in to Teleport through your organization's single sign-on (SSO) provider. You can centralize the way your infrastructure authenticates, authorizes, and audits users who want to access it, while also keeping your organization's existing processes for managing users.

To get started integrating your identity provider with Teleport, read Integrate your Identity Provider. The rest of this guide explains key concepts related to Teleport single sign-on integrations.

How Teleport uses SSO

You can register your Teleport cluster as an application with your SSO provider. When a user signs in to Teleport, your SSO provider will execute its own authentication flow, then send an HTTP request to your Teleport cluster to indicate that authentication has completed.

Teleport authenticates users to your infrastructure by issuing short-lived certificates. After a user completes an SSO authentication flow, Teleport issues a short-lived certificate to the user. Teleport also creates a temporary user on the Auth Service backend.

Temporary user resources

After a user completes an SSO authentication flow, Teleport creates a temporary user resource for the user.

When a user signs in to Teleport with tsh login, they can configure the TTL of the user Teleport creates. Teleport enforces a limit of 30 hours (the default is 12 hours).

In the Teleport audit log, you will see an event of type user.create with information about the temporary user.

How can I inspect a temporary user resource?

You can inspect a temporary user resource created via your SSO integration by using the tctl command:

Log in to your cluster with tsh so you can use tctl remotely
tsh login --proxy=example.teleport.sh
tctl get users/<username>

Here is an example of a temporary user resource created when the GitHub user myuser signed in to GitHub to authenticate to Teleport. This resource expires 12 hours after creation. The created_by field indicates that the resource was created by Teleport's GitHub SSO integration:

kind: user
metadata:
  expires: "2022-06-15T04:02:34.586688054Z"
  id: 0000000000000000000
  name: myuser
spec:
  created_by:
    connector:
      id: github
      identity: myuser
      type: github
    time: "2022-06-14T16:02:34.586688441Z"
    user:
      name: system
  expires: "0001-01-01T00:00:00Z"
  github_identities:
  - connector_id: github
    username: myuser
  roles:
  - editor
  - access
  - auditor
  status:
    is_locked: false
    lock_expires: "0001-01-01T00:00:00Z"
    locked_time: "0001-01-01T00:00:00Z"
  traits:
    github_teams:
    - my-team
    kubernetes_groups: null
    kubernetes_users: null
    logins:
    - root
version: v2

Certificates for SSO users

Along with creating a temporary user, Teleport issues SSH and X.509 certificates to a successfully authenticated SSO user's machine. This enables SSO users to authenticate to your cluster without Teleport needing to create a permanent record of them.

In the X.509 certificate, for example, the Subject field contains the same information defined in the temporary user resource. This enables Teleport to enforce RBAC rules for the authenticated user when they access resources in your cluster.

This is a Subject field for a certificate that Teleport issued for the GitHub user myuser, who signed in to a Teleport cluster via the GitHub SSO integration:

Subject: L=myuser/street=teleport.example.com/postalCode={"github_teams":["my-team"],"kubernetes_groups":null,"kubernetes_users":null,"logins":["root"]}, O=access, O=editor, O=auditor, CN=myuser/1.3.9999.1.7=teleport.example.com

The user belongs to the GitHub team my-team, which this Teleport cluster maps to the access, editor, and auditor roles in Teleport.

Inspecting your certificate subject

To inspect the contents of an X.509 certificate issued for your user after you sign in to Teleport via SSO, run the following commands:

TELEPORT_CLUSTER=<your cluster>
SSO_USER=<your username within your SSO provider>
openssl x509 -text -in ~/.tsh/keys/${TELEPORT_CLUSTER}/${SSO_USER}-x509.pem | grep "Subject:"

You can inspect an SSH certificate issued for your Teleport user with the following command:

ssh-keygen -L -f ~/.tsh/keys/${TELEPORT_CLUSTER}/${SSO_USER}-ssh/${TELEPORT_CLUSTER}-cert.pub

Logging in via SSO

Users can log in to Teleport via your SSO provider by executing a command similar to the following, using the --auth flag to specify the provider:

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 --auth=github

The command opens a browser window and shows a URL the user can visit in the terminal to complete their SSO flow:

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 SSH and X.509 certificates and store them in the ~/.tsh/keys/<clustername> directory. The tool will also will add SSH cert to an SSH agent if there's one running.

Was this page helpful?

How can we improve this page?