Fork me on GitHub

Teleport

Teleport as a SAML identity provider

  • Available for:
  • Enterprise
  • Cloud
  • Team

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 Teleport Team account. If you do not have one, visit the signup page to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool version >= 13.3.9.

    You can download these tools from the Cloud Downloads page.

    tctl version

    Teleport Enterprise v13.3.9 go1.21


    tsh version

    Teleport v13.3.9 go1.21

  • A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.0.0, which you can download by visiting your Teleport account.

    tctl version

    Teleport Enterprise v14.0.0 go1.21


    tsh version

    Teleport v14.0.0 go1.21

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status

    Cluster teleport.example.com

    Version 14.0.0

    CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
  • If you're new to SAML, consider reviewing our SAML Identity Provider Reference before proceeding.

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

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.