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

SSO with Active Directory Federation Services

Report an issue with this page

This guide will explain how to configure Active Directory Federation Services (ADFS) to be a single sign-on (SSO) provider to issue login credentials to specific groups of users. When used in combination with role based access control (RBAC), it allows Teleport administrators to define policies like:

  • Only members of "DBA" group can SSH into machines running PostgreSQL.
  • Developers must never SSH into production servers.

How it works​

You can register your Teleport cluster as an application with ADFS, then create an authentication connector resource that provides Teleport with information about your application. When a user signs in to Teleport, ADFS executes its own authentication flow, then sends an HTTP request to your Teleport cluster to indicate that authentication has completed.

Teleport authenticates users to your infrastructure by issuing short-lived certificates. After a user completes an SSO authentication flow, Teleport issues short-lived TLS and SSH certificates to the user. Teleport also creates a temporary user on the Auth Service backend.

Teleport roles are encoded in the user's certificates. To assign Teleport roles to the user, the Auth Service inspects the role mapping within the authentication connector, which associates user data on ADFS with the names of one or more Teleport roles.

Prerequisites​

  • ADFS installation with Admin access and users assigned to at least two groups.
  • Teleport role with access to maintaining saml resources. This is available in the default editor role.

  • A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.0.0-dev
    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.

Step 1/3. Configure ADFS​

You'll need to configure ADFS to export claims about a user (Claims Provider Trust in ADFS terminology) and you'll need to configure ADFS to trust Teleport (a Relying Party Trust in ADFS terminology).

For Claims Provider Trust configuration, open the AD FS management window. Under Claims Provider Trusts, right-click on Active Directory and select Edit Claim Rules. You'll need to specify at least the following two incoming claims: Name ID and Group.

  • Name ID should be a mapping of the LDAP Attribute E-Mail-Addresses to Name ID.

  • A group membership claim should be used to map users to roles (for example to separate normal users and admins).

  • If you are using dynamic roles (see below), it may be useful to map the LDAP Attribute SAM-Account-Name to Windows account name:

  • And create another mapping of E-Mail-Addresses to UPN:

You'll also need to create a Relying Party Trust. Use the below information to help guide you through the Wizard.

  • Create a Relaying Party Trust:
  • Enter data about the relying party manually.
  • Set the display name to something along the lines of Teleport.
  • Skip the token encryption certificate.
  • Select "Enable support for SAML 2.0 Web SSO protocol" and set the URL to https://teleport.example.com/v1/webapi/saml/acs, replacing the domain name with your Teleport Proxy Service URL. If you have a self-hosted cluster with multiple public addresses for the Teleport Proxy Service (the value of proxy_service.public_addr in the Teleport configuration file), ensure that this address points to the first one listed.
  • Set the relying party trust identifier to https://teleport.example.com/v1/webapi/saml/acs as well.
  • For access control policy select "Permit everyone".

Once the Relying Party Trust has been created, update the Claim Issuance Policy for it. Like before, make sure you send at least Name ID and Group claims to the relying party (Teleport). If you are using dynamic roles, it may be useful to map the LDAP Attribute SAM-Account-Name to "Windows account name" and create another mapping of E-Mail-Addresses to "UPN".

Lastly, ensure the user you create in Active Directory has an email address associated with it. To check this open Server Manager then "Tools -> Active Directory Users and Computers" and select the user and right click and open properties. Make sure the email address field is filled out.

Step 2/3. Connect ADFS to Teleport​

In this section, you will create an authentication connector that provides Teleport with the information it needs to exchange SAML messages with ADFS and issue certificates to users.

Assign a role mapping​

When a user authenticates to Teleport, the Teleport Auth Service issues SSH and TLS certificates to the user that contain the user's Teleport roles.

For SSO authentication connectors, the Auth Service determines which roles to encode in the certificate by reading the authentication connector's role mapping. The role mapping indicates which Teleport roles to assign based on data that your identity provider stores about the user.

When you configure an authentication connector using the tctl CLI, a role mapping takes the following format:

<attribute_name>,<attribute_value>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

For example, the following role mapping means that any user with the attribute group with the value admin receives the Teleport roles editor and auditor:

group,admin,editor,auditor

For the purpose of this guide, assign two separate role mappings:

  • A more permissive role mapping: group,admins,auditor,editor
  • A more restrictive role mapping: group,users,access

Make sure that, in your role mapping, each attribute begins with the following namespace prefix:

http://schemas.xmlsoap.org/claims/

Configure a SAML connector​

Create a SAML connector resource using tctl:

tctl sso configure saml --acs https://teleport.example.com/v1/webapi/saml/acs \  --preset adfs \  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \  --attributes-to-roles mapping_1 \  --attributes-to-roles mapping_2  \  > adfs.yaml

The --attributes-to-roles flag contains the role mapping you assigned earlier.

The acs field should match the value you set in ADFS earlier and you can obtain the entity_descriptor_url from ADFS under "ADFS -> Service -> Endpoints -> Metadata".

Export the signing key​

For the last step, you'll need to export the signing key:

tctl saml export adfs > saml.cer

Copy saml.cer, to ADFS server, open the "Relying Party Trust" and add this file as one of the signature verification certificates:

