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.
- For the LDAP Attribute, add a row for Surname and a row for Given-Name.
- 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.
- For the LDAP Attribute, select the field you are mapping to organization.
- 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.
- For the LDAP Attribute, select Telephone-Number.
- 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:
- Add a new rule and Select Send Group Membership as a Claim for the template.
- Locate the group that you wish to map to the role by using the Browse button.
- For Outgoing claim type, select Role.
- For Outgoing claim value, use the value specified in the user attributes table on our SAML documentation.
- Click Finish, then click Edit Rule for the rule you just created.
- 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:
- After copying the code from the rule language window, click OK to close the dialogue.
- Remove the rule and add a new rule with the Send Claims using a Custom Rule template.
- 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.
- Save the rule.
Custom role
To set a custom role, follow the steps for creating a generic role rule in section 4. Instead of agent or admin for the Outgoing claim value, use the ID of the role. 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.
8 Comments
Hello,
Are we able to map an attribute to place an agent in a certain zendesk group? I'm guessing this may be an issue because the agent role needs to be given first, but I'm curious on what's possible. I haven't seen any examples in the documentation regarding mapping an attribute for group access, just for organization.
Also, I'm guessing in order to map the agent role from an AD group, I need the agent signin switched over to SSO? I've only tried having a user sign-in via the help center, but authentication fails when I have the rule to map the role set in ADFS. Any info would be appreciated. Thanks
Hi Nathaniel,
Table 1 in the following article outlines supported user attributes for SAML SSO - unfortunately group isn't included.
Using SAML for single sign-on (Professional and Enterprise)
Regarding updating an agent's role, you're correct - in order to update their role via SSO you'll need to enable SAML SSO for agents and admins.
Hi,
how do I add the SAML attribute for light agents and group membership?
Hello John!
Since light agents are also agents, you may use this same guide for adding SAML. And for group membership, the steps are provided in this page too.
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.
Please let us know if you have any further questions.
Hi Shera!
What parameters do I use for the custom rule for the light agents?
Does the light agent still have the role (the claim) "agent" as the normal agents, or should they only have this custom rule?
And what parameters do I use for the custom rule for the group membership?
Hello John,
I'm so sorry for the delay in my response, for the custom rule you may set up with the attribute: Role=Agent and Custom_role:{{custom_role_unique_id}}.
I hope this helps!
Hi Shera!
I found the custom_role_unique_id with the api (https://developer.zendesk.com/rest_api/docs/support/custom_roles), and it works if the user is already registered as an light agent. But if the user doesn't exist or is already registered as a end user the login fails (the user is just logged out again).
The custom_role_id claim is after the role claim in the ADFS config.
Shouldn't the user be able to be created when the user logs in for the first time?
Hey John,
Do you have the user already set up in your ADFS config as a light-agent? I believe as long as they are set up correctly there, once they attempt to log in they should be created as a light-agent in the Support account.
Let me know if that's still not working after checking your ADFS config and I can create a ticket on your behalf.
Thanks!
Please sign in to leave a comment.