Mapping attributes from Active Directory with ADFS and SAML

What's my plan?

Suite

Any plan

Support

Any plan

89304293

Disclaimer: This article is provided for instructional purposes only. Zendesk does not support or guarantee the code. Post any issues you have in the comments section or try searching for a solution online.

When using SAML login with ADFS, you can pass other values in addition to the authentication values. This article describes how to pass a user's full name, organization, phone number, role, or custom role.

These values are defined as Claim Rules in the Relying Party Trust. To edit the Claim Rules, select the Relying Party Trusts folder from AD FS Management, and choose Edit Claim Rules from the Actions sidebar. New rules are added by clicking Add Rule and then selecting a template from the window that pops up. Example:

Full name

To pass the full name of a user, create a rule with the Send LDAP Attributes template.

1. For the LDAP Attribute, add a row for Surname and a row for Given-Name.
2. For the Outgoing Claim Type, select Surname and Given Name.

Organization

To define the organization that a user will be associated with in Zendesk, create a rule with the Send LDAP Attributes template. This rule will map a field in Active Directory to the outgoing claim type of organization. The LDAP attribute will depend on how you wish to map users. For example, you might want to map departments to different organizations.

1. For the LDAP Attribute, select the field you are mapping to organization.
2. For the Outgoing Claim Type, type the word organization in lowercase in the field.
   
   

Phone number

To pass the phone number of a user, create a rule with the Send LDAP Attributes template.

1. For the LDAP Attribute, select Telephone-Number.
2. For the Outgoing Claim Type, type the word phone in lowercase in the field.

Role

Setting the role of a user based on their membership in a group is a two-step process. First, you create a new rule using the Send Group Membership as a Claim template. Second, you modify the definition generated by that rule slightly to create a custom rule that correctly passes the information to Zendesk.

To create the group membership rule:

1. Add a new rule and Select Send Group Membership as a Claim for the template.
2. Locate the group that you wish to map to the role by using the Browse button.
   
3. For Outgoing claim type, select Role.
   
4. For Outgoing claim value, use the value specified in the user attributes table on our SAML documentation.
5. Click Finish, then click Edit Rule for the rule you just created.
6. Use the View Rule Language button to get the raw code for the rule. Copy the code somewhere. You'll use it in the next step.
   

To create the functioning custom rule:

1. After copying the code from the rule language window, click OK to close the dialogue.
2. Remove the rule and add a new rule with the Send Claims using a Custom Rule template.
3. Paste the code you copied into the custom rule editor, and then delete the "http://schemas.microsoft.com/ws/2008/06/identity/claims/" string from the Type field. This should leave only the word role.
   
4. Save the rule.

Custom role

To set a custom role, you'll need to use the Custom Agent Roles API to get the ID. Then follow the steps for creating a generic role rule in section 4, with the following modifications:

• Instead of agent or admin for the Outgoing claim value, use the role's ID.
• Instead of leaving the word role in the Type field, change the value to custom_role_id.

The last statement of the rule will look something like this:

issue(Type = "custom_role_id", Value = "ROLE_ID_HERE", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

Custom role mapping will only work if the user already has a role of agent.