Reset Search
 

 

Article

KB41018 - What are regular expressions (regex) and how to use them in the REGMATCH macro as custom variables in PCS auth server catalog

« Go Back

Information

 
Last Modified Date4/27/2018 11:49 PM
Synopsis
This article describes what regular expressions (regex) are and how to use them in the REGMATCH macro as custom variables in PCS auth server catalog.
Problem or Goal
Regular expressions, often abbreviated to the term "regex", can be used in the REGMATCH macro as part of the Custom Variables in the Authentication Server catalog.

 
Cause
Solution
Regex is a powerful pattern matching tool which is widely used in programming languages and computer applications against strings and text.   It uses designated meta characters such as "." and "*" to construct an expression that can be then used to match and extract information from the input string, such as the username portion of username@domain.name with a regex of ^(.*)@domain.name$

The Pulse Secure regex uses the Perl Compatible Regular Expressions (PCRE) syntax.

This can be used by the REGMATCH macro to extract part of a string so it can be assigned to a variable name for later use.  For the above example, if the mailId contains a pulsesecure.net email address then the username can be extracted with REGMATCH (mailId, “^(.*)@pulsesecure.net$”, 1)


The common meta characters are shown in the table below.
(See the links in the Related Links section for references to more information.)
 
 
MetacharacterMeaning
^Matches the start of a string or line
$Matches the end of a string or line
.matches a single character
*Matches the preceding character or expression zero or more times
+Matches the preceding character or expression one or more times
?Matches the preceding character or expression zero or one time
[ ]Defines a character set, includes a set of characters of which one must match.  For example [0-9] matches a single digit while [a-z] matches a single lower class character.  gr[ae]y will match gray or grey but not graey.
[^ ]Negates the character set.  For example [^0-9] will match any non-numeric character.
\dMatches a numeric character, equivalent to [0-9]
\sMatches a whitespace character such as a space or tab
\wMatches a word, a string of alphanumeric characters and underscores
( )Defines a grouping.  Whatever is matched within the brackets can be used as a variable.  The repetition metacharacters like * + and ? can be placed after a grouping, for example foo(bar)? will match foo or foobar.
Acts as a logical OR and matches whatever is either side of |. For example, foo|bar matches foo or bar


Any matches are termed greedy, in that they will attempt to match as many characters as possible.   For example .*xyz  when applied to abcxyzabcxyz would match the whole string.  To do a non-greedy match so abcxyz is returned as the match add a question mark after the repetition metacharacter in the regex, which would be .*?xyz

When using meta characters that start with a backslash such as \s, an extra slash is required in front of the meta character to escape the default interpretation of \ by the PCS/PPS. 

Example:
Enter \s as \\s

 

REGMATCH Example

For users that are authenticating with certificates, a Policy Trace will reveal that the username is being populated by the certAttr.CN as the example below:

 userName = "Gonzo Muppet JHPKI ABC9D6745F089GZ0"

To extract the last string (ABC9D6745F089GZ0) from the userName portion of the user directory, use REGMATCH to extract and store it in a custom variable.
  • Go to User Realm >Role Mapping; click New Rule
  • Change Rule based on: drop-down to Custom Expressions; click Update
  • In the section Rule: If user has any of these custom expressions... click Expressions to pop up the Server Catalog window
  • Click the Variables tab
  • Expand Variable Operators in the right-hand menu; click REGMATCH and click < Insert Expression

Modify the expression as per the example below:
   REGMATCH (userName, "^.*\\s(.*)$" , 1)

There is a checkbox to enable the simulator so you can test regexs to confirm the behavior.  It is recommended to use this to verify the regex against a variety of possible inputs. 

For the above userName as the input string the Custom Variable Expression would be:
REGMATCH (userName, "^.*\\s(.*)$" , 1)

Which gives a result of:
Custom Variable value = ABC9D6745F089GZ0


The regex  "^.*\\s(.*)$"  consists of:

^ matches from the start of a line
.* a greedy match for all characters up to the last instance of the next matching expression, which is...
\\s a space character (we need to use an extra \ to escape the default interpretation of the \ character)
(.*) match all characters up to the the next matching expression and store them as a grouping, which is... 
$ end of line

The brackets around the last .* allow the contents to be used as the variable, if there are more than one set of brackets then the last number then you can specify which set of brackets to use for the variable with the grouping number of the regex ( REGMATCH (attr, regex, groupingNumber) ).  For example if you used the regex ^(.*)\\s(.*)$ then the groupingNumber would need to be 2 to return the second grouping.


Once the REGMATCH has been added then the Custom Variable can be used by specifying customVar.<variableName> e.g. if you called the variable UNfromCert, then use customVar.UNfromCert
 
Related Links
Attachment 1 
Created ByMatthew Spiers

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255