How to use account field expressions - Identity as a Service

This topic describes how to use advanced account field expressions in the built-in IDaaS expression engine, including model field descriptions, function descriptions, and reference examples.

Overview

IDaaS includes a built-in expression engine. In SAML and OIDC applications, you can use advanced expressions to add parameters to returned user information. Use expressions when a target application requires an additional parameter that must be transformed, concatenated, or evaluated conditionally.

You can similarly use expressions to assign custom values to fields when you configure field mappings synchronized with an identity provider.

Reference examples later in this topic help you quickly understand expression use cases and methods.

For example, OIDC SSO configuration supports extending the returned id_token information. In Extended Value, you can enter an advanced expression such as full_phone to meet a specific processing requirement. To do this, go to the SSO configuration page of the OIDC application. In the id_token extension field configuration area, enter the required expression (such as full_phone) in the Extended Value input box.

For more usage information, see Specifications for SAML attribute statement values, OIDC id_token custom field configuration, and Manage fields.

An expression has two parts:

A model, either User (for an IDaaS account) or AppUser (for an application account).
A function, which represents execution logic.

Models

1. User

Reference the following fields in the IDaaS User model by using a reference such as user.username or user.lockExpireTime.

Field Display Name	Field ID	Data Type	Required	Unique	User Permissions	Description
Account ID	userId	String	No	Yes	Visible	The user ID.
Account name	username	String	Yes	Yes	Visible	The username.
Display name	displayName	String	No	No	Editable	The user's display name.
Email	email	String	No	Yes	Editable	Email.
Mobile phone number	phoneNumber	Number	No	Yes	Editable	Mobile phone number.
Phone region code	phoneRegion	Number	No	No	Editable	The mobile phone region code. For example, the code for China is "86", without "00" or "+".
External ID	userExternalId	String	No	Yes	Visible	The user's external ID.
Source type	userSourceType	String	No	No	Visible	Valid values: build_in: self-built. ding_talk: DingTalk. ad: AD. ldap: LDAP. we_com: WeCom. lark: Lark. idp_auto_build: IdP automatic creation.
Source ID	userSourceId	String	No	No	Visible	The source ID.
Account status	status	String	No	No	Visible	Valid values: enabled: enabled. disabled: disabled.
Description	description	String	No	No	Visible	Description.
Account expiration time	accountExpireTime	Number	No	No	Visible	The account expiration time, as a UNIX timestamp in milliseconds.
Registration time	registerTime	Number	No	No	Visible	The account registration time, as a UNIX timestamp in milliseconds.
Password expiration time	passwordExpireTime	Number	No	No	Visible	The password expiration time, as a UNIX timestamp in milliseconds.
Lock expiration time	lockExpireTime	Number	No	No	Visible	The lock expiration time, as a UNIX timestamp in milliseconds.
Creation time	createTime	Number	No	No	Visible	The creation time, as a UNIX timestamp in milliseconds.
Update time	updateTime	Number	No	No	Visible	The time when user information was last updated, as a UNIX timestamp in milliseconds.

2. App User

Reference the following fields in the IDaaS AppUser model by using a reference such as appUser.username.

Property	Description
username	The username of the application account.

3. IdP User

The IdP User model applies when data is synchronized with an identity provider. For example, the DingTalk work location field is idpUser.work_place.

For specific fields, see the relevant identity provider documentation. For example, see DingTalk documentation - User details.

Important

For an OIDC identity provider (see Connect to an OIDC identity provider), when you use an expression for automatic binding, only the sub, phoneNumber, and email fields in id_token use the idpUser. prefix, for example, idpUser.sub. All other fields must use the idpUser.rawUserInfo. prefix, for example, idpUser.rawUserInfo.aud.

Functions

The following functions and examples are available:

