
Teleport
Teleport as a SAML identity provider
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- 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 andtsh
client tool version >= 13.3.9.You can download these tools from the Cloud Downloads page.
tctl versionTeleport Enterprise v13.3.9 go1.21
tsh versionTeleport 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 andtsh
client tool version >= 14.0.0, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v14.0.0 go1.21
tsh versionTeleport v14.0.0 go1.21
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 runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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.yamlrole '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-adminUser 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.yamlSAML 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.