Como usar expressões de campos de conta - Identity as a Service: Central de Documentação do Alibaba Cloud

O IDaaS possui um mecanismo de expressões integrado que transforma atributos de usuário antes do envio a aplicativos ou provedores de identidade. Use expressões em aplicativos SAML e OpenID Connect (OIDC) para adicionar ou modifique parâmetros nas informações de usuário retornadas — por exemplo, para concatenar campos, avaliar condições ou reformatar valores. Você também pode usar expressões ao configurar mapeamentos de campos para sincronização com provedores de identidade (IdP).

Para mais informações, consulte Regras de mapeamento de declaração de atributos SAML, Regras de mapeamento de valores de extensão id_token OIDC e Gerencie campos de conta.

Uma expressão consiste em duas partes:

Modelos — fontes de dados, incluindo User (contas do IDaaS) e AppUser (contas de aplicativo)
Funções — operações aplicadas aos valores dos campos do modelo

Modelos

User

O modelo User representa contas do IDaaS. Referencie campos usando user.<fieldId>, como user.username ou user.lockExpireTime.

Nome de exibição do campo	ID do campo	Tipo de dado	Obrigatório	Único	Permissões do usuário	Descrição
Account ID	userId	String	Não	Sim	Visível	O ID do usuário.
Username	username	String	Sim	Sim	Visível	O nome de usuário.
Display name	displayName	String	Não	Não	Editável	O nome de exibição do usuário.
Email	email	String	Não	Sim	Editável	O endereço de e-mail.
Mobile phone	phoneNumber	Number	Não	Sim	Editável	O número de telefone.
Phone area code	phoneRegion	Number	Não	Não	Editável	O código de área. Para a China, o valor é `86` (sem `00` ou `+`).
External ID	userExternalId	String	Não	Sim	Visível	O ID externo do usuário.
Source type	userSourceType	String	Não	Não	Visível	Valores válidos: `build_in` (nativo), `ding_talk` (DingTalk), `ad` (AD), `ldap` (LDAP), `we_com` (WeCom), `lark` (Lark), `idp_auto_build` (criado automaticamente por um IdP).
Source ID	userSourceId	String	Não	Não	Visível	O ID da fonte.
Account status	status	String	Não	Não	Visível	Valores válidos: `enabled`, `disabled`.
Description	description	String	Não	Não	Visível	A descrição.
Account expiration time	accountExpireTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.
Account registration time	registerTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.
Password expiration time	passwordExpireTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.
Lock expiration time	lockExpireTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.
Creation time	createTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.
Update time	updateTime	Number	Não	Não	Visível	Timestamp UNIX em milissegundos.

Exemplo de JSON do modelo User

