Variable Regex Transformation

This behavior supports the authentication process for Internet of Things: Edge Connect which lets connected users and devices communicate through a publish/subscribe pattern within reserved namespaces. In conjunction with the Mutual Authentication behavior, the Variable Regex (regular expression) Transformation behavior affects how clients can authenticate themselves on edge servers and which groups within namespaces are authorized to access topics. It is not a mandatory behavior and is set only when using the part of the original values in the authentication process.

How it works

The Variable Regex Transformation behavior transforms a source string value based on a regular expression search pattern and stores it as a variable for authenticating the client request. The source string value can be client IDs or auth groups and is extracted from the client certificate by the Mutual Authentication behavior. As a result of the transformation, you can get another string as a substring or the same string matching the regex. It's used in further processing in the MQTT connection for authentication. The transformation output string cannot be empty and must match the regex exactly. Otherwise, it causes an authentication failure.

Regular expression transformation

Transformation consists of the following actions:

  • Regex matching. The input string match is checked for if it matches the regex.

  • Matching first group extraction. Only the first capturing group is checked and is extracted to the output string value. If the regex doesn’t contain a capturing group phrase marked by the brackets, the output string is always returned empty. Using at least one capturing group phrase in the regex is mandatory in order not to have the empty output string.

Features and options

FieldWhat it does
Regex PatternSpecifies a Perl-compatible regular expression with a single grouping to capture the text. For example, a value of ^.(.{0,10})omits the first character, but then captures up to 10 characters after that. If the regular expression does not capture a substring, authentication may fail.

📘

You can apply this regular expression transformation, or either of the Variable Hash Transformation or Variable Substring Transformation behaviors.

Examples

Let’s analyze some cases using an online regex testing tool. A majority of regex tools work similarly and usually show testing results as matching information and capturing group matching information.

After adding your regex and input string from the certificate field, you can check the output string in the match information section. If there is no section called Group 1, it means that the input string doesn’t match, or the regex doesn’t contain any capturing group expression.

  1. Regex value: ([^email:].*\@.*)$
    Test string: email:test@example.com
    Match information - Group 1: test@example.com
    Comment: The output (test@example.com) is the substring of the input string.

  2. Regex value: ^([\d\w]*)\.([\d\w]*)$
    Test string: filename.txt
    Match information - Group 1: filename
    Comment: The output (filename) is the substring of the input string.

  3. Regex value: ^(.*)$
    Test string: filename.txt
    Match information - Group 1: filename.txt
    Comment: The output (filename.txt) is the same as the input string. Any test string (input) matches the regex value ^(.*)$ and results in keeping the input unchanged as the output.