Skip to main content
Version: 18.x (unreleased)

SAML Identity Provider Reference

Report an issue with this page

This page provides details on the SAML identity provider available in Teleport.

What is the SAML identity provider?​

The SAML identity provider allows Teleport users to authenticate and authorize to external applications, both inside and outside of Teleport, that support SAML Single Sign-On.

Basic definitions​

The following definitions are paraphrased and summarized from OASIS's SAML specification documents, referenced at the bottom of this page.

Assertions​

A package of information that supplies zero or more statements made by an identity provider. Assertions are usually made about a subject, which in Teleport's case will be Teleport users. These can be viewed as statements of fact about a user, e.g. "user bob belongs to roles editor, access."

Service Provider​

A service provider can make use of assertions about a subject in order to control access and provide customized service. They rely on the identity provider for these assertions. In Teleport's case, service providers are typically applications like Slack, Vercel, etc. that allow SAML Single Sign-On.

Identity Provider​

A service that makes assertions about a subject.

Service/identity provider initiated SSO​

The login process can be initiated by either the service provider or the identity provider. The processes to trigger either of these are subtly different. The service provider is responsible for initiating the SSO process for service provider initiated SSO. The identity provider is responsible for initiating the process for identity provider initiated SSO.

Endpoints​

Metadata URL​

https://<proxy-address>/enterprise/saml-idp/metadata

This is the URL where the identity provider XML metadata can be retrieved from. Service providers will require information from this file to establish the trust between the service provider and identity provider.

Single Sign-On Service URL​

https://<proxy-address>/enterprise/saml-idp/sso

This is the URL that service providers will use to exchange assertions with the identity provider. This URL supports the following bindings:

  • HTTP-Redirect
  • HTTP-POST

Identity provider initiated SSO URL​

https://<proxy-address>/enterprise/saml-idp/login/<sp-name>

This URL triggers identity provider initiated SSO. sp-name matches the metadata.name of the service provider object for a particular service provider.

Teleport SAML service provider object​

Below is a service provider object. These objects must be added to Teleport in order for Teleport to trust external service providers.

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: saml-service-provider
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

Assertions​

The assertions currently provided by Teleport's SAML identity provider are listed below.

Friendly nameFull nameDescriptionFormat
uidurn:oid:0.9.2342.19200300.100.1.1The user ID from Teleporturn:oasis:names:tc:SAML:2.0:attrname-format:uri
eduPersonAffiliationurn:oid:1.3.6.1.4.1.5923.1.1.1.1The user's Teleport rolesurn:oasis:names:tc:SAML:2.0:attrname-format:uri

RBAC​

In role version 7 and below, the following access controls are applied to the saml_idp_service_provider resource access:

  • Role option that enables idp: spec.options.idp.saml.enabled: true/false.
  • Cluster auth preference that enables idp: spec.idp.saml.enabled: true/false.
  • Resource rule spec.allow/deny.rules.resources.saml_idp_service_provider. Applicable only to admin actions.
    • Allow rule with read,list verbs are applied implicitly.
    • Deny rule with read,list verbs gets precedence over implicit allow.
  • Per session MFA: spec.options.require_session_mfa: true/false.

Teleport role version 8 introduces the following changes:

  • Label matchers based on app_labels.
  • Resource rule with verbs targeting saml_idp_service_provider is now applicable to both resource access and admin actions.
  • Device Trust for SAML IdP session.

The role option spec.options.idp.saml.enabled: true/false is no longer supported starting role version 8.

Per session MFA is supported in all role versions.

RBAC precedence​

Users can be assigned with both the newer role (version 8) and the older versioned roles (version 7 and below) at the same time. If a user is assigned with both role version 7 and 8, deny rules of the version 8 takes precedence.

For example,

  • If role version 7 denies access, access is denied.
  • If role version 7 allows access but role version 8 denies access, access is denied.
  • If role version 7 allows access and role version 8 also allows access, access is allowed.

The table below shows a few more examples of applicable RBAC, when two roles with version 7 and 8 each are assigned to the user.

Role v7Role v8Result
options:
  idp:
    saml:
      enabled: false
allow:
  app_labels:
    * : *
❌ no access.
options:
  idp:
    saml:
      enabled: true
deny:
  app_labels:
     * : *
❌ no access
options:
  idp:
    saml:
      enabled: true
allow:
  app_labels:
    * : *
deny:
  rules:
    resources:
    - saml_idp_service_provider
    verbs:
    - read
    - list
❌ no access
options:
  idp:
    saml:
      enabled: true
allow:
  app_labels:
    * : *
✅ full access
No version 7 role assigned to the user
allow:
  app_labels:
    * : *
✅ full access
options:
  idp:
    saml:
      enabled: true
No version 8 role assigned to the user✅ full access
Admin Actions

saml_idp_service_provider resource does not yet support MFA and Device Trust for admin actions.

Disabling SAML identity provider at cluster level​

To disable access to the identity provider at the cluster level, create or update the cluster_auth_preference object with the following setting:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  ...
  idp:
    saml:
      enabled: false
  ...
version: v2

This will disable access to the SAML identity provider for all users regardless of their role level permissions.

Troubleshooting​

Bad Request when logging into an external application​

If the Teleport server returns a Bad Request the service provider metadata may not have been added properly to Teleport and, as a result, Teleport is unable to find the service provider. You can verify this by looking for a log entry in Teleport's logs:

2023-03-01T10:32:34-05:00 INFO [SAMLIDP]   failed to validate request: cannot find service provider https://samltest.id/saml/sp: could not find service provider https://samltest.id/saml/sp pid:31036.1 saml@v0.4.12/identity_provider.go:232

References​