SAML Attribute Statements let you control which user attributes are included in a Security Assertion Markup Language (SAML) assertion and how their values are formatted. This page describes the supported value types and provides concrete examples of the resulting SAML XML output.
Supported value types
Each Attribute Statement entry maps an attribute name to a value. The value can be a variable, a constant, or an expression.
| Type | Value | Description |
|---|---|---|
| Variable | user.username | Username |
| Variable | user.displayName | Display name |
| Variable | user.phoneNumber | Mobile phone number (no country code) |
| Variable | user.phone (expired) | Mobile phone number (no country code) — deprecated |
| Variable | user.email | Email address |
| Variable | user.status | User status. Valid values: enabled, disabled |
| Variable | user.primaryOrganizationalUnitId | ID of the user's primary organizational unit |
| Variable | ObjectToJsonString(user.organizationalUnits) | All organizational units the user belongs to, as a JSON array string |
| Variable | ArrayJoin(ArrayMap(user.organizationalUnits, __item.organizationalUnitId), ",") | IDs of all organizational units the user belongs to, as a comma-separated string |
| Variable | ObjectToJsonString(user.groups) | All groups the account belongs to, as a JSON array string |
| Variable | ArrayJoin(ArrayMap(user.groups, __item.groupId), ",") | IDs of all groups the account belongs to, as a comma-separated string |
| Variable | ArrayJoin(ArrayMap(user.groups, __item.groupExternalId), ",") | External IDs of all groups the account belongs to, as a comma-separated string |
| Variable | ObjectToJsonString(user.customFields) | All custom fields, as a JSON array string |
| Variable | user.customFieldMap.$fieldname$.fieldValue | Value of a specific custom field. Replace $fieldname$ with the field name. |
| Variable | appUser.username | Application account name |
| Constant | "your-value" | A fixed string. Enclose the value in double quotation marks. |
| Expression | (advanced) | Flexibly concatenate and transform values. See Advanced account field expressions. |
SAML parsing examples
The examples below use the following user object. Each example shows the expression configured in the Attribute Statements panel and the resulting SAML XML.
Sample user object
{
"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": "AD",
"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"
}
]
}Configuration panel
Example 1: All organizational units as a JSON array
Expression: ObjectToJsonString(user.organizationalUnits)
SAML output:
<saml2:Attribute Name="organizationalUnits" 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">
[{"organizationalUnitId":"ou_sdfadtaaxxxxxx","organizationalUnitName":"AD","primary":false},{"organizationalUnitId":"ou_werttxxxxxx","organizationalUnitName":"name_002","primary":true}]
</saml2:AttributeValue>
</saml2:Attribute>Example 2: Organizational unit IDs as a comma-separated string
Expression: ArrayJoin(ArrayMap(user.organizationalUnits, __item.organizationalUnitId), ",")
SAML output:
<saml2:Attribute Name="organizationalUnitIds" 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">
ou_sdfadtaaxxxxxx,ou_werttxxxxxx
</saml2:AttributeValue>
</saml2:Attribute>Example 3: All groups as a JSON array
Expression: ObjectToJsonString(user.groups)
SAML output:
<saml2:Attribute Name="groups" 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">
[{"groupId":"group_jp6al4sn4n4wjgjxxxxxx","groupName":"group1","groupExternalId":"group_jp6al4sn4n4wjgjxxxxxx"},{"groupId":"group_vavikcxewkf5h3oxxxxxx","groupName":"group2","groupExternalId":"group_vavikcxewkf5h3oxxxxxx"}]
</saml2:AttributeValue>
</saml2:Attribute>Example 4: Group IDs as a comma-separated string
Expression: ArrayJoin(ArrayMap(user.groups, __item.groupId), ",")
SAML output:
<saml2:Attribute Name="groupIds" 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">
group_jp6al4sn4n4wjgjxxxxxx,group_vavikcxewkf5h3oxxxxxx
</saml2:AttributeValue>
</saml2:Attribute>Example 5: Group external IDs as a comma-separated string
Expression: ArrayJoin(ArrayMap(user.groups, __item.groupExternalId), ",")
SAML output:
<saml2:Attribute Name="groupExternalIds" 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">
group_jp6al4sn4n4wjgjxxxxxx,group_vavikcxewkf5h3oxxxxxx
</saml2:AttributeValue>
</saml2:Attribute>Example 6: Group IDs as multiple attribute values
SamlArray outputs each element as a separate <saml2:AttributeValue> element rather than a single string.
Expression: SamlArray(ArrayMap(user.groups, __item.groupId))
SAML 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">
group_jp6al4sn4n4wjgjxxxxxx
</saml2:AttributeValue>
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
group_vavikcxewkf5h3oxxxxxx
</saml2:AttributeValue>
</saml2:Attribute>Example 7: All custom fields as a JSON array
Expression: ObjectToJsonString(user.customFields)
SAML output:
<saml2:Attribute Name="customFields" 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">
[{"fieldName":"place","fieldValue":"beijing"},{"fieldName":"age","fieldValue":"18"}]
</saml2:AttributeValue>
</saml2:Attribute>Example 8: A single custom field value
Expression: user.customFieldMap.age.fieldValue
SAML output:
<saml2:Attribute Name="age" 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">
18
</saml2:AttributeValue>
</saml2:Attribute>What's next
Advanced account field expressions — learn how to use expressions to concatenate, transform, and conditionally map attribute values.