How to use account field expressions - Identity as a Service: Central de Documentação do Alibaba Cloud

Este tópico descreve como usar expressões avançadas de campos da conta no motor de expressões integrado do IDaaS, incluindo descrições dos campos do modelo, descrições das funções e exemplos de referência.

Visão geral

O IDaaS inclui um motor de expressões integrado. Em aplicativos SAML e OIDC, use expressões avançadas para adicionar parâmetros às informações do usuário retornadas. Use expressões quando um aplicativo de destino exigir um parâmetro adicional que precise de transformação, concatenação ou avaliação condicional.

Use expressões também para atribuir valores personalizados a campos ao configurar mapeamentos de campos sincronizados com um provedor de identidade.

Os exemplos de referência mais adiante neste tópico ajudam a entender rapidamente os casos de uso e os métodos das expressões.

Por exemplo, a configuração de SSO OIDC permite estender as informações retornadas do id_token. No campo Extended Value, insira uma expressão avançada como full_phone para atender a um requisito de processamento específico. Para isso, acesse a página de configuração de SSO do aplicativo OIDC. Na área de configuração do campo de extensão id_token, insira a expressão necessária (como full_phone) na caixa de entrada Extended Value.

Para mais informações sobre o uso, consulte Specifications for SAML attribute statement values, OIDC id_token custom field configuration e Gerencie campos.

Uma expressão tem duas partes:

Um modelo, que pode ser User (para uma conta IDaaS) ou AppUser (para uma conta do aplicativo).
Uma função, que representa a lógica de execução.

Modelos

1. User

Referencie os seguintes campos no User model do IDaaS com uma sintaxe como user.username ou user.lockExpireTime.

Field Display Name	Field ID	Data Type	Required	Unique	User Permissions	Descrição
ID da conta	userId	String	Não	Sim	Visível	O ID do usuário.
Nome da conta	username	String	Sim	Sim	Visível	O nome do usuário.
Nome de exibição	displayName	String	Não	Não	Editável	O nome de exibição do usuário.
E-mail	email	String	Não	Sim	Editável	O e-mail.
Número de celular	phoneNumber	Número	Não	Sim	Editável	O número de celular.
Código de região do telefone	phoneRegion	Número	Não	Não	Editável	O código de região do celular. Por exemplo, o código da China é "86", sem "00" ou "+".
ID externo	userExternalId	String	Não	Sim	Visível	O ID externo do usuário.
Tipo de origem	userSourceType	String	Não	Não	Visível	Valores válidos: build_in: interno. ding_talk: DingTalk. ad: AD. ldap: LDAP. we_com: WeCom. lark: Lark. idp_auto_build: criação automática do IdP.
ID da origem	userSourceId	String	Não	Não	Visível	O ID da origem.
Status da conta	status	String	Não	Não	Visível	Valores válidos: enabled: ativado. disabled: desativado.
Descrição	description	String	Não	Não	Visível	Descrição.
Data e hora de expiração da conta	accountExpireTime	Número	Não	Não	Visível	A data e hora de expiração da conta, como um timestamp UNIX em milissegundos.
Data e hora de registro	registerTime	Número	Não	Não	Visível	A data e hora de registro da conta, como um timestamp UNIX em milissegundos.
Data e hora de expiração da senha	passwordExpireTime	Número	Não	Não	Visível	A data e hora de expiração da senha, como um timestamp UNIX em milissegundos.
Data e hora de expiração do bloqueio	lockExpireTime	Número	Não	Não	Visível	A data e hora de expiração do bloqueio, como um timestamp UNIX em milissegundos.
Data e hora de criação	createTime	Número	Não	Não	Visível	A data e hora de criação, como um timestamp UNIX em milissegundos.
Data e hora de atualize	updateTime	Número	Não	Não	Visível	A data e hora da última atualize das informações do usuário, como um timestamp UNIX em milissegundos.

2. App User

Referencie os seguintes campos no modelo AppUser do IDaaS com uma sintaxe como appUser.username.

Propriedade	Descrição
username	O nome de usuário da conta do aplicativo.

3. IdP User

O modelo IdP User se aplica quando os dados são sincronizados com um provedor de identidade. Por exemplo, o campo de local de trabalho do DingTalk é idpUser.work_place.

Para campos específicos, consulte a documentação relevante do provedor de identidade. Por exemplo, consulte DingTalk documentation - User details.

Importante

