Identity provider field mappings

ThoughtFarmer allows you to map user profile fields to attributes in identity providers such as Active Directory, Azure, GSuite, and Okta. This synchronization ensures that changes made in either ThoughtFarmer or the identity provider are reflected across both platforms.

Minimum requirements

To enable integration, at a minimum, you must map the following ThoughtFarmer fields to your identity provider's attributes:

• First Name
• Last Name

Custom profile field mapping

In addition to basic fields, ThoughtFarmer supports the synchronization of custom profile fields. Once a custom field is created within ThoughtFarmer, it becomes available for mapping to any corresponding user attribute within your identity provider.

ThoughtFarmer can also sync any custom profile field with any user attribute. Once you have created the custom field in ThoughtFarmer it will be available in the dropdown when creating a new field mapping in Active Directory.

Choosing the data owner for a mapped field

The data owner can be set to either ThoughtFarmer or an identity provider on a field by field basis. For ThoughtFarmer to be the data owner of any fields, write access needs to be enabled on the specific Employee Directory Connector store page. If ThoughtFarmer is the owner of a mapped field then any changes made on a user's profile will overwrite that value in your identity provider when the profile changes are saved.

With the identity provider as the data owner, any changes users make to their profile fields within ThoughtFarmer are overwritten by the provider values whenever the synchronization task Bulk update users occurs. Because of this you may wish to make fields as the data owner non-editable by users.

An example of field mappings and data owner settings is shown further on in this document.

Create a new field mapping

1. Go to the ThoughtFarmer Admin Panel: Users & security section > Employee directory connector page.
2. Click on the Store name for which you want to create a new field mapping.
3. Click on the Field Mappings tab.
   
   
    
4. Click Add at the bottom.
5. Select the ThoughtFarmer field from the dropdown.
6. Enter the case sensitive attribute in the External store field.
7. Select ThoughtFarmer or the Identity Provider as the Data owner in the dropdown.
8. Click the Save icon on the right of the field mapping.

Note: The "External store field" column is free-text and case sensitive. If you are unsure of the exact attribute name, refer to the table of accepted attributes in this document.

Edit an existing field mapping

1. Go to the ThoughtFarmer Admin Panel: Users & security section > Employee directory connector page.
2. Click on the Store name for which you want to edit a field mapping.
3. Click on the Field Mappings tab.
4. Click the edit icon (a pencil) beside the field mapping that you want to edit.
   
   
    
5. Change the desired values
6. Click the Save icon.

Delete an existing field mapping

1. Go to the ThoughtFarmer Admin Panel: Users & security section > Employee directory connector page.
2. Click on the Store name for which you want to delete a field mapping.
3. Click on the Field Mappings tab.
4. Click the garbage can icon beside the field mapping you want to delete.

Example ThoughtFarmer fields to Active Directory attributes

The following is a list that shows an example of ThoughtFarmer profile fields and their usual mapping to Active Directory user attributes. This is just a guide. Fields can be mapped to any AD attribute you wish.

First name, Last name and Email fields do not need an explicit mapping if you are using the AD fields from the below table. However if you want to map them to a different field you will need to explicitly map them.

Example ThoughtFarmer fields to Entra ID (Azure AD) Directory attributes

The following is a list of the accepted field mappings from Entra ID:

Note: Microsoft Graph offers four types of extensions for adding custom data.

1. Extension attributes
   • Extension attributes provide an easy way to extend your Azure AD directory with additional attributes. Azure (Microsoft Entra ID) includes 15 predefined extension attributes that can be used to store values for users and devices. These attributes originated from custom attributes provided in on-premises Active Directory (AD) and Microsoft Exchange.
2. Directory (Microsoft Entra ID) extensions
   • Directory extensions allow developers to create strongly typed, discoverable, and filterable attributes for directory objects. The naming convention for directory extension attributes is "extension_" + <objectID of your placeholder application> + "_" + <name of your new property>. The exact attribute name will vary based on the application you create.
3. Schema extensions
4. Open extensions

Additional configuration settings

ThoughtFarmer’s EDC sync maps a user’s UPN to the ThoughtFarmer username field, and in instances where External/Guest users are utilized, Microsoft appends #EXT# to the UPN. For example, the userPrincipalName for the guest user john.doe@email.com would become john.doe_email.com#EXT#@tenantname.onmicrosoft.com. An optional configuration setting is available to map a user’s email address to the username.
{
  "domainGroup": "{domain_group}",
  "tenant": "{tenant_id}",
  "clientId": "{client_id}",
  "clientSecret" : "[clientSecret]",
  “setupnasusernameforazureguestusers” : "false"
}

Example ThoughtFarmer fields to Google Workspace directory attributes

The following table lists the accepted field mappings from Google:

Limitations
There is a current limitation from Google in regard to profile images, whatever the size of the photo being uploaded, the API downsizes it to 96x96 pixels.

Custom Attributes
If you wish to use custom field mappings from Google, under the ThoughtFarmer External Store Field column, the customs attribute has to be in the following format: [CustomSchemaName].[CustomAttribute].

To use custom attributes append "hasCustomSchema": "true" to your configuration.

Example:
{
"domain": "yourDomain",
"privateKey": "-----BEGIN PRIVATE KEY-----yourKeyHere-----END PRIVATE KEY-----\n",
"clientEmail": "email@yourOrganization.iam.gserviceaccount.com",
"customer": "yourCustomerValue",
"adminUser": "adminUserEmail@domain.com", "group": "yourGroupName",
"hasCustomSchema": "true"
}

Example ThoughtFarmer fields to Okta Directory attributes

Set up field mappings in ThoughtFarmer

Here you can configure which Okta profile fields should sync with which ThoughtFarmer profile fields. 

1. The ThoughtFarmer field column is the name of the ThoughtFarmer profile field. The External store field is the ThoughtFarmer field name in Okta.
2. For the Data owner column, choose your Okta external user store. 

Set up field mappings in Okta

For each field mapping in ThoughtFarmer, you'll need to set them up in Okta too. Currently, Okta does not support profile images being uploaded.

1. In Okta, go to Directory > Profile Editor.
2. Find your ThoughtFarmer application, and click Profile.
3. Click + Add Attribute and create an attribute for each ThoughtFarmer profile field in the Field Mappings tab above. Give it the same name as the profile field in ThoughtFarmer, but without spaces and special characters.
   
   
   
   
4. In Okta, click Mappings.
   
   
    
5. Click the Okta User to <name of your application> tab.
6. The Okta user profile side is where you select the profile field in Okta. The ThoughtFarmer user profile side shows the fields that Okta will map to. Select the green arrows so the field mappings can be applied on user creation and update.