Custom attribute map rules

Sometimes, you can't directly map values in your SAML attribute map.

This most often occurs with:

• Groups, either because the IdP doesn't have groups, or the groups the IdP has aren't relevant to KnowledgeOwl.
• Custom fields that have a different value/meaning in your IdP and need to be "translated" to a different value in KnowledgeOwl.

In these situations, it can be useful to define a rule that will look at some attribute coming from the IdP and then update a KnowledgeOwl field based on that rule. We call these Custom attribute map rules. In the app, they're listed under Custom rules in the Map reader attributes step.

There are two things to keep in mind when working with custom attribute map rules:

• The SAML attribute map always overrides custom attribute mappings.
  This means that you can't, for example, have a SAML attribute map entry for the Reader groups field and also have a custom attribute map rule that sets the Reader groups field. The SAML attribute mapping always overrides the custom mapping. If you're going to set a field using a custom attribute map rule, it's best to leave the SAML attribute map for that field blank. If you do map it, the rule displays a warning that "{field} is also mapped above, so the mapped value always replaces this rule's."
• At this time, only one rule can be applied to a specific reader/attribute combination.
  If you have five rules for what happens with the groups field, only the first rule that is a match will be applied for a given reader, even if a reader technically matches all five rules. Rules are checked in the order they're listed, oldest first. If an earlier rule sets the same field, the later rule displays a warning explaining when it applies.

We offer three types of custom attribute map rules:

1. Default: The simplest of rules, the default rule will check to see if a specified IdP attribute is present at all and will set a reader field when it is. It does not care what the actual value of the IdP attribute is.
2. Exact matches: These will look for an exact match for an attribute value coming from the IdP and set a reader field only when it finds that exact match.
3. Regex pattern: The most flexible and complex rule. Define a regular expression (regex) pattern to match an IdP value and set a reader field accordingly. We use the PHP flavor of regex.

Where to find custom rules

To view, add, edit, or delete rules:

1. Go to Security and access > Access & SSO.
2. In the Login methods card, select Set up or Manage next to SAML.
3. Expand step 3, Map reader attributes.
4. Below the attribute map, find Custom rules. If you don't have any rules yet, select Set reader fields with rules to show them.

Each rule is listed as IF the IdP attribute and condition, THEN the reader field and value it sets. Use the pencil icon to edit a rule or the trash icon to delete it. Creating, editing, and deleting rules saves right away, so you don't need to select Save changes.

Default rules

Default rules are our simplest rule. The rule basically says: if an incoming IdP attribute has any value, set the selected KnowledgeOwl field for the reader.

It doesn't matter what the value of the attribute actually is.

