Teleport
Teleport as a SAML identity provider
- Version 16.x
- Version 15.x
- Version 14.x
- Version 13.x
- Older Versions
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 cluster. If you want to get started with Teleport, sign up for a free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 15.2.4, which you can download from your Teleport account workspace or the Teleport Enterprise Cloud Downloads page.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials.tctl
is supported on macOS and Linux machines. 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 15.2.4
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.
- User with permission to create service provider resource. The preset
editor
role has this permission. - SAML application (also known as a SAML service provider or SP) for testing. For this guide, we'll be using samltest.id as a service provider for Teleport's SAML IdP.
Step 1/3. Add a service provider to Teleport
The minimum configuration values required to add a service provider are:
- Entity ID: The SAML metadata endpoint of the service provider.
- ACS URL: The endpoint where users will be redirected after SAML authentication. ACS URL is also referred to as SAML SSO URL.
The following saml_idp_service_provider
spec is a reference for adding samltest.id to Teleport:
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:
# entity_id is the metadata endpoint of service provider
# that serves entity descriptor, aka SP metadata.
entity_id: https://samltest.id/saml/sp
# acs_url is the endpoint where users will be redirected after
# SAML authentication.
acs_url: https://samltest.id/idp/profile/SAML2/POST/SSO
version: v1
Add the spec to Teleport using tctl
:
tctl create saml-sp.yamlSAML IdP service provider 'samltest-id' has been created.
The above configuration shows creating service provider without an entity descriptor.
In this scenario, Teleport first tries to fetch an entity descriptor by querying the entity_id
endpoint.
If an entity descriptor is not found at that endpoint, Teleport will generate
a new entity descriptor with the given entity_id
and acs_url
values.
If you need more control over the entity descriptor, you may also add it directly
to the saml_idp_service_provider
spec.
First 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.
If an entity descriptor is provided, it's content takes preference over values provided in entity_id
and acs_url
.
Teleport only tries to fetch or generate entity descriptor when service provider is created for the first time. Subsequent updates require an entity descriptor to be present in the service provider spec. As such, when updating service provider, you should first fetch the spec that is stored in Teleport and only then edit the configuration.
get service provider spec
tctl get saml_idp_service_provider/<service provider name> > service-provider.yml
Step 2/3. Configure the service provider to recognize Teleport's SAML IdP
First, obtain your Teleport SAML IdP metadata by navigating to https://<proxy-address>/enterprise/saml-idp/metadata
.
Save it in an easy to remember file name like teleport-metadata.xml
.
Now navigate to https://samltest.id and click on "Upload Metadata." Next, choose to upload
teleport-metadata.xml
.
Step 3/3. 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.
Optional: Creating dedicated role to manage service provider
For production, we recommend creating a dedicated role to manage service provider.
To create a dedicated role, 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
Next, add the role to your user.
Assign the sp-manager
role to your Teleport user by running the appropriate
commands for your authentication provider:
-
Retrieve your local user's roles as a comma-separated list:
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') -
Edit your local user to add the new role:
tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},sp-manager" -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingsp-manager
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - sp-manager
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingsp-manager
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - sp-manager
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingsp-manager
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - sp-manager
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.