Teleport as a SAML identity provider
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
This guide details an example on how to use Teleport as an identity provider to authenticate to external services.
A Teleport Team account. If you do not have one, visit the signup page to begin your free trial.
tctladmin tool and
tshclient tool version >= 13.3.9.
You can download these tools from the Cloud Downloads page.tctl version
Teleport Enterprise v13.3.9 go1.21tsh 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.
tctladmin tool and
tshclient tool version >= 14.0.0, which you can download by visiting your Teleport account.tctl version
Teleport Enterprise v14.0.0 go1.21tsh version
Teleport v14.0.0 go1.21
- To check that you can connect to your Teleport cluster, sign in with
tsh login, then verify that you can run
tctlcommands 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 status
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl statuscommand, you can use your current credentials to run subsequent
tctlcommands from your workstation. If you host your own Teleport cluster, you can also run
tctlcommands 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.
We'll be using samltest.id to create a test consumer of Teleport's SAML identity provider.
First, ensure you are logged into Teleport as a user that has permissions
to read and modify
saml_idp_service_provider objects. The default
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 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
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
it in an easy to remember file name like
Navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload
Download the service provider metadata from samltest.id as
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
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 create saml-sp.yaml
SAML IdP service provider 'samltest-id' has been created.
Teleport now trusts the samltest.id service provider.
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:
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
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.