Function	Syntax	Description	Example
Append	Append(str1, str2, ..., strn)	Concatenates input arguments into a new string, equivalent to `str1+str2+...`.	Input: `Append("str1", "@example.com")` Output: `str1@example.com`
Join	Join(source1, source2, ..., sourceN, separator)	Concatenates multiple source values into a string, using a separator between values.	Input: `Join("str1", "str2", 123,"-")` Output: `"str1-str2-123"`
Coalesce	Coalesce(source1, source2, ..., sourceN, defaultValue)	Returns the first non-empty input argument. If all arguments are empty, it returns null. A non-empty value is not null and has a length greater than 0.	Input: `Coalesce("", user.phoneRegion, "86")` Output: when the phone region code is empty or missing, the output is `86`
IIF	IIF(condition, whenTrue, whenFalse)	A ternary operation. Returns different values based on the result of condition: whenTrue when condition is true, and whenFalse when condition is false.	Example 1: Input: `IIF(true, 1, 2)` Output: `1` Example 2: Input: `IIF(false, 1, 2)` Output: `2`
IsNull	IsNull(value)	Returns true when value is null, which means the value is missing.	Example 1: Input: `IsNull(null)` Output: `true` Example 2: Input: `IsNull("")` Output: false
IsNullOrEmpty	IsNullOrEmpty(value)	Returns true when value is null or an empty string.	Example 1: Input: `IsNullOrEmpty(user.email)` Output: when the email is null or missing, the output is `true` Example 2: Input: `IsNullOrEmpty("")` Output: `true`
Now	Now()	Returns a string for the current UTC DateTime in yyyy-MM-dd'T'HH:mm:ssXXX format.	Output: 2021-11 01T09:52:11Z
StringReplace	StringReplace("hello $VariableName", "$VariableName", ReplaceString)	Performs a plain string replacement.	Input: `StringReplace("hello $str", "$str", "world")` Output: `hello world`
Trim	Trim(source)	Removes whitespace characters before and after a source string.	Input: `Trim(" 123 ")` Output: `123`
TrimLeft	TrimLeft(source)	Removes whitespace characters on the left of a source string.	Input: `TrimLeft(" 123 ")` Output: `123`
TrimRight	TrimRight(source)	Removes whitespace characters on the right of a source string.	Input: `TrimRight(" 123 ")` Output: `123`
ToLower	ToLower(source)	Converts a string to uppercase or lowercase.	Input: `ToLower(" Abc ")` Output: `abc`
ToUpper	ToUpper(source)	Converts a string to uppercase.	Input: `ToUpper(" Abc ")` Output: `ABC`
Substring	Substring(source, fromIndex, endIndex)	Returns a substring of the string, with indexes in [fromIndex, endIndex]. source: required; a source string of any type supported by the syntax. fromIndex: required; must be an integer. Non-integers return null. endIndex: required; must be an integer. Non-integers return null.	Example 1: Input: `Substring("0123456", 1, 5)` Output: `1234` Example 2: Input: `Substring("0123456", -1, 7)` Output: `0123456` Example 3: Input: `Substring("0123456", "1", 5)` Output: null
SubstringBefore	SubstringBefore(source, subString)	Returns the substring after the first target string matched from left to right in the source string. If no target string exists, it returns null. Parameters: source: required; a source string of any type supported by the syntax. target: required; a target string of any type supported by the syntax. Return value: string	Example 1: Input: `SubstringBefore("test@example@com", "@")` Output: `"test"`
Array	Array(source1, source2,...)	Combines multiple values into an array. Values can be Object types.	Input: `Array(1, 2, 3)` Output: `[1, 2, 3]`
ArrayAdd	ArrayAdd(Array(), "test")	Adds an array to an array object.	Input: `ArrayAdd(Array(), "test")` Output: `["test"]`
ArrayMap	ArrayMap($ArrayObject, __item.ObjectProperty)	Gets a property value from an array object to form a new array.	Get the IDs of groups to which the user belongs: Input: `ArrayMap(user.groups, __item.groupId)` Output: `["groupId1","groupId2","groupId3"]`
ArrayIndex	ArrayIndex(Array(), n)	Gets an Array element by position, starting from 0.	Input: `ArrayIndex(Array(1,2,3), 0)` Output: `1`
ArrayJoin	ArrayJoin(Array(), str)	Joins an array with a string.	Input: `ArrayJoin(Array(1,2,3), "-")` Output: `"1-2-3"`
Object	Object(key1, value1, key2, value2, ...)	Creates an Object from specified key-value pairs. Supports zero or an even number of arguments.	Input `Object("key1", "value1", "key2", "value2")` Outputs the corresponding object: `{"key1": "value1", "key2": "value2"}`
ObjectIndex	ObjectIndex(user, "username")	Gets the value of a specified property of an object.	Code `ObjectIndex(user, "username")` is equivalent to `user.username`
ObjectToJsonString	ObjectToJsonString(user.groups)	Converts an object to a JSON string.	-
Contains	Contains(str1,str2)	Checks whether a value is included, returning true or false.	Example 1: Input: `Contains("test", "t")` Output: `true` Example 2: Input: `Contains("test", "a")` Output: `false`
Or	Or(true,false,...,true)	Evaluates multiple conditions using OR. It returns true if any condition is true.	Example 1: Input: `Or(true,false)` Output: `true` Example 2: Input: `Or(true,true,false)` Output: `true` Example 3: Input: `Or(false,false)` Output: `false`
And	And(true,false,...,true)	Evaluates multiple conditions using AND. It returns false if any condition is false.	Example 1: Input: `And(true,false)` Output: `false` Example 2: Input: `And(true,true,false)` Output: `false` Example 3: Input: `And(true,true,true)` Output: `true`
xOr	xOr(true,false,...,true)	There must be exactly two conditions. It returns false when both are true or both are false. It returns true when one condition is true and the other is false.	Example 1: Input: `xOr(true,false)` Output: `true` Example 2: Input: `xOr(true,true)` Output: `false` Example 3: Input: `And(false,false)` Output: `false`
StartsWith	StartsWith(str1, str2)	Checks whether a string starts with the specified value. It accepts only two parameters.	Example 1: Input: `StartsWith("test", "t")` Output: `true` Example 2: Input: `StartsWith("test", "e")` Output: `false`
Split	Split("str1,str2,str3")	Splits a string and returns an array.	Example 1: Input: `Split("str1,str2,str3",",")` Output: `Array(str1,str2,str3)`
Equals	Equals(str1,str2)	Compares two strings for equality. Equals(str1,str2). Equals(str1,str2,false) does not ignore case. Equals(str1,str2,true) ignores case.	Example 1: Input: `Equals("test","Test")` Output: `false` Example 2: Input: `Equals("test","Test",true)` Output: `true` Example 3: Input: `Equals("test","Test",false)` Output: `false`
CurrentTimeMillis	CurrentTimeMillis()	The current UNIX timestamp in milliseconds.	-
SamlArray	SamlArray(Array())	Available only for SAML SSO.	Input: `SamlArray(Array("group1","group2"))` SAML Response output. `<saml2:Attribute Name="grouIdArray"` `NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">` <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xsd:string"> group1 `</saml2:AttributeValue>` `<saml2:AttributeValue` xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string"> group2 `</saml2:AttributeValue>` Input: `SamlArray(Array("group1","group2"))` SAML Response output. `</saml2:Attribute>`
ExtractPhoneRegion	ExtractPhoneRegion(source, defaultRegion,autoAppendPlusSignal)	Extracts the region code from a mobile phone number. source: mobile phone number. autoAppendPlusSignal: whether to add a plus sign automatically. true adds it; false does not. defaultRegion: the default country or region for the phone region code. For country and region codes, use the Alpha-2 code in ISO 3166 Country Codes, such as CN, US, or TW. If a number includes a region code preceded by +, you do not need to specify autoAppendPlusSignal or deafaultRegion. If a number includes a region code without +, specify autoAppendPlusSignal=true and set defaultRegion to the default country or region code. If a number does not include a region code and you want to set a default region code, specify autoAppendPlusSignal=false and set defaultRegion to the default country or region code.	Example 1: If the number is `+86131xxxxx000`, `+86 131xxxxx000`, or `+86-131xxxxx000` Input: ExtractPhoneRegion(idpUser.mobile) Return: 86 Example 2: If the number is `86131xxxxx000`, `86 131xxxxx000`, or `86-131xxxxx000` Input: ExtractPhoneRegion(idpUser.mobile,"CN",true) Return: 86 Example 3: If the number is `131xxxxx000` Input: ExtractPhoneRegion(idpUser.mobile,"CN",false) Return: 86
ExtractPhoneNumber	ExtractPhoneNumber(source, defaultRegion,autoAppendPlusSignal)	Extracts the actual mobile phone number without the region code. source: mobile phone number. autoAppendPlusSignal: whether to add a plus sign automatically. true adds it; false does not. defaultRegion: the default country or region for the phone region code. For country and region codes, use the Alpha-2 code in ISO 3166 Country Codes, such as CN, US, or TW. If a number includes a region code preceded by +, you do not need to specify autoAppendPlusSignal or deafaultRegion. If a number includes a region code without +, specify autoAppendPlusSignal=true and set defaultRegion to the default country or region code. If a number does not include a region code and you want to set a default region code, specify autoAppendPlusSignal=false and set defaultRegion to the default country or region code.	Example 1: If the number is `+86131xxxxx000`, `+86 131xxxxx000`, or `+86-131xxxxx000` Input: ExtractPhoneNumber(idpUser.mobile) Return: 131xxxxx000 Example 2: If the number is `86131xxxxx000`, `86 131xxxxx000`, or `86-131xxxxx000` Input: ExtractPhoneNumber(idpUser.mobile,"CN",true) Return: 131xxxxx000 Example 3: If the number is `131xxxxx000` Input: ExtractPhoneNumber(idpUser.mobile,"CN",false) Return: 131xxxxx000

