Fork me on GitHub

Teleport

Teleport as a SAML identity provider

Improve
Preview

The SAML identity provider is currently in Preview mode.

How to use Teleport as an identity provider

This guide details an example on how to use Teleport as an identity provider to authenticate to external services.

Prerequisites

  • A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.

    tctl version

    Teleport Enterprise v12.1.1 go1.19

    tsh version

    Teleport v12.1.1 go1.19

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 12.1.1

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 12.1.2

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Example external application

We'll be using samltest.id to create a test consumer of Teleport's SAML identity provider.

Step 1/4. Configure a Teleport role with access to SAML service provider objects

First, ensure you are logged into Teleport as a user that has permissions to read and modify saml_idp_service_provider objects. The default editor role has access to this already, but in case you are using a more customized configuration, create a role called sp-manager.yaml with the following contents:

kind: role
metadata:
  name: sp-manager
spec:
  allow:
    rules:
    - resources:
      - saml_idp_service_provider
      verbs:
      - list
      - create
      - read
      - update
      - delete
version: v6

Create the role with tctl:

tctl create sp-manager.yaml

role 'saml-idp-service-provider-manager' has been created

Add the role to your user. Replace teleport-admin with your user name:

tctl users update --set-roles $(tctl get users/teleport-admin --format=json | \jq -r '.[].spec.roles | join(",")'), sp-manager teleport-admin

User teleport-admin has been updated:

New roles: auditor,editor,access,sp-manager

Step 2/4. Configure samltest.id to recognize Teleport's identity provider

The first step in configuring the application for SSO is retrieving Teleport's SAML identity provider metadata. You can obtain this metadata in XML format by navigating to https://<proxy-address>/enterprise/saml-idp/metadata. Save it in an easy to remember file name like teleport-metadata.xml.

Navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload teleport-metadata.xml.

Successful upload

Step 3/4. Obtain the service provider metadata and add it to Teleport

Download the service provider metadata from samltest.id as saml-sp.xml:

curl -o saml-sp.xml https://samltest.id/saml/sp

Using the template below, create a file called saml-sp.yaml. Assign the metadata you just downloaded to the entity_descriptor field in the saml_idp_service_provider object:

kind: saml_idp_service_provider
metadata:
  # The friendly name of the service provider. This is used to manage the
  # service provider as well as in identity provider initiated SSO.
  name: samltest-id
spec:
  # The entity_descriptor is the service provider XML.
  entity_descriptor: |
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"...
version: v1

Add this to Teleport using tctl:

tctl create saml-sp.yaml

SAML IdP service provider 'samltest-id' has been created.

Teleport now trusts the samltest.id service provider.

Step 4/4. Verify samltest.id login works

To verify everything works, navigate back to samltest.id's home page and select "Test Your IdP." From there, enter the entity ID of Teleport's identity provider, which is the same as the metadata URL: https://<proxy-address>/enterprise/saml-idp/metadata and click "Go!"

Test the IdP

If you are not already logged into Teleport, you will be prompted to login. Once you are logged in, you should be re-routed to a success page on samltest.id.

Successful login

This has verified service provider initiated SSO. To verify identity provider initiated SSO, navigate to https://<proxy-address>/enterprise/saml-idp/login/samltest-id, where samltest-id is the friendly name of the service provider object created earlier. You should be redirected to the same successful login page seen earlier.