Username Rules

When provisioning access to an application that results in a new user being created, some applications require a "username" field to be populated. Rather than just using the identity's email address, Clarity allows you to set custom username rules. These rules can be general, and apply to all new application access, or be conditional and target specific applications or situations.

To access these settings head to Settings > Username/Identifiers

Topics we will cover:

• Rule structure
• Default username rule
• Custom rules

How do username rules work?

Out of the box, Clarity comes with a default username rule. This is typically of the form [first_initial][last_name]@[yourdomain]. This results in usernames of the form jsmith@yourdomain.com. The default rule has no additional conditions, so it will apply if no other username rules are applicable.

You can create as many username rules as you would like and set conditions to tailor them to your specific use-cases. For instance, you may want to provision Azure Active Directory accounts to use a simple [first_initial][last_name] scheme (jsmith) or you can set more exotic rules based on the identity type, add custom postfixes if the identity is a contractor or guest account, or any combination of the two. Each username rule is ordered by priority and Clarity will apply the first rule that it finds that meets the conditions specified, falling back to the default rule if no others apply.

Rule structure

All usename rules have a few parts. They are:

• Condition(s) - optional
• Attributes
• Pattern
• Format
• Incrementer
• Priority

Conditions

If you want your rule to apply only in certain contexts, you can specify conditions that must be met.

Each condition has a condition type. The two condition types are currently "Application" and "Identity Type", but the Clarity team will continue to add new conditions over time.

Each condition has an operator of the form "is" or "is not".

Each condition has a value the must be specified. The possible values for each condition are dynamically populated based on the applications and identity types in your environment.

Using these three parts, you can set conditions like:

• "Application is 'MS Active Directory'"
• "Application is not 'AWS'"
• "Identity type is 'guest'"

and so forth. If you specify multiple conditions on a single rule, all of the conditions must be met in order for the rule to apply. For instance, if you set two conditions "Application is MS Active Directory" and "Identity Type is Guest" the rule will only be applied when trying to create a new MS Active Directory account for a Guest user.

Attributes

Each rule must specify the attribute(s) that you want to draw from when creating possible usernames. These should be uniquely identifiable and easily tied to a specific identity. The most common attributes are "First Name" and "Last Name", but you can specify whichever attributes you would like when generating a username. For instance, you could set the attributes "First Name", "Last Name", "Department" and generate usernames of the form "jsmith-dev".

All of the pre-populated formats rely on "First Name" and "Last Name" as the attributes. If you want to use the standard patterns/formats, you should keep these as your attributes.

Pattern

The rule pattern lets you select how you want your username to be generated based on the attributes you've selected. The dropdown has many common username options, as well as a "custom" option. When you select a pattern, the format (below) will automatically update to match the pattern you've selected. If you select "custom" you can specify your own regular expression with subgroups to create any username pattern you desire.

Format

The username format references the pattern you've selected and substitutes the values into a string which will become the username. For instance, if you've selected j.smith, the format will be $1.$2@yourdomain.com. $1 is a reference to the "j" part of the pattern and $2 is a reference to the "smith" part of the format. You can modify the format however you wish by adding to the string.

For example, if you have a username rule based on the condition "Identity Type is Guest", you may want to use a format of: "$1.$2-guest" which would result in a username of "j.smith-guest" whenever the rule applies.

Another common example would be to set a different domain string from your default domain based on these conditions. For instance, if you set a rule that applied when the application is "Salesforce" you may want to modify the pattern to be "$1.$2@sales.yourdomain.com".

Incrementer

The incrementer specifies how the rule should be modified if there are collisions between two or more identities/users. Its common for large organizations to have more than one "J Smith". Clarity will increment the generated username any time it detects a collision. The possible values for the incrementer are any of the attributes you've selected as well as the default "integer" incrementer. If you select an attribute, Clarity will add on additional letters on to the attribute you've specified until there is no longer a collision. In our example, lets say we have a John Smith and a James Smith. When we try to create a username for John Smith, Clarity will see that there is a potential collision with James. If you've selected "First Name" as the incrementer, the resulting username will be "jo.smith" for John, and "ja.smith" for James. Clarity will continue to add additional letters until no collision is found. If it runs out of available letters, Clarity will then start to add integers onto the end of the username portion (j.smith_1, j.smith_2, etc...) If you just select "integer" as the incrementer, Clarity will not attempt to add extra letters and instead just go straight to adding integers.

Priority

Every rule has a priority which determines the order that Clarity will attempt to apply one rule vs another. If two or more rules apply, Clarity will apply the first rule it finds, corresponding to the lowest priority. Priority 1 rule will apply before priority 2, 3, and so forth. The default rule has priority 99 and will always be applied last, only if no other rules apply.

To change rule priorities, simply click the blue UP or DOWN arrows next to the rule, and the priority will be automatically updated upon Save.

Default username rule

The default username rule has the lowest priority and no conditions. This means that it will apply to any application that requires a username, if no other rules are found. Its generally a good idea to keep this rule as an email-type rule, with your default domain attached. This way, it will be able to generate acceptable usernames for applications that require email addresses as well as applications that allow more flexible rules.

Custom Rules

If you select "custom" for the rule pattern, you will then see a regular expression of the rule. This allows you to set your own expression and substitution as you see fit. The custom rule will not automatically update the format field, so make sure that when you are done inputting your regular expression, you update the format field accordingly. You will see a preview of the resulting username as you alter the pattern and format fields.

Candidate phrase

When writing a custom regular expression, Clarity starts by generating a candidate phrase which is simply a string of all the attributes you've selected one after the other. This phrase becomes the input of the regular expression/substitution. If you select "First Name", "Last Name" and "Department" as your attributes. The generated candidate phrase would be "John Smith Operations" for example. This phrase then gets fed into the regular expression pattern you specify.

Here is an example of a custom pattern/format based on that example:

For more information on regular expressions check out this reference.