Reference examples

Scenario	Example expression
Get the username and append the fixed string "@example.com".	`Append(user.username, "@example.com")`
Return the email address when it is not empty. Return the mobile phone number when the email address is empty.	`Coalesce(user.email, user.phoneNumber)`
Use a fixed mobile phone number when the mobile phone number is empty.	`IIF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber)`
Join the phone region code and mobile phone number with -.	`Join(user.phoneRegion, user.phoneNumber, "-")`
Return a custom welcome message that contains the display name.	`StringReplace("hello $DisplayName", "$DisplayName", user.displayName)`
Mask the middle four digits of a mobile phone number with *.	`Append(` `SubString(user.phoneNumber, 0, 4),` `"****",` `SubString(user.phoneNumber, 8, 10)` )
Extract the username from an email address.	`SubstringBefore(user.email, "@")`
Assemble an email field in the array format required by the SCIM specification.	`Array(Object("email", user.email, "type", "work", "primary", true))`

User model JSON example:

{
  "customFieldMap": {
        "place": {
            "fieldName": "place",
            "fieldValue": "beijing"
        },
        "age": {
            "fieldName": "age",
            "fieldValue": "18"
        }
    },
    "identityProviderUserMap": {
        "idp_m2gngriuenktdkxxxxxx": {
            "identityProviderId": "idp_m2gngriuenktdkxxxxxx",
            "identityProviderType": "ding_talk",
            "identityProviderExternalId": "corp_1234xxxxxxx",
            "identityProviderUserId": "b2ed5fc0xxxxx"
        }
    },
    "organizationalUnits": [
        {
            "organizationalUnitId": "ou_sdfadtaaxxxxxx",
            "organizationalUnitName": "name_001",
            "primary": false
        },
        {
            "organizationalUnitId": "ou_werttxxxxxx",
            "organizationalUnitName": "name_002",
            "primary": true
        }
    ],
    "primaryOrganizationalUnitId": "ou_werttxxxxxx",
    "customFields": [
        {
            "fieldName": "place",
            "fieldValue": "beijing"
        },
        {
            "fieldName": "age",
            "fieldValue": "18"
        }
    ],
    "groups": [
        {
            "groupId": "group_jp6al4sn4n4wjgjxxxxxx",
            "groupName": "group1",
            "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx"
        },
        {
            "groupId": "group_vavikcxewkf5h3oxxxxxx",
            "groupName": "group2",
            "groupExternalId": "group_vavikcxewkf5h3oxxxxxx"
        }
    ],
  "userId": "user_x3zyd6cxxxxxxxxxxxxx",
  "username": "name_001",
  "displayName": "displayname_001",
  "passwordSet": true,
  "phoneRegion": "86",
  "phoneNumber": "333xxxx3333",
  "phoneNumberVerified": true,
  "email": "xxxxx@example.com",
  "emailVerified": true,
  "userExternalId": "b2ed5fc0xxxxxxxxxx",
  "userSourceType": "ding_talk",
  "userSourceId": "corp_1234xxxxxxx",
  "status": "enabled",
  "accountExpireTime": "-1",
  "passwordExpireTime": "-1",
  "registerTime": "1730454581598",
  "lockExpireTime": "-1",
  "createTime": "1730454582379",
  "updateTime": "1733479455307"
}