Overview
Identity as a Service (IDaaS) has a built-in expression engine. In Security Assertion Markup Language (SAML) and OpenID Connect (OIDC) applications, you can use advanced expressions to add parameters to the response information. When an application requires additional parameters, and the parameters need to be converted, concatenated, or checked, you can use expressions to process and add the parameters.
Similarly, when you configure the mappings between fields on IDaaS and those from an identity provider, you can also use expressions to assign values to the fields.
This topic provides common examples in the last section to help you understand what the expressions are used for and how to specify expressions.
The following figure shows a single sign-on (SSO) setting for OIDC applications. You can extend fields in the id_token to be returned. You can enter an advanced expression as the value of an extended field to obtain required results.
An expression consists of the following two parts:
Model: User (corresponding to an IDaaS account) and AppUser (corresponding to an
application account).Function: execution logic.
Models
1. User
The following fields are available in the User model. If you want to use one of the following fields in an expression, you can add the user. prefix to the field, such as user.username or user.lockExpireTime.
Field | Description |
username | The username. |
displayName | The display name of the user. |
passwordSet | Specifies whether a password is set. |
phoneRegion | The country code of the mobile number. For example, the country code of China is 86 without 00 or +. |
phoneNumber | The mobile number. |
The email address. | |
userSourceType | The source of the user. Valid values: build_in, ding_talk, ad, ldap, and idp_auto_build. |
userSourceId | The ID of the source. |
status | The status of the user. Valid values: enabled and disabled. |
accountExpireTime | The time when the account expires. The value is a UNIX timestamp. Unit: milliseconds. |
registerTime | The time when the user was registered. The value is a UNIX timestamp. Unit: milliseconds. |
lockExpireTime | The time when the account is unlocked. The value is a UNIX timestamp. Unit: milliseconds. |
updateTime | The time when the account was last updated. The value is a UNIX timestamp. Unit: milliseconds. |
description | The description. |
2. App User
The following field is available in the AppUser model. If you want to use the following field in an expression, you can add the appUser. prefix to the field. The field is then referenced as appUser.username.
Field | Description |
username | The username of the application account. |
3. IdP User
The IdP User model is used to synchronize data between IDaaS and an identity provider. For example, if you want to use the DingTalk workplace field in an expression, you can add the idpuser. prefix to the field. The field is then referenced as idpuser.work_place.
For more information about the fields in the IdP model, see the documentation of the relevant identity provider. For example, if the IdP is DingTalk, see the View user details topic of the DingTalk documentation.
Functions
The following table describes the available common functions and their descriptions.
Function | Definition | Description |
Append | Append(str1, str2, ..., strn) | Concatenates input strings into a new string, which is the result of |
Join | Join(source1, source2, ..., sourceN, separator) | Combines multiple source values into a string. The source values are separated by a delimiter. |
Coalesce | Coalesce(source1, source2, ..., sourceN, defaultValue) | Returns the first non-null value among the specified arguments. If all arguments are null, Coalesce returns NULL. A non-null argument is greater than 0 in length. |
IFF | IFF(condition, whenTrue, whenFalse) | Performs a ternary operation. The IIF function returns whenTrue if the condition evaluates to TRUE, and returns whenFalse if the condition evaluates to FALSE. |
IsNull | IsNull(value) | Returns true if the value is null. |
IsNullOrEmpty | IsNullOrEmpty(value) | Returns true if the value is null or an empty string. |
Now | Now() | Returns the current date and time in UTC in the yyyy-MM-dd'T'HH:mm:ssXXX format. |
StringReplace | StringReplace("hello $VariableName", VariableName, ReplaceString) | Replaces characters or substrings with other characters or substrings in the desired string. |
Trim | Trim(source) | Removes all leading and trailing spaces from the source string. |
ToLower ToUpper | ToLower(source) ToUpper(source) | Converts the source string to uppercase or lowercase. |
Substring | Substring(source, fromIndex, endIndex) | Returns a substring of the source string. The index of the substring is [fromIndex, endIndex]. |
SubstringBefore | SubstringBefore(source, subString) | Returns a new string that is a substring of the given string. |
Examples
Scenario | Sample expression |
Append "@example.com" to a username. | Append(user.username, "@example.com") |
Return the specified email address. Return a mobile number if no email address is specified. | Coalesce(user.email, user.phoneNumber) |
Use the default mobile number if no mobile number is specified. | IFF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber) |
Concatenate the country code of a mobile number and the mobile number with a hyphen (-). | Join(user.phoneRegion, user.phoneNumber, "-") |
Return a custom welcome message that contains the display name of a user. | StringReplace("hello $DisplayName", "$DisplayName", user.displayName) |
Replace the middle four digits of a mobile number with asterisks (*). | Append( SubString(user.phoneNumber, 0, 4), "****", SubString(user.phoneNumber, 8, 10) ) |
Extract the username from an email address. | SubstringBefore(user.email, "@") |