Configure custom SAML attribute mappings

Configure custom attribute mappings to use SSO with an identity provider (IdP) that sends SAML attributes under names you cannot change. Kobiton translates your IdP’s attribute names into the names it expects before it processes each sign-in, so SSO works without changes to your IdP.

How custom attribute mappings work

Kobiton reads five attributes from the SAML assertion your IdP sends at sign-in:

Platform attribute Purpose

email

The user’s email address, used to match their Kobiton account.

firstName

The user’s first name.

lastName

The user’s last name.

phoneNumber

The user’s phone number.

memberOf

The groups the user belongs to, used for role mapping.

By default, Kobiton expects your IdP to send each attribute under these exact names. When your IdP sends them under different names, sign-in fails.

Custom attribute mappings let you tell Kobiton which name your IdP uses for each attribute. At the next sign-in, Kobiton renames the matching attributes in the assertion to its expected names before it validates the assertion. The rest of SSO validation is unchanged.

Before you start

  • You have administrator access to your organization’s SSO settings in Kobiton.

  • You have completed the SSO setup for your IdP. See About Single Sign-On (SSO) authentication.

  • You know the exact attribute names your IdP sends in the SAML assertion.

Turn on custom attribute mappings

  1. Open your organization settings and choose SSO Settings.

  2. Go to the User attributes (or parameters) section.

    By default, Custom attribute mappings is off, and Kobiton shows the five attribute names as a read-only list with Copy buttons.

    User attributes section with Custom attribute mappings turned off, showing the read-only attribute names with Copy buttons

  3. Turn on Custom attribute mappings.

    The read-only attribute list is replaced by a mapping table. Each row pairs a fixed Platform Attribute with an editable field where you enter the name your IdP uses.

    User attributes section with Custom attribute mappings turned on, showing the two-column Platform Attribute and Your IdP’s Attribute Name mapping table

  4. For each platform attribute, enter the attribute name your IdP sends. Match the name your IdP uses exactly.

    The following special characters are not supported in an IdP attribute name: . (period), [ (opening bracket), and ] (closing bracket). Make sure the attribute name you enter does not contain these characters.

  5. Save your SSO settings.

The mappings apply the next time a user signs in through SSO.

To stop using custom attribute mappings, turn off Custom attribute mappings and save. The section returns to the read-only attribute list, and Kobiton expects the default attribute names again.

How Kobiton applies your mappings

  • Empty fields use the default name. If you leave a row blank, Kobiton uses the platform attribute name for that attribute.

  • Unmapped attributes pass through. Attributes your IdP sends that are not in the mapping are ignored, and other attributes are read under their original names.

  • Duplicate names are not allowed. If you enter the same IdP attribute name for two platform attributes, Kobiton shows an error on the affected rows and blocks the save until you resolve it.

  • Empty mappings prompt a warning. If you turn on custom attribute mappings but leave every field blank, Kobiton warns you before saving that SSO will use the default attribute names. You can still save.

  • Some special characters are not supported. An IdP attribute name must not contain . (period), [ (opening bracket), or ] (closing bracket).

Limitations

  • Custom attribute mappings change only the names Kobiton reads attributes under. They do not change attribute values.

  • Conditional mapping, such as choosing a name based on another condition, is not supported.

  • Turning off custom attribute mappings does not change any other SSO setting.

Related guides