SAML Attribute Mapping

Attribute mapping configures Teleport SAML Identity Provider to assert custom user attributes in SAML response. The Teleport SAML IdP supports three configurable fields for attribute mapping:

• name: Name of the outgoing attribute. Required. Name should be unique across attribute mapping.
• value: Value defined using a predicate expression, which can reference Teleport usernames, roles or traits. Required.
• name_format: SAML attribute name format. Optional. The following formats are supported:
  • unspecified: value equals to urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified. Used as a default value.
  • uri: value equals to urn:oasis:names:tc:SAML:2.0:attrname-format:uri.
  • basic: value equals to urn:oasis:names:tc:SAML:2.0:attrname-format:basic.

Attribute mapping can be configured when adding a SAML application in Teleport web UI, or with saml_idp_service_provider resource spec created with tctl create or via API.

kind: saml_idp_service_provider
metadata:
  name: example.com
spec:
  entity_id: https://example.com/saml/metadata
  acs_url: https://example.com/saml/metadata
  attribute_mapping:
  - name: username
    value: uid
  - name: firstname
    name_format: basic # optional, unspecified used as default if no value is provided.
    value: user.spec.traits.firstname
  - name: groups
    name_format: urn:oasis:names:tc:SAML:2.0:attrname-format:basic # optional, full urn format.
    value: user.spec.roles

Prerequisites

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

• The Enterprise tctl admin tool and tsh 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 run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.4
  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.
• Teleport user with permission to create a service provider resource. The preset editor role has this permission.
• If you're new to SAML, consider reviewing our SAML Identity Provider Reference before proceeding.

Predicate expressions

Attribute values are authored using predicate expressions.

When a service provider is created with attribute mapping, internally, the attribute mapping details (attribute name, name format and the corresponding value) are embedded as a SAML requested attribute elements in the service provider entity descriptor.

Then, during an SSO request, SAML assertion service extracts the expressions from the entity descriptor and passes it to the predicate expression evaluator along with the authenticated user context.

Once the expressions are evaluated, the resulting values are asserted in the SAML response under the requested attribute name.

Evaluation context

The following user attributes are available for mapping between Teleport IdP and service providers:

Given a correct and supported predicate expression, attributes will be mapped as long as the requested attributes are present in Teleport. Attribute mapping that points to a non-existent value will not be included in SAML assertion.

Predicate expressions syntax

Predicate expressions for attribute mapping are evaluated against user attributes that can be accessed using evaluation context listed above.

The supported functions and methods are listed below, along with the usage syntax and it's result, evaluated against the following reference user spec file:

# reference user spec file
kind: user
metadata:
  name: foobar
spec:
  roles:
    - access
    - editor
    - dev-ssh
  traits:
    firstname:
      - foo
    lastname:
      - BAR
    displayname:
      - foo bar
    email:
      - [email protected]
    groups:
      - okta-admin
      - dev-sso
      - dev-rdp

Methods

add

Add new value(s). Works on user.spec.roles and user.spec.traits.groups.

You can also add an entirely new value that is not available in the user spec file. E.g.:

remove

Remove value(s). Works on user.spec.roles and user.spec.traits.groups

contains

Returns boolean value for matching expression. To be used in helper functions such as ifelse. Works on user.spec.roles and user.spec.traits.groups.

Helper functions

strings.upper

Transform string to upper.

strings.lower

Transform string to lower.

strings.replaceall

Replace all matching strings.

strings.split

Split string at matching character.

ifelse

Conditionally return values. To be used in conjunction with methods such as contains.

Signature: ifelse(condition, "value to return if condition is true", "value to return if condition is false")

union

Combine values in user.spec.traits.groups and user.spec.roles.

Testing attribute mapping

test-attribute-mapping command

Attribute mapping can be tested using tctl idp saml test-attribute-mapping command. test-attribute-mapping command accepts three arguments.

• --users: user names or names of files containing user spec. Required.
• --sp: name of file containing service provider spec with attribute mapping. Required.
• --format: yaml or json. Optional. Text output by default if the flag is not provided.

E.g.: Test with user name and service provider spec file:

test with username and service provider file
tctl idp saml test-attribute-mapping --user user1 --sp sp.yml
User: user1Attribute Name Attribute Value-------------- -----------------------------firstname      foolastname       barroles          access, editor, dev-sshgroups         okta-admin, dev-sso, dev-rdp

Test with user spec file and service provider spec file:

tctl idp saml test-attribute-mapping --user user.yml --sp sp.yml

Print result in format of choice.

tctl idp saml test-attribute-mapping --user user.yml --sp sp.yml --format (json/yaml)