This topic will walk you through Ironclad's supported user attributes. This includes how to create a custom attribute schema and build fields using custom attributes.
SCIM, or the System for Cross-Domain Identity Management specification, is an open standard designed to make identity management in cloud-based applications, such as Ironclad, easier. It includes a defined schema for users and groups to reduce complexity. In addition to supporting this defined schema for user attributes, Ironclad also supports custom attributes if needed. The two main use cases for using user attributes within Ironclad are:
-
Leveraging the "UserAttribute()" formula in Workflow Designer to access those attributes to populate fields in a workflow.
-
Determining hierarchies for approvers and signers via user reference chains.
Ironclad supports the standard SCIM Core Resources and Extensions attributes. For more information on SCIM endpoints in Ironclad, refer to our Developer Hub.
User Resource Schema
The first core schema is the user reference schema, which often includes the basic information that represents the user. Some attributes are singular, whereas others can have multiple values.
Namespace: “urn:ietf:params:scim:schemas:core:2.0:User”
Singular Attributes
- userName
- name (formatted, familyName, givenName, middleName, honorificSuffix)[This is a complex attribute that is structured as an object. In the payload, this information is formatted as a JSON object with keys being name .familyName, name.givenName, etc.]
- displayName
- nickName
- profileUrl
- title
- userType
- preferredLanguage
- locale
- timezone
- active
- password
Attributes with Multiple Values
- emails (value, display, type, primary)
- phoneNumbers (value, display, type, primary)
- ims (value, display, type, primary)
- photos (value, display, type, primary)
- address (formatted, streetAddress, locality, region, postalCode, country, type)
- groups (value, $ref, display, type)
- entitlements (value, display, type, primary)
- role (value, display, type, primary)
Enterprise User Schema
The enterprise user schema can be used to extend the user schema to meet larger company needs, such as information about what organization or function a user belongs to (or acts on behalf of).
Namespace: “urn:ietf:params:scim:schemas:extension:enterprise:2.0:User”
Attributes
- employeeNumber
- costCenter
- organization
- division
- department
- manager (value, $ref, displayName)
Create a Custom Attribute Schema
Ironclad also supports the use of custom attributes. Often, company-specific information is needed for use cases such as reporting (mapping a user to a legal entity) or driving approvals (assigning the legal approval to different groups of lawyers depending on the user’s region).
This section provides an outline of how to create additional attributes to power the metadata and logic of your workflow configurations. You only need to create these attributes once, then they can be used similarly to the user reference and enterprise attributes above. To learn more about mapping to a custom attribute from Okta, refer to SCIM in Ironclad with Okta.
Prerequisites
- Generate an API Token in Ironclad by navigating to Company Settings > API.
- Confirm the Base URLs.
- Production {{baseUrl}} = ironcladapp.com
- Demo {{baseUrl}} = demo.ironcladapp.com
- Example payload, where the first camelCase line of each object is the custom attribute that is being created.
{
“managerName”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “The name of the User’s manager.“,
“multiValued”: false,
“mapping”: {
“type”: “direct”,
“key”: “managerName”
}
},
“managerEmail”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “The email/username of the SCIM resource representing the User’s manager.“,
“multiValued”: false,
“internalAttributeType”: {
“type”: “UserChain”,
“maxDepth”: 50,
“referencedAttribute”: [
“userName”
]
},
“mapping”: {
“type”: “direct”,
“key”: “managerEmail”
}
},
“legalEntities”: {
“type”: “complex”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “Legal entities represented by the User.“,
“multiValued”: true,
“subAttributes”: {
“usEntity”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “Legal entity for the United States.“,
“multiValued”: false
},
“japanEntity”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “Legal entity for Japan.“,
“multiValued”: false
}
}
},
“managementLevel”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “The management level of the User.“,
“multiValued”: false,
“mapping”: {
“type”: “direct”,
“key”: “managementLevel”
}
},
“region”: {
“type”: “string”,
“required”: false,
“returned”: “default”,
“caseExact”: false,
“mutability”: “readWrite”,
“uniqueness”: “none”,
“description”: “The User’s region.“,
“multiValued”: false,
“mapping”: {
“type”: “direct”,
“key”: “region”
}
}
}
Method 1: Postman
- Create Attributes
- POST a JSON payload (example above) to ”https://{{baseUrl}}/public/api/v1/custom-attributes”
- Confirm Custom Attributes
- GET to ”https://{{baseUrl}}/public/api/v1/custom-attributes”
Method 2: cURL
- Create Attributes
- Assuming the JSON payload (example above) has been saved to a file at $HOME/custom-attributes.json
- Confirm Custom Attributes
Create Attributes
export TOKEN = "..."
export BASE_URL="{{baseUrl}}"
curl --header "Authorization: Bearer $TOKEN" \
"https://$BASE_URL/public/api/v1/custom-attributes" \
-X POST \
--header "Content-Type: application/json" \
--data @$HOME/custom-attributes.json
Confirm Custom Attributes
export TOKEN="..."
export BASE_URL="{{baseUrl}}"
export SCHEMA_URI="urn:ietf:params:scim:schemas:extension:ironclad:2.0:User"
curl --header "Authorization: Bearer $TOKEN" \
"https://$BASE_URL/scim/v2/Schemas/$SCHEMA_URI"
Build Fields Using Custom Attributes
Example Enterprise Attribute Formula Field in Workflow Designer
Example Custom Attribute Formula Field in Workflow Designer