You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/active-directory/develop/active-directory-jwt-claims-customization.md
+24-23Lines changed: 24 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,42 +104,43 @@ The following table provides information about the first level of transformation
104
104
105
105
| Action | Field | Description |
106
106
| :----- | :---- | :---------- |
107
-
| 1 | Transformation | Select the **RegexReplace()** option from the **Transformation** options to use regex-based claims transformation method for claims transformation. |
108
-
| 2 | Parameter 1 |*Parameter 1* is the source user input attribute that is an input for the regular expression transformation. For example, user.mail that has a user email address such as `admin@contoso.com`. |
109
-
| 3 | Treat source as multivalued | Some input user attributes can be multi-value user attributes. If the selected user attribute supports multiple values and the user wants to use multiple values for the transformation, they need to check the **Treat source as multivalued** checkbox. If an administrator checks the checkbox, all values are used for regex match, otherwise only the first value is used.
110
-
| 4 | Regex pattern |The **Regex pattern** textbox accepts a regular expression that is evaluated against the value of user attribute selected as *parameter 1*. For example a regular expression to extract user alias from the user's email address would be represented as: "(?'domain'^.*?)(?i)(\@contoso\.com)$"|
111
-
| 5 | Add additional parameter | By using **Add additional parameter**, an administrator can choose more user attributes that can be used for the transformation. The values of the attributes would then be merged with regex transformation output. Up to five additional parameters are supported.<br/>To illustrate, let's use user.country attribute as an input parameter. The value of this attribute is "US". To merge the attribute into the replacement pattern, the administrator needs to refer to it as {country} inside the replacement pattern. Once the administrator selects the user attribute for the parameter, an info balloon for the parameter explains how the parameter can be used inside the replacement pattern.
112
-
| 6 | Replacement pattern | The **Replacement pattern** textbox accepts the replacement pattern. Replacement pattern is the text template, which contains placeholders for regex outcome group name, input parameter group name, and static text value. All group names must be wrapped inside the curly braces such as {group-name}. Let's say the administration wants to use user alias with some other domain name, for example "xyz.com" and merge country name with it. In this case, the replacement pattern would be "{country}.{domain}@xyz.com", where {country} is the value of input parameter and {domain} is the group output from the regular expression evaluation. In such a case, the expected outcome is "[email protected]".
113
-
| 7 | Test transformation | The RegexReplace() transformation is evaluated only if the value of the selected user attribute for *Parameter 1* matches with the regular expression provided in the **Regex pattern** textbox. If they don't match, the default claim value is added to the token. To validate regular expression against the input parameter value, a test experience is available within the transform blade. This test experience operates on dummy values only. When additional input parameters are used, the name of the parameter is added to the test result instead of the actual value. You can see a sample output in point 18. To access the test section, an administrator can select the **Test transformation**. |
107
+
| 1 | Transformation | Select the **RegexReplace()** option from the **Transformation** options to use the regex-based claims transformation method for claims transformation. |
108
+
| 2 | Parameter 1 |The input for the regular expression transformation. For example, user.mail that has a user email address such as `admin@fabrikam.com`. |
109
+
| 3 | Treat source as multivalued | Some input user attributes can be multi-value user attributes. If the selected user attribute supports multiple values and the user wants to use multiple values for the transformation, they need to select **Treat source as multivalued**. If selected, all values are used for the regex match, otherwise only the first value is used.|
110
+
| 4 | Regex pattern |A regular expression that is evaluated against the value of user attribute selected as *Parameter 1*. For example a regular expression to extract the user alias from the user's email address would be represented as`(?'domain'^.*?)(?i)(\@fabrikam\.com)$`.|
111
+
| 5 | Add additional parameter |More than one user attribute can be used for the transformation. The values of the attributes would then be merged with regex transformation output. Up to five additional parameters are supported.|
112
+
| 6 | Replacement pattern | The replacement patternis the text template, which contains placeholders for regex outcome. All group names must be wrapped inside the curly braces such as {group-name}. Let's say the administration wants to use user alias with some other domain name, for example "xyz.com" and merge country name with it. In this case, the replacement pattern would be "{country}.{domain}@xyz.com", where {country} is the value of input parameter and {domain} is the group output from the regular expression evaluation. In such a case, the expected outcome is "[email protected]".
113
+
transformation**. |
114
114
115
115
:::image type="content" source="./media/active-directory-jwt-claims-customization/regexreplace-transform2.png" alt-text="Screenshot of second level of claims transformation.":::
116
116
117
117
The following table provides information about the second level of transformations. The actions listed in the table correspond to the labels in the previous image.
118
118
119
119
| Action | Field | Description |
120
120
| :----- | :---- | :---------- |
121
-
| 9 | Transformation | Regex-based claims transformations aren't limited to the first transformation and can be used as the second level transformation as well. Any other transformation method can be used as the first transformation. |
122
-
| 10 | Parameter 1 | If **RegexReplace()** is selected as a second level transformation, output of first level transformation is used as an input for the second level transformation. The second level regex expression should match the output of the first transformation else the transformation won't be applied. |
123
-
| 11 | Regex pattern |**Regex pattern** is the regular expression for the second level transformation. |
124
-
| 12 | Parameter input | User attribute inputs for the second level transformations. |
125
-
| 13 | Parameter input | Administrators can delete the selected input parameter if they don't need it anymore. |
121
+
| 1 | Transformation | Regex-based claims transformations aren't limited to the first transformation and can be used as the second level transformation as well. Any other transformation method can be used as the first transformation. |
122
+
| 2 | Parameter 1 | If **RegexReplace()** is selected as a second level transformation, output of first level transformation is used as an input for the second level transformation. The second level regex expression should match the output of the first transformation or the transformation won't be applied. |
123
+
| 3 | Regex pattern |**Regex pattern** is the regular expression for the second level transformation. |
124
+
| 4 | Parameter input | User attribute inputs for the second level transformations. |
125
+
| 5 | Parameter input | Administrators can delete the selected input parameter if they don't need it anymore. |
126
+
| 6 | Replacement pattern | The replacement pattern is the text template, which contains placeholders for regex outcome group name, input parameter group name, and static text value. All group names must be wrapped inside the curly braces such as {group-name}. Let's say the administration wants to use user alias with some other domain name, for example "xyz.com" and merge country name with it. In this case, the replacement pattern would be "{country}.{domain}@xyz.com", where {country} is the value of input parameter and {domain} is the group output from the regular expression evaluation. In such a case, the expected outcome is "[email protected]". |
127
+
| 7 | Test transformation | The RegexReplace() transformation is evaluated only if the value of the selected user attribute for *Parameter 1* matches with the regular expression provided in the **Regex pattern** textbox. If they don't match, the default claim value is added to the token. To validate regular expression against the input parameter value, a test experience is available within the transform blade. This test experience operates on dummy values only. When additional input parameters are used, the name of the parameter is added to the test result instead of the actual value. To access the test section, select **Test transformation**. |
126
128
127
-
:::image type="content" source="./media/active-directory-jwt-claims-customization/regexreplace-trasform3.png" alt-text="Screenshot of testing the transformation.":::
129
+
:::image type="content" source="./media/active-directory-jwt-claims-customization/regexreplace-transform3.png" alt-text="Screenshot of testing the transformation.":::
128
130
129
131
The following table provides information about testing the transformations. The actions listed in the table correspond to the labels in the previous image.
130
132
131
133
| Action | Field | Description |
132
134
| :----- | :---- | :---------- |
133
-
| 14 | Test transformation | Once administrator selects **Test transformation**, the section is displayed, and **Test transformation** goes away. |
134
-
| 15 | Test transformation | Select the close or (X) button to hide the test section and re-render the **Test transformation** button again on the blade. |
135
-
| 16 | Test regex input | The **Test regex input** textbox accepts the dummy input, which is used as an input for regular expression test evaluation. In case regex-based claims transformation is configured as a second level transformation, the administrator needs to provided a dummy value, which would be the expected output of the first transformation. |
136
-
| 17 | Run test | Once the administrator provides the test regex input and configures the **Regex pattern**, **Replacement pattern** and **Input parameters**, they can evaluate the expression by selecting **Run test**. |
137
-
| 18 | Test transformation result | If evaluation succeeds, an output of test transformation will be rendered against the **Test transformation result** label. |
138
-
| 19 | Remove transformation | The administrator can remove the second level transformation by selecting **Remove transformation**. |
139
-
| 20 | Specify output if no match | When a regex input value is configured against the **Parameter 1** which doesn't matches the **Regular expression**, the transformation is skipped. In such cases, the administrator can configure the alternate user attribute, which is added to the token for the claim by checking **Specify output if no match**. |
140
-
| 21 | Parameter 3 | If an administrator wants to return alternate user attribute when there's no match and **Specify output if no match** is checked, they can select an alternate user attribute by using the dropdown. This dropdown is available against **Parameter 3 (output if no match)**. |
141
-
| 22 | Summary | At the bottom of the blade, a full summary of the format is displayed that explains the meaning of the transformation in simple text. |
142
-
| 23 | Add | Once the administrator is satisfied with the configuration settings for the transformation, they can save it to claims policy by selecting **Add**. Changes won't be saved unless the administrator manually selects **Save** available on **Manage Claim** blade. |
135
+
| 1 | Test transformation | Select the close or (X) button to hide the test section and re-render the **Test transformation** button again on the blade. |
136
+
| 2 | Test regex input | Accepts input that is used for the regular expression test evaluation. In case regex-based claims transformation is configured as a second level transformation, a value is provided that would be the expected output of the first transformation. |
137
+
| 3 | Run test | After the test regex input is provided and the **Regex pattern**, **Replacement pattern** and **Input parameters** are configured, the expression can be evaluated by selecting **Run test**. |
138
+
| 4 | Test transformation result | If evaluation succeeds, an output of test transformation will be rendered against the **Test transformation result** label. |
139
+
| 5 | Remove transformation | The second level transformation can be removed by selecting **Remove transformation**. |
140
+
| 6 | Specify output if no match | When a regex input value is configured against the *Parameter 1* that doesn't matche the **Regular expression**, the transformation is skipped. In such cases, the alternate user attribute can be configured, which is added to the token for the claim by checking **Specify output if no match**. |
141
+
| 7 | Parameter 3 | If an alternate user attribute needs to be returned when there's no match and **Specify output if no match** is checked, an alternate user attribute can be selected using the dropdown. This dropdown is available against **Parameter 3 (output if no match)**. |
142
+
| 8 | Summary | At the bottom of the blade, a full summary of the format is displayed that explains the meaning of the transformation in simple text. |
143
+
| 9 | Add | After the configuration settings for the transformation are verified, it can be saved to a claims policy by selecting **Add**. Changes won't be saved unless **Save** is selected on the **Manage Claim** blade. |
143
144
144
145
RegexReplace() transformation is also available for the group claims transformations.
0 commit comments