Teleport as a SAML identity provider

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

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

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!"

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.

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.