Customizing Mapped Fields with XCreds

Created On
Last Updated On
byDave Lebbing
You are here:

XCreds provides some options for how to use the authentication fields returned from identity providers. This is primarily used when XCreds uses one of these fields to set the user name when creating a new macOS account. Depending on your choice of IdP and your current IdP configuration, these field names may be different. XCreds establishes some defaults for these and then allows them to be customized when needed.

Confirm Fields Sent to XCreds

To customize how XCreds uses IdP fields it is important to first confirm what fields are currently being sent from the IdP to XCreds. XCreds can only use an IdP field if it is included in the authentication data it receives. The current IdP field data received can be found in the XCreds log located at /tmp/xcreds/xcreds.log. For example the IdP data may show a field named last_name or family_name. Confirm the correct field name shown in the XCreds log before using it to customize XCreds mapping preferences.

Add Claims

If there is a field used in your IdP but is not shown in the XCreds log data, it can be added by going to the IdP console. For Azure the can be done at portal.azure.com, then finding your XCreds item in App registrations, then going to Token configuration on the left navigation. There will then be buttons for Add optional claim and Add group claim. Select one of these and then choose from what is provided to add claim information.

Confirm in XCreds Log

After updating your IdP configuration, confirm the intended claim field data is being received for XCreds to use. This can be done by signing in to macOS again using XCreds and checking the XCreds log. Once the log shows data received from your IdP, it can be used to map to macOS user fields.

Customize XCreds Field Mapping with Preferences

Use the confirmed IdP field names shown in the XCreds log to set XCreds preferences with Profile Creator. In Profile Creator find any of the following preference keys and set their value to the name of the corresponding IdP field name. It may also be necessary to configure the preference for scopes. See XCreds Preferences guide for more information on setting each preference key.

  1. map_firstname
  2. map_lastname
  3. map_fullname
  4. map_username

Field Mapping Defaults and Normalization

When XCreds field mapping preferences are not customized, the app will do the following default sequence to map user name:

  1. If the claim email is defined, that is selected.
  2. If the claim unique_name is defined, that is selected.
  3. If neither of those are true, then the value in sub is selected.

After selecting the user name, it is normalized by taking the part before the “@” and replacing spaces with “_”.