{
  "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",
  "customFieldMap": {
    "place": { "fieldName": "place", "fieldValue": "beijing" },
    "age": { "fieldName": "age", "fieldValue": "18" }
  },
  "customFields": [
    { "fieldName": "place", "fieldValue": "beijing" },
    { "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",
  "groups": [
    { "groupId": "group_jp6al4sn4n4wjgjxxxxxx", "groupName": "group1", "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx" },
    { "groupId": "group_vavikcxewkf5h3oxxxxxx", "groupName": "group2", "groupExternalId": "group_vavikcxewkf5h3oxxxxxx" }
  ]
}

AppUser

O modelo AppUser representa contas de aplicativo. Referencie campos usando appUser.<property>, como appUser.username.

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

IdP User

Use o modelo IdP User para mapeamentos de campos durante a sincronização com um provedor de identidade. Por exemplo, o campo de localização do escritório no DingTalk é idpUser.work_place. Para consultar os campos disponíveis, verifique a documentação do seu provedor de identidade, como o Documento de Ajuda do DingTalk - Detalhes do Usuário.

Importante

Em provedores de identidade OIDC (consulte Anexar um provedor de identidade OIDC), ao usar expressões no recurso de anexação automática, o prefixo idpUser. aplica-se apenas aos campos sub, phoneNumber e email do id_token (por exemplo, idpUser.sub). Para todos os outros campos, use o prefixo idpUser.rawUserInfo. (por exemplo, idpUser.rawUserInfo.aud).

Funções

As funções operam sobre valores dos campos do modelo e estão agrupadas por categoria abaixo.

Funções de string

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
Append	`Append(str1, str2, ..., strN)`	String	Concatena parâmetros em uma nova string. Equivalente a `str1 + str2 + ...`.	`Append("str1", "@example.com")` → `str1@example.com`
Join	`Join(source1, source2, ..., sourceN, separator)`	String	Une vários valores de origem em uma única string usando o separador especificado.	`Join("str1", "str2", 123, "-")` → `str1-str2-123`
StringReplace	`StringReplace(source, target, replacement)`	String	Substitui `target` em `source` por `replacement`.	`StringReplace("hello $str", "$str", "world")` → `hello world`
Trim	`Trim(source)`	String	Remove espaços em branco no início e no fim.	`Trim(" 123 ")` → `123`
TrimLeft	`TrimLeft(source)`	String	Remove apenas espaços em branco iniciais.	`TrimLeft(" 123 ")` → `123`
TrimRight	`TrimRight(source)`	String	Remove apenas espaços em branco finais.	`TrimRight(" 123 ")` → `123`
ToLower	`ToLower(source)`	String	Converte todo o texto para minúsculas.	`ToLower(" Abc ")` → `abc`
ToUpper	`ToUpper(source)`	String	Converte todo o texto para maiúsculas.	`ToUpper(" Abc ")` → `ABC`
Substring	`Substring(source, fromIndex, endIndex)`	String	null	Retorna a substring de `fromIndex` (inclusivo) até `endIndex` (exclusivo). Se `fromIndex` for negativo, será tratado como 0. Retorna null se qualquer índice não for inteiro.	`Substring("0123456", 1, 5)` → `1234`; `Substring("0123456", -1, 7)` → `0123456`; `Substring("0123456", "1", 5)` → null
SubstringBefore	`SubstringBefore(source, subString)`	String	null	Retorna a parte de `source` anterior à primeira ocorrência de `subString`. Retorna null se `subString` não for encontrado.	`SubstringBefore("test@example@com", "@")` → `test`
Split	`Split(source, separator)`	Array	Divide uma string em um array de substrings usando o separador especificado.	`Split("str1,str2,str3", ",")` → `Array(str1, str2, str3)`
Contains	`Contains(str1, str2)`	Boolean	Retorna true se `str1` contiver `str2`; caso contrário, retorna false.	`Contains("test", "t")` → `true`; `Contains("test", "a")` → `false`
StartsWith	`StartsWith(str1, str2)`	Boolean	Retorna true se `str1` começar com `str2`. Aceita exatamente dois parâmetros.	`StartsWith("test", "t")` → `true`; `StartsWith("test", "e")` → `false`
Equals	`Equals(str1, str2[, ignoreCase])`	Boolean	Compara duas strings quanto à igualdade. Passe `true` como terceiro parâmetro para comparação sem distinção entre maiúsculas e minúsculas ou `false` para diferenciar maiúsculas de minúsculas (padrão).	`Equals("test", "Test")` → `false`; `Equals("test", "Test", true)` → `true`

Funções de condição

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
IIF	`IIF(condition, whenTrue, whenFalse)`	Any	Retorna `whenTrue` se `condition` for verdadeira; caso contrário, retorna `whenFalse`.	`IIF(true, 1, 2)` → `1`; `IIF(false, 1, 2)` → `2`
IsNull	`IsNull(value)`	Boolean	Retorna true se `value` for null ou ausente. Retorna false para strings vazias.	`IsNull(null)` → `true`; `IsNull("")` → `false`
IsNullOrEmpty	`IsNullOrEmpty(value)`	Boolean	Retorna true se `value` for null ou uma string vazia.	`IsNullOrEmpty(user.email)` → `true` se o e-mail for null ou ausente; `IsNullOrEmpty("")` → `true`
Coalesce	`Coalesce(source1, source2, ..., sourceN, defaultValue)`	Any	null	Retorna o primeiro parâmetro não vazio. Um valor não vazio não é null e tem comprimento maior que 0. Retorna null se todos os parâmetros estiverem vazios.	`Coalesce("", user.phoneRegion, "86")` → `86` se o código de área do telefone estiver vazio ou ausente
Or	`Or(condition1, condition2, ..., conditionN)`	Boolean	Retorna true se qualquer condição for verdadeira.	`Or(true, false)` → `true`; `Or(false, false)` → `false`
And	`And(condition1, condition2, ..., conditionN)`	Boolean	Retorna true somente se todas as condições forem verdadeiras.	`And(true, false)` → `false`; `And(true, true, true)` → `true`
xOr	`xOr(condition1, condition2)`	Boolean	Aceita exatamente duas condições. Retorna true se apenas uma condição for verdadeira e false se ambas forem iguais.	`xOr(true, false)` → `true`; `xOr(true, true)` → `false`; `xOr(false, false)` → `false`

Funções de array

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
Array	`Array(source1, source2, ...)`	Array	Combina valores em um array. Os valores podem ser do tipo Object.	`Array(1, 2, 3)` → `[1, 2, 3]`
ArrayAdd	`ArrayAdd(array, element)`	Array	Adiciona um elemento a um array.	`ArrayAdd(Array(), "test")` → `["test"]`
ArrayMap	`ArrayMap($ArrayObject, __item.ObjectProperty)`	Array	Cria um novo array extraindo uma propriedade específica de cada objeto em um array.	`ArrayMap(user.groups, __item.groupId)` → `["groupId1","groupId2","groupId3"]`
ArrayIndex	`ArrayIndex(array, n)`	Any	Retorna o elemento no índice `n`. O índice começa em 0.	`ArrayIndex(Array(1, 2, 3), 0)` → `1`
ArrayJoin	`ArrayJoin(array, separator)`	String	Une elementos de um array em uma string usando o separador especificado.	`ArrayJoin(Array(1, 2, 3), "-")` → `1-2-3`

Funções de objeto

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
Object	`Object(key1, value1, key2, value2, ...)`	Object	Cria um objeto a partir de pares chave-valor. Suporta zero ou um número par de parâmetros.	`Object("key1", "value1", "key2", "value2")` → `{"key1": "value1", "key2": "value2"}`
ObjectIndex	`ObjectIndex(object, "propertyName")`	Any	Retorna o valor da propriedade especificada. `ObjectIndex(user, "username")` equivale a `user.username`.	—
ObjectToJsonString	`ObjectToJsonString(object)`	String	Converte um objeto em uma string JSON.	`ObjectToJsonString(user.groups)` → Representação em string JSON

Funções de tempo

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
Now	`Now()`	String	Retorna a data e hora UTC atuais no formato `yyyy-MM-dd'T'HH:mm:ssXXX`.	Saída: `2021-11-01T09:52:11Z`
CurrentTimeMillis	`CurrentTimeMillis()`	Number	Retorna o timestamp UNIX atual em milissegundos.	—

Funções de número de telefone

Tanto ExtractPhoneRegion quanto ExtractPhoneNumber usam códigos de país ISO 3166 Alpha-2 (por exemplo, CN, US, TW). Consulte o padrão Códigos de País ISO 3166 para obter a lista completa.

Os parâmetros funcionam da seguinte maneira, dependendo do formato do número de telefone de origem:

Número já com prefixo + (por exemplo, +86131xxxxx000): passe apenas source. A função extrai o código de área do prefixo.
Número com código de área, mas sem prefixo + (por exemplo, 86131xxxxx000): passe source, defaultRegion e defina autoAppendPlusSignal como true.
Número sem código de área (por exemplo, 131xxxxx000): passe source, defaultRegion e defina autoAppendPlusSignal como false.

Função	Assinatura	Tipo de retorno	Descrição
ExtractPhoneRegion	`ExtractPhoneRegion(source[, defaultRegion, autoAppendPlusSignal])`	String	Extrai o código de área de um número de telefone.
ExtractPhoneNumber	`ExtractPhoneNumber(source[, defaultRegion, autoAppendPlusSignal])`	String	Extrai o número de telefone sem o código de área.

Exemplos de ExtractPhoneRegion

Formato do número de telefone	Expressão	Valor de retorno
`+86131xxxxx000`, `+86 131xxxxx000` ou `+86-131xxxxx000`	`ExtractPhoneRegion(idpUser.mobile)`	`86`
`86131xxxxx000`, `86 131xxxxx000` ou `86-131xxxxx000`	`ExtractPhoneRegion(idpUser.mobile, "CN", true)`	`86`
`131xxxxx000`	`ExtractPhoneRegion(idpUser.mobile, "CN", false)`	`86`

Exemplos de ExtractPhoneNumber

Formato do número de telefone	Expressão	Valor de retorno
`+86131xxxxx000`, `+86 131xxxxx000` ou `+86-131xxxxx000`	`ExtractPhoneNumber(idpUser.mobile)`	`131xxxxx000`
`86131xxxxx000`, `86 131xxxxx000` ou `86-131xxxxx000`	`ExtractPhoneNumber(idpUser.mobile, "CN", true)`	`131xxxxx000`
`131xxxxx000`	`ExtractPhoneNumber(idpUser.mobile, "CN", false)`	`131xxxxx000`

Funções específicas do SAML

Função	Assinatura	Tipo de retorno	Descrição	Exemplo
SamlArray	`SamlArray(Array())`	Atributo SAML	Disponível apenas para SSO SAML. Formata um array como um atributo SAML com múltiplos elementos `AttributeValue`.	`SamlArray(Array("group1","group2"))` → Resposta SAML com elementos `<saml2:AttributeValue>` separados para `group1` e `group2`

Expressões comuns

Os exemplos a seguir usam os dados de usuário de amostra abaixo. Copie e adapte essas expressões diretamente.

Dados de usuário de amostra:

user.username: name_001
user.displayName: displayname_001
user.email: xxxxx@example.com
user.phoneRegion: 86
user.phoneNumber: 333xxxx3333
user.groups: dois grupos com IDs group_jp6al4sn4n4wjgjxxxxxx e group_vavikcxewkf5h3oxxxxxx

Objetivo	Expressão	Saída
Adicionar um domínio ao nome de usuário	`Append(user.username, "@example.com")`	`name_001@example.com`
Retornar o e-mail se definido; caso contrário, usar o número de telefone	`Coalesce(user.email, user.phoneNumber)`	`xxxxx@example.com`
Usar um número de telefone padrão quando o campo estiver vazio	`IIF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber)`	`333xxxx3333`
Concatenar o código de área e o número de telefone com um hífen	`Join(user.phoneRegion, user.phoneNumber, "-")`	`86-333xxxx3333`
Criar uma mensagem de boas-vindas com o nome de exibição	`StringReplace("hello $DisplayName", "$DisplayName", user.displayName)`	`hello displayname_001`
Mascarar os quatro dígitos centrais do número de telefone	`Append(SubString(user.phoneNumber, 0, 4), "****", SubString(user.phoneNumber, 8, 10))`	`333x****33`
Extrair o nome de usuário de um endereço de e-mail	`SubstringBefore(user.email, "@")`	`xxxxx`
Formatar o campo de e-mail como um array compatível com SCIM	`Array(Object("email", user.email, "type", "work", "primary", true))`	`[{"email":"xxxxx@example.com","type":"work","primary":true}]`
Obter uma lista de IDs de grupo para um usuário	`ArrayMap(user.groups, __item.groupId)`	`["group_jp6al4sn4n4wjgjxxxxxx","group_vavikcxewkf5h3oxxxxxx"]`