Para um provedor de identidade OIDC (consulte Connect to an OIDC identity provider), ao usar uma expressão para vinculação automática, apenas os campos sub, phoneNumber e email em id_token usam o prefixo idpUser., por exemplo, idpUser.sub. Todos os outros campos devem usar o prefixo idpUser.rawUserInfo., por exemplo, idpUser.rawUserInfo.aud.

Funções

Veja as seguintes funções e exemplos:

Função	Sintaxe	Descrição	Exemplo
Append	Append(str1, str2, ..., strn)	Concatena os argumentos de entrada em uma nova string. Equivalente a `str1+str2+...`.	Entrada: `Append("str1", "@example.com")` Saída: `str1@example.com`
Join	Join(source1, source2, ..., sourceN, separator)	Concatena vários valores de origem em uma string, usando um separador entre os valores.	Entrada: `Join("str1", "str2", 123,"-")` Saída: `"str1-str2-123"`
Coalesce	Coalesce(source1, source2, ..., sourceN, defaultValue)	Retorna o primeiro argumento de entrada não vazio. Se todos os argumentos estiverem vazios, retorna null. Um valor não vazio não é nulo e tem comprimento maior que 0.	Entrada: `Coalesce("", user.phoneRegion, "86")` Saída: quando o código de região do telefone está vazio ou ausente, a saída é `86`
IIF	IIF(condition, whenTrue, whenFalse)	Operação ternária. Retorna valores diferentes com base no resultado da condição: whenTrue se a condição for verdadeira e whenFalse se for falsa.	Exemplo 1: Entrada: `IIF(true, 1, 2)` Saída: `1` Exemplo 2: Entrada: `IIF(false, 1, 2)` Saída: `2`
IsNull	IsNull(value)	Retorna true quando o valor é null, ou seja, quando o valor está ausente.	Exemplo 1: Entrada: `IsNull(null)` Saída: `true` Exemplo 2: Entrada: `IsNull("")` Saída: false
IsNullOrEmpty	IsNullOrEmpty(value)	Retorna true quando o valor é null ou uma string vazia.	Exemplo 1: Entrada: `IsNullOrEmpty(user.email)` Saída: quando o e-mail é null ou está ausente, a saída é `true` Exemplo 2: Entrada: `IsNullOrEmpty("")` Saída: `true`
Now	Now()	Retorna uma string com a data e hora UTC atuais no formato yyyy-MM-dd'T'HH:mm:ssXXX.	Saída: 2021-11 01T09:52:11Z
StringReplace	StringReplace("hello $VariableName", "$VariableName", ReplaceString)	Executa uma substituição simples de string.	Entrada: `StringReplace("hello $str", "$str", "world")` Saída: `hello world`
Trim	Trim(source)	Remove espaços em branco no início e no fim de uma string de origem.	Entrada: `Trim(" 123 ")` Saída: `123`
TrimLeft	TrimLeft(source)	Remove espaços em branco à esquerda de uma string de origem.	Entrada: `TrimLeft(" 123 ")` Saída: `123`
TrimRight	TrimRight(source)	Remove espaços em branco à direita de uma string de origem.	Entrada: `TrimRight(" 123 ")` Saída: `123`
ToLower	ToLower(source)	Converte uma string para maiúsculas ou minúsculas.	Entrada: `ToLower(" Abc ")` Saída: `abc`
ToUpper	ToUpper(source)	Converte uma string para maiúsculas.	Entrada: `ToUpper(" Abc ")` Saída: `ABC`
Substring	Substring(source, fromIndex, endIndex)	Retorna uma substring da string, com índices no intervalo [fromIndex, endIndex]. source: obrigatório; uma string de origem de qualquer tipo compatível com a sintaxe. fromIndex: obrigatório; deve ser um número inteiro. Valores não inteiros retornam null. endIndex: obrigatório; deve ser um número inteiro. Valores não inteiros retornam null.	Exemplo 1: Entrada: `Substring("0123456", 1, 5)` Saída: `1234` Exemplo 2: Entrada: `Substring("0123456", -1, 7)` Saída: `0123456` Exemplo 3: Entrada: `Substring("0123456", "1", 5)` Saída: null
SubstringBefore	SubstringBefore(source, subString)	Retorna a substring antes da primeira string de destino correspondida da esquerda para a direita na string de origem. Se não houver string de destino, retorna null. Parâmetros: source: obrigatório; uma string de origem de qualquer tipo compatível com a sintaxe. target: obrigatório; uma string de destino de qualquer tipo compatível com a sintaxe. Valor de retorno: string	Exemplo 1: Entrada: `SubstringBefore("test@example@com", "@")` Saída: `"test"`
Array	Array(source1, source2,...)	Combina vários valores em um array. Os valores podem ser do tipo Object.	Entrada: `Array(1, 2, 3)` Saída: `[1, 2, 3]`
ArrayAdd	ArrayAdd(Array(), "test")	Adiciona um array a um objeto de array.	Entrada: `ArrayAdd(Array(), "test")` Saída: `["test"]`
ArrayMap	ArrayMap($ArrayObject, __item.ObjectProperty)	Obtém um valor de propriedade de um objeto de array para formar um novo array.	Obtenha os IDs dos grupos aos quais o usuário pertence: Entrada: `ArrayMap(user.groups, __item.groupId)` Saída: `["groupId1","groupId2","groupId3"]`
ArrayIndex	ArrayIndex(Array(), n)	Obtém um elemento de array por posição, começando em 0.	Entrada: `ArrayIndex(Array(1,2,3), 0)` Saída: `1`
ArrayJoin	ArrayJoin(Array(), str)	Une um array com uma string.	Entrada: `ArrayJoin(Array(1,2,3), "-")` Saída: `"1-2-3"`
Object	Object(key1, value1, key2, value2, ...)	Cria um Object a partir de pares chave-valor especificados. Aceita zero ou um número par de argumentos.	Entrada `Object("key1", "value1", "key2", "value2")` Saída do objeto correspondente: `{"key1": "value1", "key2": "value2"}`
ObjectIndex	ObjectIndex(user, "username")	Obtém o valor de uma propriedade especificada de um objeto.	O código `ObjectIndex(user, "username")` é equivalente a `user.username`
ObjectToJsonString	ObjectToJsonString(user.groups)	Converte um objeto em uma string json.	-
Contains	Contains(str1,str2)	Verifica se um valor está incluído, retornando true ou false.	Exemplo 1: Entrada: `Contains("test", "t")` Saída: `true` Exemplo 2: Entrada: `Contains("test", "a")` Saída: `false`
Or	Or(true,false,...,true)	Avalia várias condições usando OR. Retorna true se qualquer condição for verdadeira.	Exemplo 1: Entrada: `Or(true,false)` Saída: `true` Exemplo 2: Entrada: `Or(true,true,false)` Saída: `true` Exemplo 3: Entrada: `Or(false,false)` Saída: `false`
And	And(true,false,...,true)	Avalia várias condições usando AND. Retorna false se qualquer condição for falsa.	Exemplo 1: Entrada: `And(true,false)` Saída: `false` Exemplo 2: Entrada: `And(true,true,false)` Saída: `false` Exemplo 3: Entrada: `And(true,true,true)` Saída: `true`
xOr	xOr(true,false,...,true)	Exige exatamente duas condições. Retorna false quando ambas são verdadeiras ou ambas são falsas. Retorna true quando uma condição é verdadeira e a outra é falsa.	Exemplo 1: Entrada: `xOr(true,false)` Saída: `true` Exemplo 2: Entrada: `xOr(true,true)` Saída: `false` Exemplo 3: Entrada: `And(false,false)` Saída: `false`
StartsWith	StartsWith(str1, str2)	Verifica se uma string começa com o valor especificado. Aceita apenas dois parâmetros.	Exemplo 1: Entrada: `StartsWith("test", "t")` Saída: `true` Exemplo 2: Entrada: `StartsWith("test", "e")` Saída: `false`
Split	Split("str1,str2,str3")	Divide uma string e retorna um array.	Exemplo 1: Entrada: `Split("str1,str2,str3",",")` Saída: `Array(str1,str2,str3)`
Equals	Equals(str1,str2)	Compara duas strings quanto à igualdade. Equals(str1,str2). Equals(str1,str2,false) diferencia maiúsculas de minúsculas. Equals(str1,str2,true) não diferencia maiúsculas de minúsculas.	Exemplo 1: Entrada: `Equals("test","Test")` Saída: `false` Exemplo 2: Entrada: `Equals("test","Test",true)` Saída: `true` Exemplo 3: Entrada: `Equals("test","Test",false)` Saída: `false`
CurrentTimeMillis	CurrentTimeMillis()	O timestamp UNIX atual em milissegundos.	-
SamlArray	SamlArray(Array())	Disponível apenas para SSO SAML.	Entrada: `SamlArray(Array("group1","group2"))` Saída da resposta SAML. `<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>` Entrada: `SamlArray(Array("group1","group2"))` Saída da resposta SAML. `</saml2:Attribute>`
ExtractPhoneRegion	ExtractPhoneRegion(source, defaultRegion,autoAppendPlusSignal)	Extrai o código de região de um número de celular. source: número de celular. autoAppendPlusSignal: indica se deve adicionar o sinal + automaticamente. true adiciona; false não. defaultRegion: o país ou região padrão para o código de região do telefone. Para códigos de país e região, use o código Alpha-2 em ISO 3166 Country Codes, como CN, US ou TW. Se um número incluir um código de região precedido por +, não é necessário especificar autoAppendPlusSignal ou deafaultRegion. Se um número incluir um código de região sem +, especifique autoAppendPlusSignal=true e defina defaultRegion como o código de país ou região padrão. Se um número não incluir um código de região e você quiser definir um código de região padrão, especifique autoAppendPlusSignal=false e defina defaultRegion como o código de país ou região padrão.	Exemplo 1: Se o número for `+86131xxxxx000`, `+86 131xxxxx000` ou `+86-131xxxxx000` Entrada: ExtractPhoneRegion(idpUser.mobile) Retorno: 86 Exemplo 2: Se o número for `86131xxxxx000`, `86 131xxxxx000` ou `86-131xxxxx000` Entrada: ExtractPhoneRegion(idpUser.mobile,"CN",true) Retorno: 86 Exemplo 3: Se o número for `131xxxxx000` Entrada: ExtractPhoneRegion(idpUser.mobile,"CN",false) Retorno: 86
ExtractPhoneNumber	ExtractPhoneNumber(source, defaultRegion,autoAppendPlusSignal)	Extrai o número de celular real sem o código de região. source: número de celular. autoAppendPlusSignal: indica se deve adicionar o sinal + automaticamente. true adiciona; false não. defaultRegion: o país ou região padrão para o código de região do telefone. Para códigos de país e região, use o código Alpha-2 em ISO 3166 Country Codes, como CN, US ou TW. Se um número incluir um código de região precedido por +, não é necessário especificar autoAppendPlusSignal ou deafaultRegion. Se um número incluir um código de região sem +, especifique autoAppendPlusSignal=true e defina defaultRegion como o código de país ou região padrão. Se um número não incluir um código de região e você quiser definir um código de região padrão, especifique autoAppendPlusSignal=false e defina defaultRegion como o código de país ou região padrão.	Exemplo 1: Se o número for `+86131xxxxx000`, `+86 131xxxxx000` ou `+86-131xxxxx000` Entrada: ExtractPhoneNumber(idpUser.mobile) Retorno: 131xxxxx000 Exemplo 2: Se o número for `86131xxxxx000`, `86 131xxxxx000` ou `86-131xxxxx000` Entrada: ExtractPhoneNumber(idpUser.mobile,"CN",true) Retorno: 131xxxxx000 Exemplo 3: Se o número for `131xxxxx000` Entrada: ExtractPhoneNumber(idpUser.mobile,"CN",false) Retorno: 131xxxxx000

Exemplos de referência

Cenário	Expressão de exemplo
Obter o nome de usuário e anexar a string fixa "@example.com".	`Append(user.username, "@example.com")`
Retornar o endereço de e-mail quando não estiver vazio. Retornar o número de celular quando o endereço de e-mail estiver vazio.	`Coalesce(user.email, user.phoneNumber)`
Usar um número de celular fixo quando o número de celular estiver vazio.	`IIF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber)`
Unir o código de região do telefone e o número de celular com -.	`Join(user.phoneRegion, user.phoneNumber, "-")`
Retornar uma mensagem de boas-vindas personalizada que contenha o nome de exibição.	`StringReplace("hello $DisplayName", "$DisplayName", user.displayName)`
Ocultar os quatro dígitos centrais de um número de celular com *.	`Append(` `SubString(user.phoneNumber, 0, 4),` `"****",` `SubString(user.phoneNumber, 8, 10)` )
Extrair o nome de usuário de um endereço de e-mail.	`SubstringBefore(user.email, "@")`
Montar um campo de e-mail no formato de array exigido pela especificação SCIM.	`Array(Object("email", user.email, "type", "work", "primary", true))`

Exemplo de json do modelo de usuário:

{
  "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"
}