You can only set one default rule per IdP attribute name (so, for example, you can't have two default rules that both checked the custom1 attribute coming from your IdP).

Default rules display as IF attribute is present.

Use case

Default rules are a fantastic choice if you want to assign all readers to one or more reader groups, or set one of the custom fields to be the same value for all SSO readers.

Setup

To create a default rule:

1. In Custom rules, select Add rule. The Create custom map rule modal opens for you to define the rule:
   The Create custom map rule modal
2. Enter the IdP attribute name you'd like to base the rule on. This should be formatted exactly as it appears in the IdP.
   • If you're not sure of the attribute name, review your IdP settings or turn on Debug mode in step 4, Test login, save, and try to log in. Then select Load last login attempt to see the list of the attributes coming from the IdP.
   • For a default rule you'd like applied to all readers coming in through SSO, use any attribute that is always populated from your IdP. Email address, username or user ID, first name, or last name are often good candidates.
3. Select Default as the Value matching type.
4. Use the Reader attribute dropdown to select the reader field you'd like to update based on this rule.
5. Add the Reader attribute value you'd like that reader attribute set to. If you selected Reader groups, select the groups in Assign to reader groups instead.
6. Select Create rule to create and save the rule.

Once created, you can view, edit, and delete the rule in the Custom rules section.

Example

To set all of your incoming SSO readers to a single group, you can match against an IdP attribute which is always populated, such as the userID or email address.

In our SAML attribute map, we've mapped these fields:

• SSO ID: uid
• Username / email: email
• First name: firstName
• Last name: lastName

We set up our default Custom attribute map rule using these settings:

• IdP attribute name: uid
• Value matching type: Default
• Reader attribute: Reader groups
• Assign to reader groups: Production, Support

Once saved, the rule displays as "IF uid is present THEN Reader groups = Production, Support".

With this rule in place, every reader who logs in will be assigned to the Production and Support Reader Groups.

Exact matches rules

With exact match rules, you define the incoming IdP attribute the rule should examine as well as a specific value it should match. If the exact value is matched when a reader authenticates, it will set a reader field based on the rule.

Exact match rules display as IF attribute is value. If you add multiple exact matches, they're joined with "or", for example: "IF country is US or USA or United States of America".

Use case

The exact match rule is useful when you have a specific attribute value in your IdP that you'd like to transform into a different value in KnowledgeOwl.

For example, maybe your company operates in five offices in three countries and your IdP captures an office attribute for each employee.

But in your knowledge base, you don't care about offices. You have a reader group for each country only.

You can set up an exact match rule for the offices of each country to map your readers to those groups:

• office attributes: Colorado or New York = US employees reader group
• office attributes: London or Manchester = UK employees reader group
• office attribute: Melbourne = Australia employees reader group

Setup

To create an exact match rule:

1. In Custom rules, select Add rule. The Create custom map rule modal opens for you to define the rule.
2. Enter the IdP attribute name you'd like to base the rule on. This should be formatted exactly as it appears in the IdP.
   • If you're not sure of the attribute name, review your IdP settings or turn on Debug mode in step 4, Test login, save, and try to log in. Then select Load last login attempt to see the list of the attributes coming from the IdP.
3. Select Exact matches as the Value matching type (this is selected by default for new rules).
4. Enter the exact value of the incoming attribute you'd like to match against in Exact match values.
5. If you'd like to look for multiple values to match against, select Add value to add additional values for this rule.
   • Multiple values will be treated as OR values--the exact match will match for the first value OR the second value OR the third value, etc.
6. Use the Reader attribute dropdown to select the reader field you'd like to update based on this rule.
7. Enter the Reader attribute value you'd like that reader attribute set to. If you selected Reader groups, select the groups in Assign to reader groups instead.
8. Select Create rule.

Once created, you can view, edit, and delete the rule in the Custom rules section.

Example

Let's say our company operates in five offices:

• Denver, Colorado
• New York, New York
• London, England
• Manchester, England
• Melbourne, Australia

We've set up reader groups in our knowledge base for each country:

• US employees
• UK employees
• AUS employees

An employee can only belong to one office, and our IdP tracks this information for each employee in an "office" field.

We want to set up a rule that will check that office field and then assign readers to the appropriate country employee group.

In our SAML attribute map, we've mapped these fields:

• SSO ID: uid
• Username / email: email
• First name: firstName
• Last name: lastName

We set up our first Custom attribute map rule using these settings:

• IdP attribute name: office
• Value matching type: Exact matches
• Exact match values: Denver, New York
• Reader attribute: Reader groups
• Assign to reader groups: US employees

And created second and third rules for our UK employees and AUS employees.

Once saved, the rules display as:

• "IF office is Denver or New York THEN Reader groups = US employees".
• "IF office is London or Manchester THEN Reader groups = UK employees".
• "IF office is Melbourne THEN Reader groups = AUS employees".

With these rules in place, every reader who logs in with an office in Melbourne will be assigned to the AUS employees reader group; every reader who logs in with an office of either London or Manchester will be assigned to the UK employees reader group, and every reader who logs in with an office of either Denver or New York will be assigned to the US employees reader group.

Because each of these rules sets Reader groups, the second and third rules display the warning "An earlier rule also sets Reader groups. This rule only applies when that one doesn't match." That's expected here, since an employee can only belong to one office.

Regex pattern rules

Regex rules are the most complicated but also the most flexible. Regex is a common abbreviation of 'regular expressions'. Regular expressions are "a sequence of characters that specifies a search pattern. Usually such patterns are used by string-searching algorithms for "find" or "find and replace" operations on strings, or for input validation." (from Wikipedia - Regular expression).

For regex custom attribute map rules, you define a regex pattern you'd like to search for and then define the KnowledgeOwl field and value you'd like to set when that pattern is found.

We recommend only using these rules when neither of the other custom rule types will meet your needs, as they are a bit harder to write and more intimidating if you're not familiar with regex. If an attribute you'd like to use is an array containing a list of values, you must use regex to properly search and match within that list.

Regex pattern rules display as IF attribute matches /pattern/i, for example: "IF custom1 matches /Brie/i THEN Custom field 2 = Cheese lover".

Use case

Regex pattern rules are useful when there are patterns within one of your IdP attributes that doing exact matches for might be tedious. For example, if all our internal IdP groups are prefixed with KO_ and all of our contractor or customer IdP groups are prefixed with EXT_, and we really only care about this KO/not-KO distinction, a regex rule makes more sense than generating very large exact match rule lists.

Refer to Auto-Assign Groups By Email Rules (SSO Edition) for a walkthrough on how to set up a rule to auto-assign everyone at a given email domain to one or more reader groups.

Setup

To create a regex pattern rule:

1. In Custom rules, select Add rule. The Create custom map rule modal opens for you to define the rule.
2. Enter the IdP attribute name you'd like to base the rule on. This should be formatted exactly as it appears in the IdP.
   • If you're not sure of the attribute name, review your IdP settings or turn on Debug mode in step 4, Test login, save, and try to log in. Then select Load last login attempt to see the list of the attributes coming from the IdP.
3. Select Regex pattern as the Value matching type.
4. Add the regex pattern you'd like to match that attribute value against in Regex pattern.
5. Use the Reader attribute dropdown to select the reader field you'd like to update based on this rule.
6. Add the Reader attribute value you'd like that reader attribute set to. If you selected Reader groups, select the groups in Assign to reader groups instead.
7. Select Create rule.

Once created, you can view, edit, and delete the rule in the Custom rules section.

Example

Let's say the KnowledgeOwl IdP is used for authenticating KnowledgeOwl employees as well as KnowledgeOwl customers. Our employees might be segmented into different groups, like:

• KO_Support
• KO_Security
• KO_Development

Whereas our customers might be segmented into groups based on subscription extras:

• EXT_Base
• EXT_Base_plus_business
• EXT_Base_plus_enterprise

Within our knowledge base, we only segment content by two reader groups:

• Internal users (KO employees)
• External users (Customers)

No account belongs to both KO_ groups and EXT_ groups.

Since the two never overlap, we could create two regex pattern rules to look for these prefixes and assign our users to the appropriate reader group in our knowledge base.

In our SAML attribute map, we've mapped these fields:

• SSO ID: uid
• Username / email: email
• First name: firstName
• Last name: lastName

We set up our first Custom attribute map rule using these settings:

• IdP attribute name: groups
• Value matching type: Regex pattern
• Regex pattern: EXT_

  Regex formatting note
  KnowledgeOwl automatically includes the regex opening / and closing /i, so you don't need to include them in your Regex pattern.

• Reader attribute: Reader groups
• Assign to reader groups: External users

And created a second rule for our Internal users against the KO_ prefix

Once saved, the rules display as:

• "IF groups matches /EXT_/i THEN Reader groups = External users".
• "IF groups matches /KO_/i THEN Reader groups = Internal users".

With these rules in place:

• Anyone with any IdP KO_ group would be assigned to the Internal users reader group.
• Anyone with any IdP EXT_ group would be assigned to the External users reader group.