The Web UI will now contain a new button: "Login with MS Active Directory". The CLI is the same as before:

tsh --proxy=proxy.example.com login

This command will print the SSO login URL and try to open it automatically in a browser.

Tip

Teleport can use multiple SAML connectors. In this case a connector name can be passed via tsh login --auth=connector_name

Test the connector​

Run the following command to test your connector:

tctl sso test < adfs.yaml

Create the connector​

Apply the connector:

tctl create -f adfs.yaml

Step 3/3. Configure authentication preferences​

Edit your cluster authentication preferences so you can make the authentication connector you configured in this guide the default authentication method for your Teleport cluster.

Open the Teleport Web UI. From the left sidebar, navigate to Zero Trust Access > Auth Connectors. Find the connector you would like to make the default and, from its three-dot menu, select Set as default.

If you are managing your Teleport resources as configuration files, you can choose a default authentication connector using a dynamic resource. In this case, use tctl to edit the cluster_auth_preference value:

tctl edit cluster_auth_preference

Set the value of spec.type to saml:

kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  type: saml
  ...
version: v2

After you save and exit the editor, tctl will update the resource:

cluster auth preference has been updated
Additional ways to edit cluster auth preferences

The cluster auth preference is available as a Teleport Terraform provider resource. Find a list of configuration options in the Cluster Auth Preferences Resource Reference.

If you self-host Teleport, you can edit your Teleport Auth Service configuration file to include the following:

# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: saml

If you need to log in again before configuring your identity provider, use the flag --auth=local.

Next steps​

Now that you have connected Teleport to your identity provider, you can customize the way Teleport includes IdP data in Teleport roles.

With role templates, you can include user data from your IdP directly in Teleport roles. If you use the external template variable in the value of a role field, Teleport passes that value from your IdP. In this example, all of the role options you can use for allowing users to assume certain principals on remote systems come from your IdP:

kind: role
version: v7
metadata:
  name: sso-users
spec:
  allow:
    logins: ['{{external.logins}}']
    aws_role_arns: ['{{external.aws_role_arns}}']
    azure_identities: ['{{external.azure_identities}}']
    db_names: ['{{external.db_names}}']
    db_roles: ['{{external.db_roles}}']
    db_users: ['{{external.db_users}}']
    desktop_groups: ['{{external.desktop_groups}}']
    gcp_service_accounts: ['{{external.gcp_service_accounts}}']
    host_groups: ['{{external.host_groups}}']
    host_sudoers: ['{{external.host_sudoers}}']
    kubernetes_groups: ['{{external.kubernetes_groups}}']
    kubernetes_users: ['{{external.kubernetes_users}}']
    windows_desktop_logins: ['{{external.windows_desktop_logins}}']

For more information on using the external template variable, see Role Templates.

For an explanation of the fields listed above, see the Role Reference.

If you need to transform your IdP user data before you include it in Teleport roles, you can do so using Login Rules. Login Rules allow you to include external traits within Teleport roles even if your IdP provides user data in a different format than the one expected by Teleport. Read more about Login Rules.

Troubleshooting​

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

  • Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
  • Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
  • For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS certificates are configured properly for both the Teleport Proxy Service and the SSO provider.

If something is not working, we recommend to:

  • Double-check the host names, tokens and TCP ports in a connector definition.

Using the Web UI​

If you get "access denied" or other login errors, the number one place to check is the Audit Log. To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "code": "T1001W",
  "error": "role clusteradmin is not found",
  "event": "user.login",
  "message": "Failed to calculate user attributes.\n\trole clusteradmin is not found",
  "method": "oidc",
  "success": false,
  "time": "2024-11-07T15:41:25.584Z",
  "uid": "71e46f17-d611-48bb-bf5e-effd90016c13"
}

Teleport does not show the expected Nodes​

When the Teleport Auth Service receives a request to list Teleport-connected resources (e.g., to display resources in the Web UI or via tsh ls), it only returns the resources that the current user is authorized to view.

For each resource in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the resource from the user:

  • None of the user's roles contain a deny rule that matches the resource's labels.
  • At least one of the user's roles contains an allow rule that matches the resource's labels.

If you are not seeing resources when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Access Controls Reference.

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

kind: role
metadata:
  name: example-role
spec:
  allow:
    logins: ['{{external.logins}}', ubuntu, debian]
    node_labels:
      'env': 'dev'
version: v5

Single sign-on fails with OIDC​

When encountering the error message "Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys", it typically indicates a discrepancy between the algorithm used to sign the JWT token and the algorithm(s) supported by the JSON Web Key Set (JWKS). Specifically, the token might be signed with one algorithm, e.g., HS256, while the JWKS only lists keys for a different algorithm. e.g., RS256. This issue predominantly arises when using identity providers that offer extremely low-level functionality.

Here are some things to check:

  • Verify the JWT header specifies the correct signing algorithm. This should match one of the algorithms listed in the keys section of the JWKS endpoint response.
  • Ensure the JWKS endpoint is returning all relevant public keys. Sometimes key rotation can cause valid keys to be omitted.

To resolve the issue, align the JWT algorithm header with a supported algorithm in the JWKS. Rotate keys if necessary. Verify the JWKS only publishes the active public keys. With proper configuration, the signature should validate successfully.