Custom Expressions and System Variables
Using Custom Expressions in Rule Configuration
This topic describes custom expressions. It is intended for advanced users.
Custom Expressions
Many system rules, such as role mapping rules or resource policy rules, support custom expressions. A custom expression is a combination of variables that the system evaluates as a Boolean object. The expression returns true, false, or error.
You can write custom expressions in the following formats. Note that elements of these formats are described in greater detail in the table that follows:
- variable comparisonOperator variable
- variable comparisonOperator simpleValue
- variable comparisonOperator (simpleValue)
- variable comparisonOperator (OR Values)
- variable comparisonOperator (AND Values)
- variable comparisonOperator (time TO time)
- variable comparisonOperator (day TO day)
- isEmtpy (variable)
- isUnknown (variable)
- (customExpr)
- NOT customExpr
- ! customExpr
- customExpr OR customExpr
- customExpr || customExpr
- customExpr AND customExpr
- customExpr && customExpr
The custom expression should be less than 64K.
Custom Expression Elements
The following table describes the Custom Expression Elements:
Element | Description |
|---|---|
variable | Represents a system variable. A variable name is a dot-separated string, and each component can contain characters from the set [a-z A-Z 0-9_ ] but cannot start with a digit [0-9]. Variable names are case-insensitive. For system variables that you may use in role mapping rules and resource policies. When writing a custom expression in a log query field, you need to use system log variables. These variables are described in the Filter Variables Dictionary on the Filter page (System > Log/Monitoring > Events | User Access | Admin Access > Filters > Select Filter tab). |
| Quoting syntax for variables: The system supports a quoting syntax for custom expression variables that allows you to use any character except '.' (period) in a user attribute name. To escape characters in an attribute name, quote some or all of the variable name using { } (curly-braces). For example, these expressions are equivalent: userAttr. = 'xyz' userAttr.LoginName = 'xyz' = 'xyz' userAName = 'xyz' |
| Escape characters supported within quotes: \\-Escape a backslash (\). \{-Escape a left curly brace ({). \}-Escape a right curly brace (}). \hh-Escape a hexadecimal value where hh is two characters from [0-9A-Fa-f]. |
| Examples: userAttr.{Tree Frog} = 'kermit' userAttr.{Tree\20Frog} = 'kermit' |
| There is no limit to the number of quotes you can use in a variable name. You can use the quoting syntax with any variable, not just userAttr.* variables. You need to use curly-brace quotes only when writing custom expressions. |
comparisonOperator | One of the following: =-Equal to. Use with strings, numbers, and DNs. !=-Not equal to. Use with strings, numbers, and DNs. <-Less than. Use with numbers. <=-Less than or equal to. Use with numbers. >-Greater than. Use with numbers. >=-Greater than or equal to. Use with numbers. |
simpleValue | One of the following: string - quoted string that may contain wildcards. IP Address-a.b.c.d subnet-a.b.c.d/subnetBitCount or a.b.c.d/netmask number-Positive or negative integer day-SUN MON TUE WED THU FRI SAT Notes about strings: A string may contain all characters except <nl> (newline) and <cr> (carriage return). Strings can be any length. String comparisons are case-insensitive. Strings can be quoted with single- or double-quotes. A quoted string may contain wildcards, including star(*), question mark (?), and square brackets ([ ]). variable comparisonOperator variable comparisons are evaluated without wildcard matching. Use a backslash to escape these characters: single-quote (') - \' double-quote (") - \" backslash (\) - \\ hexadecimal - \hh [0-9a-fA-F] Note about day: Day and time comparisons are evaluated in the system's time zone. Day range (day TO day) calculations start with the first day and step forward until the second day is reached. In time range (time TO time) calculations, the first value must be earlier than the second value. Only time variables can be compared to day and time values. The time variables are: time.* and loginTime.*. |
time | Time of day in one of the following formats: HH:MM - 24-hour HH:MMam - 12-hour HH:MMpm - 12-hour H:MM - 24-hour H:MMam - 12-hour H:MMpm - 12-hour Day and time comparisons are evaluated in the system's time zone. Day range (day TO day) calculations start with the first day and step forward until the second day is reached. In time range (time TO time) calculations, the first value must be earlier than the second value. Only time variables can be compared to day and time values. The time variables are: time.* and loginTime.*. |
OR Value | String containing one or more OR comparisons: Examples: variable comparisonOperator (number OR number ...) variable comparisonOperator (string OR string ...) |
AND Value | String containing one or more AND comparisons. Examples: variable comparisonOperator (number AND number ...) variable comparisonOperator (string AND string ...) |
isEmpty | Function that takes a single variable name (variable) argument and returns a boolean value. isEmpty() is true if the variable is unknown or has a zero-length value, zero-length strings, and empty lists. Example: isEmpty(userAttr.terminationDate) |
isUnknown | Function that takes a single variable name (variable) argument and returns a boolean value. isUnknown() is true if the variable is not defined. User attributes (userAttr.* variables) are unknown if the attribute is not defined in LDAP or if the attribute lookup failed (such as if the LDAP server is down). Example: isUnknown(userAttr.bonusProgram) |
NOT, ! | Logical negation comparisonOperator. The negated expression evaluates to true if the customExpr is false and evaluates to false if the customExpr is true. The operators NOT, AND, and OR are evaluated from highest to lowest precedence in this order: NOT (from right), AND (from left), OR (from left). |
OR, || | Logical operator OR or ||, which are equivalent. The operators NOT, AND, and OR are evaluated from highest to lowest precedence in this order: NOT (from right), AND (from left), OR (from left). |
AND, && | Logical AND or &&, which are equivalent. The operators NOT, AND, and OR are evaluated from highest to lowest precedence in this order: NOT (from right), AND (from left), OR (from left). |
customExpr | Expression written in the Custom Expression Syntax (see above). |
Wildcard Matching
In a quoted string, supported wildcards include:
- star (*)-A star matches any sequence of zero or more characters.
- question mark (?)-A question mark matches any single character.
- square brackets ([ ])-Square brackets match one character from a range of possible characters specified between the brackets. Two characters separated by a dash (-) match the two characters in the specified range and the lexically intervening characters. For example, 'dept[0-9]' matches strings "dept0", "dept1", and up to "dept9".
To escape wildcard characters, place them inside square brackets. For example, the expression ' userAttr.x = " value [*]" ' evaluates to true if attribute x is exactly "value*".
Using Multivalued Attributes
Multivalued attributes-attributes that contain two or more values-provide you with a convenient method for defining resources that expand into multiple individual bookmarks on the users' bookmarks page.
For example, assume that the user's LDAP directory contains the multivalued attribute HomeShares: \\Srv1\Sales;\\Srv2\Marketing. When you configure the Windows File share resource definition using the HomeShares multivalued attribute, \\<userAttr.HomeShares>, the user sees two bookmarks:
- \\Srv1\Sales
- \\Srv2\Marketing
Now let's assume the user's LDAP directory contains a second multivalued attribute defined as HomeFolders: Folder1;Folder2;Folder3. When you configure the Windows File share resource using both of the multivalued attributes, \\<userAttr.HomeShares>\<userAttr.HomeFolders>, the user sees the following six bookmarks:
- \\Srv1\Sales\Folder1
- \\Srv1\Sales\Folder2
- \\Srv1\Sales\Folder3
- \\Srv2\Marketing\Folder1
- \\Srv2\Marketing\Folder2
- \\Srv2\Marketing\Folder3
The only exception to this functionality is when the variable includes an explicit separator string. In this case, only one bookmark containing multiple resources displays on the users' bookmark page.
You specify the separator string in the variable definition using the syntax sep='string' where string equals the separator you want to use. For example, to specify a semi-colon as the separator, use the syntax <variable.Attr sep=';'>.
Use the following syntax for multivalued attributes handling. Note that <variable> refers to a session variable such as <userAttr.name> or <CertAttr.name>:
- <variable[Index]>-You specify indexes in a variety of ways. If, for example, the total number of values for a given index is 5, and you want to specify the entire range of values you use <variable[ALL]>. If you want to specify only the fourth value, you use <variable[4]>.
- <variable> is the same as <variable[ALL]>.
- <variable> is the same as <variable[ALL]>.
- <variable sep='str'> and <variable[All] sep='str'> - These variable definitions always refer to a single string value with all the tokens expanded out with separator strings between the values.
Variable names cannot contain spaces.
Specifying Multivalued Attributes in a Bookmark Name
Another common case of using multivalued attributes occurs when you include a variable in a bookmark name and in a URL or file server/share field.
For example, again assume that the user's LDAP directory contains the multivalued attribute HomeShares: \\Srv1\Sales;\\Srv2\Marketing. When you configure the Windows File share resource definition using the HomeShares multivalued attribute, \\<userAttr.HomeShares>, and you use the same attribute in the bookmark name field, <userAttr.HomeShares>, the system creates two bookmarks:
- Srv1\Sales bookmark pointing to \\Srv1\Sales
- Srv2\Marketing bookmark pointing to \\Srv2\Marketing
This does not create a situation in which you end up with the following set of conditions:
- Srv1\Sales bookmark pointing to \\Srv1\Sales
- Srv1\Marketing bookmark pointing to \\Srv1\Marketing (error)
- Srv2\Sales bookmark pointing to \\Srv1\Sales (error)
- Srv2\Marketing bookmark pointing to \\Srv2\Marketing
Distinguished Name Variables
You can compare a distinguished name (DN) to another DN or to a string, but the system ignores wildcards, white space, and case. Note, however, that the system takes the order of DN keys into consideration.
When the system compares an expression to a DN to a string, it converts the string to a distinguished name before evaluating the expression. If the system cannot convert the string due to bad syntax, the comparison fails. The DN variables are:
- userDN
- certDN
- certIssuerDN
The system also supports DN suffix comparisons using the matchDNSuffix function. For example:
matchDNSuffix( certDn, "dc=danastreet,dc=net")
Within the parenthesis, the first parameter is the " full" DN and the second is the suffix DN. You can use a variable or string for each parameter. Note that this first parameter should have more keys than the second (suffix parameter). Otherwise, if they are equal, it is the same as <firstparam> = <secondparam>. If the second parameter has more keys, matchDNsuffix returns false.
System Variables
The following table lists and defines system variables, gives an example for each system variable, and provides a guide as to where you may use system variables.
The following table lists the System Variables and Examples:
Variable | Description |
| Examples |
|---|---|---|---|
authMethod | Type of authentication method used to authenticates a user. | role mapping rules, resource policy rules | authMethod = 'ACE Server' |
certAttr.<cert-attr> | Attributes from a client-side certificate. Examples of certAttr attributes include: C - country CN - common name description - description e-mailAddress - e-mail address GN - given name initials - initials L - locality name O - organization OU - organizational unit SN - surname serialNumber- serial number ST - state or province title - title UI - unique identifier Use this variable to check that the user's client has a client-side certificate with the value(s) specified. | role mapping rules resource policy rules SSO parameter fields LDAP configuration | certAttr.OU = 'Retail Products Group' |
certAttr.altName.<Alt-attr> | Subject alternative name value from a client-side certificate where <Alt-attr> may be: Emailld EmailDomain DNS registeredId ipAddress UPN UPNid UPNDomain fascn fascnAC fascnSC fascnCN fascnCS fascnICI fascnPI fascnOC fascnOI fascnPOA fascnLRC | role mapping rules resource policy rules SSO parameter fields LDAP configuration | certAttr.altName.email = "[email protected]" certAttr.altName.ipAddress = 10.10.83.2 |
certAttr.serialNumber | Client certificate serial number. Note that all characters other than [0-9 a-f A-F] are stripped out of a string before comparison with certAttr.SN. Wildcards are not supported. | role mapping rules resource policy rules SSO parameter fields LDAP configuration | certAttr.SerialNumber = userAttr.certSerial certAttr.SerialNumber = "6f:05:45:ab" |
certDN | Client certificate subject DN. Wildcards are not permitted. | role mapping rules, resource policy rules | certDN = 'cn=John Harding,ou=eng,c=Company' certDN = userDN (match the certificate subject DN with the LDAP user DN) certDN = userAttr.x509SubjectName certDN = ('cn=John Harding,ou=eng,c=Company' or 'cn=Julia Yount,ou=eng,c=Company') |
certDN.<subject-attr> | Any variable from the client certificate subject DN, where subject-attr is the name of the RDN key. Use to test the various subject DN attributes in a standard x.509 certificate. | role mapping rules resource policy rules SSO parameter fields LDAP configuration | |
certDNText | Client certificate user DN stored as a string. Only string comparisons to this value are allowed. | role mapping rules resource policy rules SSO parameter fields | certDNText = 'cn=John Harding,ou=eng,c=Company' |
certAttr.EKUText | The Enhanced Key Usage field, abbreviated as EKU has 2 components to it. One part of it is the text which is in human readable format and the second part is the OID number which is unique for a given purpose. The user has the flexibility to create rules and realm-based restrictions using either of the two. Format to be given is: EKUText = string or <comma separated string> or string with regular expression. Custom expressions need to be given with the following format: certAttr.EKUText = string or <comma separated string> or string with regular expression. | role mapping rules resource policy rules SSO parameter fields | certAttr.EKUText = "TLS Web Server Authentication","E-mail Protection","TLS Web Client Authentication" |
certAttr.EKUOID | Format to be given is: EKUOID = to a.b.c.d.e.f.g.h.i or <comma separated list of EKUOIDs> or OID with regular expressions This works in both certificate rule as well as custom expressions. Custom expressions need to be given with the following format: certAttr.EKUOID = a.b.c.d.e.f.g.h.i or <comma separated list of EKUOIDs> or OID with regular expressions | | certAttr.EKUOID=1.3.6.1.5.5.7.3.1,1.3.6.1.5.5.7.3.4,1.3.6.1.5.5.7.3.2 |
certIssuerDN | Client certificate-issuer subject DN. This variable works like a standard DN attribute such as CertDN. Wildcards are not permitted. | role mapping rules resource policy rules SSO parameter fields | certIssuerDN = 'cn=John Harding,ou=eng,c=Company' certIssuerDN = userAttr.x509Issuer certIssuerDN = ('ou=eng,c=Company' or 'ou=operations,c=Company') |
certIssuerDN.<issuer-attr> | Any variable from the client certificate-issuer subject DN, where issuer-attr is the name of the RDN key. | role mapping rules resource policy rules SSO parameter fields | certIssuerDN.OU = 'company' certIssuerDN.ST = 'CA' |
certIssuerDNText | Client certificate-issuer subject DN stored as a string. Only string comparisons to this value are allowed. | role mapping rules resource policy rules SSO parameter fields | certIssuerDNText = 'cn=John Harding,ou=eng,c=Company' |
defaultNTDomain | Contains the Domain value set in the authentication server configuration when you use AD/NT authentication. | role mapping rules resource policy rules SSO parameter fields | defaultNTDomain=" CORP" |
geoLocationCountry | The location from where user should be allowed or denied to login from. In case you have a Fresh Installation of ICS, then it will NOT have UEBA package by default with it. Please add the UEBA package at Behavioral Analysis page before using Adaptive Authentication. In case of Upgrade of ICS from R7 or earlier to R8 or later, then UEBA package is carried forwarded as is and you can still update it to latest version by uploading new package. You may download latest UEBA package from Support Site. | role mapping rules | geoLocationCountry = 'United States' geoLocationCountry = ('United States' or 'Canada') |
group.<group-name> | User's group membership as provided by the realm authentication or directory server. | role mapping rules resource policy rules Only those groups evaluated for role mapping rules are available in the detailed rules (conditions) in the resource policies. We recommend that you use the groups variable instead of group.<group-name>, which is supported only for backwards compatibility. | group.preferredPartner group.goldPartner or group.silverPartner group.employees and time.month = 9 Combination examples: Allow all partners with active status from Monday to Friday but preferred partners Monday through Saturday: ((group.partners and time = (Mon to Fri)) or (group.preferredPartners and time = (Mon to Sat))) and userAttr.partnerStatus = 'active' Spaces are not supported, such as, group.sales managers |
groups | List of groups as provided by the realm authentication or directory server. NOTE: You can enter any characters in the groupname, although wildcard characters are not supported. | role mapping rules resource policy rules SSO parameter fields | groups=('sales managers') |
hostCheckerPolicy | Host Checker polices that the client has met. | role mapping rules resource policy rules SSO parameter fields | hostCheckerPolicy = ('Norton' and 'Sygate') and cacheCleanerStatus = 1hostCheckerPolicy = ('Norton' and 'Sygate') |
loginHost | Hostname or IP address that the browser uses to contact theIvanti Secure Access Client service. | role mapping rules resource policy rules SSO parameter fields LDAP configuration | loginHost = 10.10.10.10 |
loginTime | The time of day at which the user submits his credentials. The time is based on system time. NOTE: When using this variable in an SSO parameter field, the variable returns the UNIX string time. | role mapping rules resource policy rules SSO parameter fields | loginTime = (8:00am) loginTime= (Mon to Fri) |
loginTime.day | The day of month on which the user submits his credentials, where day is 1-31. The time is based on the system time. You cannot use the TO operator with variable. | role mapping rules resource policy rules | loginTime.day = 3 |
loginTime.dayOfWeek | The day of the week on which the user submits his credentials, where dayOfWeek is in the range [0-6] where 0 = Sunday. The system does not support the TO operator with time.dayOfWeek expressions if you use numbers instead of strings. In other words, " loginTime.dayOfWeek = (2 TO 6)" does not work, but " loginTime.dayOfWeek = (mon to fri)" does work. | role mapping rules resource policy rules | loginTime.dayOfWeek = (0 OR 6) loginTime.dayOfWeek = (mon TO fri) loginTime.dayOfWeek = (1) loginTime.dayOfWeek = 5 |
loginTime.dayOfYear | The numeric day of the year on which the user submits his credentials, where dayOfYear can be set to [0-365]. You cannot use the TO operator with this variable. | role mapping rules resource policy rules | loginTime.dayOfYear = 100 |
loginTime.month | The month in which the user submits his credentials, where month can be set to [1-12] where 1 = January. You cannot use the TO operator with this variable. | role mapping rules resource policy rules | loginTime.month >= 4 AND loginTime.month <=9 |
loginTime.year | The year in which the user submits his credentials, where year can be set to [1900-2999]. You cannot use the TO operator with this variable. | role mapping rules resource policy rules | loginTime.year = 2005 |
loginURL | URL of the page that the user accessed to sign in. The system gets this value from the Administrator URLs|User URLs column on the Authentication > Signing In > Sign-in Policies page of the admin console. | role mapping rules resource policy rules SSO parameter fields LDAP configuration | loginURL = */admin |
networkIf | The network interface on which the user request is received. Possible values: internal, external | role mapping rules resource policy rules SSO parameter fields | sourceIp = 192.168.1.0/24 and networkIf = internal |
ntdomain | The NetBIOS NT domain used in NT4 and Active Directory authentication. | role mapping rules SSO parameter fields | ntdomain = jnpr |
ntuser | The NT username used in Active Directory authentication | role mapping rules SSO parameter fields | ntuser = jdoe |
password password[1] password[2] | The password entered by the user for the primary authentication server (password and password[1]) or the secondary authentication server (password[2]). | role mapping rules resource policy rules SSO parameter fields | password = A1defo2z |
realm | The name of the authentication realm to which the user is signed in. | role mapping rules resource policy rules SSO parameter fields | Realm = ('GoldPartners' or 'SilverPartners') AND condition will always fail as a user is only allowed to sign in to a single realm in a session. |
role | List of all the user roles for the session. In SSO, if you want to send all the roles to back-end applications, use <role sep = ";"> - where sep is the separator string for multiple values. The system supports all separators except " and >. | resource policy rules SSO parameter fields | Role = ('sales' or 'engineering') Role = ('Sales' AND 'Support') |
sourceIP | The IP address of the machine on which the user authenticates. You can specify the netmask using the bit number or in the netmask format: '255.255.0.0'. Note that you can evaluate the sourceIP expression against a string variable such as an LDAP attribute. | role mapping rules resource policy rules SSO parameter fields | sourceIP = 192.168.10.20 sourceIP = 192.168.1.0/24 and networkIf internal userAttr.dept = ('eng' or 'it') and sourceIP = 10.11.0.0/16 sourceIP = 192.168.10.0/24 (Class C) is the same as: sourceIP = 192.168.10.0/255.255.255.0 sourceIP=userAttr.sourceip |
time | The time of day at which the role mapping rule or resource policy rule is evaluated. The time of the day can be in 12-hour or 24-hour format. | role mapping rules resource policy rules | time = (9:00am to 5:00pm) time = (09:00 to 17:00) time = (Mon to Fri) Combination examples: Allow executive managers and their assistants access from Monday to Friday: userAttr.employeeType = ('*manager*' or '*assistant*') and group.executiveStaff and time = (Mon to Fri) |
time.day | The day of month on which the user submits his credentials to, where day is 1-31. The time is based on the system time. | role mapping rules resource policy rules | loginTime.day = 3 |
time.dayOfWeek | The day of the week on which the role mapping rule or resource policy rule is evaluated, where dayOfWeek is in the range [0-6] where 0 = Sunday. | role mapping rules resource policy rules | loginTime.dayOfWeek = (0 OR 6) loginTime.dayOfWeek = (1 to 5) loginTime.dayOfWeek = 5 |
time.dayOfYear | The day of the year on which the role mapping rule or resource policy rule is evaluated. Possible values include: 1-365. | role mapping rules resource policy rules | time.dayOfYear = 100 |
time.month | The month in which the role mapping rule or resource policy rule is evaluated. Possible values include: 1-12 | role mapping rules resource policy rules | time.month >= 9 and time.month <= 12 and time.year = 2004 group.employees and time.month = 9 |
time.year | The year in which the role mapping rule or resource policy rule is evaluated, where year can be set to [1900-2999]. | role mapping rules resource policy rules | time.year = 2005 |
user user@primary_auth_server_name user@secondary_auth_server_name | Ivanti Secure Access Client username for the user's primary authentication server (user and user@primary_auth_server_name) or secondary authentication server (user@secondary_auth_server_name). Use when authenticating against an Active Directory server, domain and username. primary_auth_server_name is the name of the primary auth server. If there are spaces or special characters in the name, it can be enclosed in curly brackets. For example, user@{My Primary Auth Server} secondary_auth_server_name is the name of the secondary auth server. If there are spaces or special characters in the name, it can be enclosed in curly brackets. For example, user@{My Secondary Auth Server} NOTE: When including a domain as part of a username, you must include two slashes between the domain and user. For example, user='yourcompany.net\\joeuser'. | role mapping rules resource policy rules SSO parameter fields | user = 'steve' user = 'domain\\steve' |
username username@primary_auth_server_name username@secondary_auth_server_ name | Ivanti Secure Access Client system username for the user's primary authentication server (username and username@primary_auth_server_name) or secondary authentication server (username@secondary_auth_server_name). If the user is signing in to a certificate authentication server, then the user's Ivanti Secure Access Client system username is the same as CertDN.cn. primary_auth_server_name is the name of the primary auth server. If there are spaces or special characters in the name, it can be enclosed in curly brackets. For example user@{My Primary Auth Server} secondary_auth_server_name is the name of the secondary auth server. If there are spaces or special characters in the name, it can be enclosed in curly brackets. For example user@{My Secondary Auth Server} | role mapping rules resource policy rules SSO parameter fields | username = 'steve' and time = mon username = 'steve' username = 'steve*' username = ('steve' or '*jankowski') |
userAgent | The browser's user agent string. | role mapping rules resource policy rules SSO parameter fields | The browser's user agent string. |
userAttr.<auth-attr> | User attributes retrieved from an LDAP or RADIUS, authentication or directory server. | role mapping rules resource policy rules SSO parameter fields | userAttr.building = ('HQ*' or 'MtView[1-3]') userAttr.dept = ('sales' and 'eng') userAttr.dept = ('eng' or 'it' or 'custsupport') userAttr.division = 'sales' userAttr.employeeType != 'contractor' userAttr.salaryGrade > 10 userAttr.salesConfirmed >= userAttr.salesQuota Negative examples: userAttr.company != "Acme Inc" or not group.contractors not (user = 'guest' or group.demo) Combination examples: Allow executive managers and their assistants access from Monday to Friday: userAttr.employeeType = ('*manager*' or '*assistant*') and group.executiveStaff and time = (Mon to Fri) Allow all partners with active status from Monday to Friday but preferred partners Monday through Saturday: ((group.partners and time = (Mon to Fri)) or (group.preferredPartners and time = (Mon to Sat))) and userAttr.partnerStatus = 'active' |
userDN | The user DN from an LDAP server (not applicable to Active Directory auth server with ldap group lookup). If the user is authenticated by the LDAP server, then this DN is from the authentication server; otherwise, the DN comes from the realm's Directory/Attribute server. | role mapping rules resource policy rules | userDN = 'cn=John Harding,ou=eng,c=Company' userDN = certDN |
userDN.<user-attr> | Any variable from the user DN, where user-attr is the name of the RDN key. | role mapping rules resource policy rules SSO parameter fields | Any variable from the user DN, where user-attr is the name of the RDN key. |
userDNText | User DN stored as a string. Only string comparisons to this value are allowed. | role mapping rules resource policy rules SSO parameter fields | userDNText = 'cn=John Harding,ou=eng,c=Company' |
Custom Variables and Macros
Custom variables, like system variables, are name-value pair tags that you can use when defining role mapping rules, resource policy rules and SSO parameter fields.
Custom variables are created in the Server Catalog (for example, Authentication > Auth Server > Name > Settings) by using a predefined macro on a system variable. Available macros are:
- REGMATCH - Matches a regular expression pattern against a string text.
- APPEND - Appends a text string to another text string.
- DAYSDIFF - Calculates the difference between two dates.
These macros are located under Variable Operators in the Variables tab of the Server Catalog window.
A custom variable name is a dot-separated string. Each component can contain characters from the set [a-z A-Z 0-9 _] but cannot start with a digit [0-9]. Custom variable names are case-insensitive.
Custom variables are referenced as customVar.<variableName>. For example, if you create a custom variable with the name check-prefix, you reference this custom variable as customVar.check-prefix.
append
Field | Description |
|---|---|
Syntax | APPEND (attr, TextString) APPEND (attr, attr2) |
DescriptionS | Append a text string to an attribute or append an attribute to another attribute and store the resulting string in the custom variable. |
Options | attr-System variable of type string. TextString-Quoted ASCII string. attr2-System variable of type string. |
Output Fields | Returns a String value. If no match is found, returns an empty string. If the system variable is multivalued, the custom variable is also multivalued and uses the same order as the system variable. |
Sample Output | APPEND (userName, "@secure.net") In this example, the string "@secure.net" is appended to the userName value. |
daysdiff
Field | Description |
|---|---|
Syntax | DAYSDIFF (attr, timeformat) |
Description | Calculates the number of days between the attribute and the current time. |
Options | attr-System variable of type string. timeformat-Output time format. Valid values are: UTC, TIMET, MMDDYYYY |
Output Fields | Returns an Integer value. |
Sample Output | DAYSDIFF ( certAttr.validUpto, UTC) In this example, calculate the difference in days between the current time and the value of certAttr.validUpto and express the time in UTC (Coordinated Universal Time). |
regmatch
Field | Description |
|---|---|
Syntax | REGMATCH (attr, regex, groupingNumber) |
Description | Match the regular expression pattern against an attribute and store the result in the custom variable. |
Options | attr-System variable of type string. regex-Quoted string containing the regular expression to be applied to the attr option. groupingNumber-The group value to assign to the custom variable. |
Additional Information | The regular expression supports the Perl Compatible Regular Expressions (PCRE) syntax. A grouping (capture buffer) in the regex pattern can also be used to define a custom variable. |
Output Fields | Returns a String value. If no match is found, returns an empty string. If the system variable is multivalued, the custom variable is also multivalued and uses the same order as the system variable. |
Sample Output | REGMATCH (mailId, "^(.*)@ivantisecure.net$", 1) In this example, a mailId of [email protected] creates a custom variable with value "myName". |
Specifying Fetch Attributes in a Realm
To facilitate the support for various parameterized settings in user roles and resource policies, you have the ability to specify additional fetch attributes. The system stores the fetch attributes when users log in so that you can use them in parameterized role or resource policy definitions.
The system pulls all the attributes that are currently stored in the Sever Catalog for the user's authentication or authorization LDAP server. So, make sure to add the LDAP user attributes that are used in role or resource policy definitions in the LDAP Server Catalog first.
When a user logs in, the system retrieves user attributes that are referenced in the role mapping rules plus all of the additional attributes referenced in the Server Catalog and stores all these values. Note that this should not incur a significant performance overhead because all the user attributes are retrieved in one single LDAP query.
When you substitute variables, such as in IP/Netmasks or hostnames, the values in the session are appropriately converted into the data type that is required by the particular application definition.
Specifying the homeDirectory Attribute for LDAP
You can create a bookmark that automatically maps to a user's LDAP home directory. You can accomplish this using the LDAP attribute homeDirectory. You need to configure a realm that specifies the LDAP server instance as its auth server, and you need to configure role-mapping rules and a bookmark that points to the LDAP homeDirectory attribute.