Teleport 16: Advancing Infrastructure Defense in Depth with Device Trust, MFA, and VNET
Jul 25
Register Today
Teleport logoTry For Free
Fork me on GitHub


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
  - 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


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

  • The tctl admin tool and tsh client tool version >= 16.0.4.

    Visit Installation for instructions on downloading tctl and tsh.

  • 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 --user=[email protected]
    tctl status


    Version 16.0.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:

Usernameuid or
RoleseduPersonAffiliation or user.spec.roles.
Traitsuser.spec.traits.firstname, user.spec.traits.groups etc.

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
  name: foobar
    - access
    - editor
    - dev-ssh
      - foo
      - BAR
      - foo bar
      - [email protected]
      - okta-admin
      - dev-sso
      - dev-rdp



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

user.spec.roles.add("staging-ssh")access, editor, dev-ssh, staging-ssh

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

set().add("prod-ssh") or set("prod-ssh")prod-ssh


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

user.spec.roles.remove("editor", "access")dev-ssh


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


Transform string to upper.



Transform string to lower.



Replace all matching strings.

strings.replaceall(user.spec.traits.groups, "-", "+")okta+admin, dev+sso, dev+rdp
strings.replaceall(user.spec.traits.groups, "admin", "dev")okta-dev, dev-sso, dev-rdp


Split string at matching character.

strings.split(user.spec.traits.groups, "-")okta, admin, dev, sso, rdp


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")

ifelse(user.spec.traits.groups.contains("okta-admin"), user.spec.traits.groups.add("new group"), user.spec.traits.groups)okta-admin, dev-sso, dev-rdp, new group


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

union(user.spec.traits.groups, user.spec.roles)okta-admin, dev-sso, dev-rdp, access, editor, dev-ssh
union(user.spec.traits.groups.remove("okta-admin"), user.spec.roles)dev-sso, dev-rdp, access, editor, dev-ssh

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)