Template for pushing IdP domain, user, and group metadata
Use this template to model authorization metadata for custom identity providers using the Open Authorization API.
This document includes an example template and notes for designing and publishing a model of your IdP.
A can define additional properties, used to add supplemental metadata to entities in the payload.
Veza will handle federated identities just as those in supported IdPs such as Okta or Entra ID, enabling search and access review for OAA entities alongside the rest of your data catalog.
The metadata payload describes the Identity Provider domain, users, and groups to add to the Veza Access Graph:
For cases where federated IdP entities are granted AWS permissions via IAM roles, the template supports defining assumable roles per-user. Binding a custom IdP user or group to an AWS role or group ARN enables Veza to parse and display the resource-level actions permitted within AWS.
Custom IdP users and groups can be assigned permissions in other OAA applications by setting the principal type to idp in identity_to_permissions in the payload.
For use cases where a custom IdP is federated with another identity provider user identities can be linked between the two. Authorizations granted to the user will also be granted the source identity. The link is created by providing the unique identity ID and provider type as part of the user entry.
For provider_type the following values are accepted:
New in Veza release
2022.2.1
To assign an IdP user or group as the manager of any resource Veza has discovered, list the node type and node id in the entities_owned field, for example:
When parsing the payload, resources in the data catalog will be updated with a SYSTEM_resource_managers tag to enable entitlement reviews. The owner(s) will be suggested as reviewers for Veza Workflows that target an individual named resource with the correct tag.
Users and groups can be mapped to the identity of another user they report to. When configured, the manager will be suggested as a review for Workflow certifications where the assigned reporter is the single query target "named entity."
are the recommended method for adding additional metadata to custom identities and resources.
The custom_property_definition object supports separate property namespaces for each entity type:
Additionally, can be applied to the IdP domain, users, and groups:
Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the remove_tag operation.
After the initial metadata push (which must contain the full payload), you can modify, add, or remove the domain, users, and groups without resubmitting other entities. An is enabled by setting "incremental_change": true in the json_data push payload, and specifying the update operation for each entity to change.
The identity provider object models one instance of the custom IdP:
One domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:
Each IdP user object contains the display name, login email, and identity, along with other identity-related properties:
Add a group by name in the groups section of the template to enable mapping IdP users to those groups:
IdP entities can be granted permissions on custom applications in the
identity_to_permissionssection of the .
Use the apps section to define any applications used to manage access within the identity provider. Apps can be associated with users and groups to model application assignments across your organization.
The apps payload does not accept an owners field. To assign owners to CustomIDPApp entities, see .
Users and Groups can be assigned to an application by setting the app_assignments in the user or group.
The steps to add a custom IdP are the same as for any other OAA provider: you will need to register the new provider and data source, and then push the domain, user, and group descriptions in a JSON payload.
To create a new custom provider using the identity_provider template, POST the name and template type to /providers/custom:
The response will return the custom IdP ID, which you will need when pushing the metadata payload:
Note that the provider id is required in both the path and body of the request. The response will include the new data source ID.
The payload file must contain the provider and data source ID, and the authorization metadata as a single string, for example:
The identity_mapping_configuration parameter defines rules for connecting users in a custom IdP to users from other data sources in the Veza graph.
This is useful when:
The connected data source does not natively support returning information about external identities
A correlation between IdP identities and local users can be assumed based on values like username, email, or another property value.
The identity_mapping_configuration is a top-level property of the Custom IDP submission, and is optional. The mapping configuration can include multiple mappings to connect IDP users to users from different data source types,
each based on its own mappings.
You can update just the identity mappings without resubmitting the entire provider payload by using an incremental update. This is useful when you need to modify only the mapping configuration while leaving other provider data unchanged.
Example curl command to apply the incremental identity mapping update:
Supported transformations:
IGNORE_SPECIAL: Ignore special characters (_, -, .) when matching identities
IGNORE_DOMAIN: Match identities after removing domain portions (e.g., "@example.com")
Set source_property or destination_property to TEMPLATE to match on a constructed value instead of a single property, and put the expression in the corresponding custom_source_property or custom_destination_property field. For example, {FirstInitial | LOWER}{LastName | LOWER} matches a user named John Doe against jdoe. Veza validates the expression when you submit the payload and rejects unknown transformation functions. For the available properties and functions, see .
{
"name": "Custom User",
"assumed_role_arns": {
"identity": [
"arn:aws:iam::123456789012:role/S3Access"
]
},
}{
"name": "Custom User",
"identity": "00001",
"source_identity": {
"identity": "user0001@corp.example.com",
"provider_type": "okta"
}
}Provider
provider_type string
Active Directory
active_directory
Any
any
Azure AD
azure_ad
OAA
custom
Google Workspace
google_workspace
{
"name": "Custom User",
"identity": "000011",
"entities_owned": [
{
"node_type": "S3Bucket",
"id": "arn:aws:s3:::amazon-connect-53f87966654d"
}
]
}{
"name": "Custom User",
"identity": "000013",
"manager_id": "000011"
}domain_properties
Custom property definitions for IdP domain entities.
user_properties
Custom property definitions for IdP user entities.
group_properties
Custom property definitions for IdP group entities.
app_properties
Custom property definitions for IdP app entities.
app_assignment_properties
Custom property definitions for app assignment entities.
"tags": [
{
"key": "Tag1key",
"value": "optional_Tag1Val"
}
]name
string
Name to associate with the provider in Veza.
custom_property_definition
Defines the key and types for properties that can be applied to other objects in the push payload
idp_type
string
Type descriptor for IdP, can be unique or share across multiple IdP (for example ldap, IPA)
name
string
IdP Domain name
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the domain (deprecated, use instead)
{
"name": "willis",
"email": "willis@example.com",
"identity": "000001",
"full_name": "Charles Willis",
"department": "Sales",
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
}
],
"assumed_role_arns": {
"identity": [
"arn:aws:iam::123456789012:role/S3Access"
]
},
"source_identity": {
"identity": "user0001@corp.example.com",
"provider_type": "okta"
},
"tags": [],
"custom_properties": {},
"manager_id": "string",
"entities_owned": {
"node_type": "S3Bucket",
"id": "arn:aws:s3:::amazon-connect-53f87966654d"
}
}name
string
Primary ID for user
email
string
Optional email for user
identity
string
Optional unique identifier for user
"groups": [
{
"name": "developers",
"identity": "developers",
"full_name": null,
"is_security_group": null,
"assumed_role_arns": {
"identity": ["arn:aws:iam::123456789012:role/S3Access"]
},
"tags": [],
"groups": [
{ "group_1_identity": "parent" },
{ "group_2_identity": "parent" }
],
"custom_properties": {}
}
]name
string
IdP group name.
identity
string
Unique ID used for user-group assignments.
full_name
string
Optional display name for group
"apps": [
{
"id": "app1",
"name": "Application 1",
"description": "This is a sample application",
"assumed_role_arns": [
{
"identity": "arn:aws:iam::1234567890:role/DevAppRole"
}
],
"custom_properties": {
"owner_org": "engineering"
},
"tags": []
}
]id
string
App unique identifier.
name
string
IdP app name.
description
string
Description for the App (optional).
{
"name": "willis",
"email": "willis@example.com",
"identity": "cwilliams",
"groups": [
{
"identity": "everyone"
}
],
"custom_properties": {
"region": "NorthAmerica",
"is_contractor": true
},
"app_assignments": [
{
"id": "assignment1",
"name": "Assignment",
"app_id": "app1",
"custom_properties": {
"assigned_on": "2024-12-05T12:42:25+00:00"
}
}
]
}id
string
Assignment unique identifier.
name
string
Display name for the assignment.
app_id
string
Unique ID of the App to assign the identity to.
curl -X POST 'https://<veza_url>/api/v1/providers/custom' \
-H 'authorization: Bearer <access_token>' \
--data-binary '{"name":"SimpleIdP","custom_template":"identity_provider"}'{
"value": {
"id": "532f6fe3-189f-4576-afdf-8913088961e4",
"name": "Simple IdP",
"custom_template": "identity_provider",
"state": "ENABLED",
"application_types": [],
"resource_types": [],
"idp_types": []
}
}curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources' \
-H 'authorization: Bearer <access_token>' \
--data-binary '{"id":"532f6fe3-189f-4576-afdf-8913088961e4", "name":"SimpleDataSource"}'{"value":{"id":"b6a32af6-b854-47e1-8325-e5984f78bb4d","name":"SimpleDataSource"}}curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources/b6a32af6-b854-47e1-8325-e5984f78bb4d:push' \
-H 'authorization: Bearer <access_token>' \
--compressed --data-binary @payload.json{
"id": "532f6fe3-189f-4576-afdf-8913088961e4",
"data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
"json_data": "{\n\"name\":\"CustomIdentityProvider\",\n\"idp_type\": ... "
}{
"identity_mapping_configuration": {
"mappings": [
{
"destination_datasource_type": "OKTA",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_SPECIAL"
]
},
{
"destination_datasource_type": "AZURE_AD",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
},
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
}
]
}
}curl --location 'https://<veza_url>/api/v1/providers/custom/816d6e51-6d6a-4279-ba41-2e7c732be880/datasources/716026b5-4b84-4b2f-a805-b41a6ec69cf3:push' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
"id": "816d6e51-6d6a-4279-ba41-2e7c732be880",
"data_source_id": "716026b5-4b84-4b2f-a805-b41a6ec69cf3",
"json_data": "{\"incremental_change\":true,\"identity_mapping_configuration\":{\"operation\":\"modify\",\"mappings\":[{\"destination_datasource_type\":\"GITHUB_USERS\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"UNIQUE_ID\"}]},{\"destination_datasource_type\":\"SQL_SERVER\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"EMAIL\"}],\"transformations\":[\"IGNORE_DOMAIN\"]}]}}"
}'mappings
IdentityMappingSubmission
List of mappings to create between IDP Users and external data sources
operation
enum
For , the operation to use.
destination_datasource_type
string
Veza Type for the destination data source, GITHUB_USERS, SQL_SERVER, CUSTOM_APPLICATION
destination_datasource_oaa_app_type
string
Optional specifically for mapping to OAA Custom Application to provide a specific App Type
destination_datasources
list
Optional list of destinations for the mapping, each with a type and an optional oaa_app_type. Veza uses this list only when destination_datasource_type is empty; if destination_datasource_type is set, this list is ignored
source_property
enum
IdP User property to match on: UNIQUE_ID, EMAIL, PROPERTY, CUSTOM_PROPERTY, or TEMPLATE
destination_property
enum
Destination User property to match on. Accepts the same values as source_property
custom_source_property
string
With PROPERTY or CUSTOM_PROPERTY, the source property name to match on. With TEMPLATE, the template expression to evaluate on the source
Okta
okta
One Login
one_login
idp_description
string
Any notes to add as entity details (optional)
domains
Domain model
users
Dictionary of CustomIdPUser class instances
groups
Dictionary of CustomIdPGroup class instances
incremental_change
boolean
When true, enables incremental update operations (optional).
identity_mapping_configuration
Configuration for mapping identities between IdP User and other User types from external data sources
tags
Veza Tags list
Any tags to create and apply to the domain.
operation
enum
For incremental updates, the operation to use.
groups
string list
Assign groups memberships by group identity (optional)
full_name
string
Full name to display in Veza
department
string
Department to apply as a searchable property (optional).
is_active
boolean
If available, will be applied to the entity as a searchable property (optional).
is_guest
boolean
If available, will be applied to the entity as a searchable property (optional).
assumed_role_arns
array
AWS IAM roles that can be assumed by the IdP user, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
tags
Veza Tags list
Any tags to create and apply to the user.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the user (deprecated, use custom properties instead)
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
manager_id
string
If the same as another user's identity, that user will be recommended for access reviews. Entity details for the user will be updated on push to include the manager as a searchable property.
entities_owned
Entities Owned array
If another resource is specified by entity type and entity id, a Veza tag will be created on the resource to indicate the owner.
operation
enum
For incremental updates, the operation to use (optional).
source_identity
Optionally link IdP user to user from another IdP for federation use cases.
groups
string list
other custom IdP groups this group is a member of
is_security_group
boolean
Sets the is security group searchable property for the entity in Veza (optional).
tags
Veza Tags list
Any tags to create and apply to the group.
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
dynamic_properties
Dynamic Properties
Up to 5 attributes to apply to the domain. (deprecated, use custom properties instead)
operation
enum
For incremental updates, the operation to use (optional).
assumed_role_arns
array
AWS IAM roles the group can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
source_identity
Optionally link the IdP group to a group from another IdP for federation use cases (optional).
entities_owned
Entities Owned array
Resources to assign this group as manager of (optional).
app_assignments
array
App assignments for this group (optional). See IdP Apps.
assumed_role_arns
array
AWS IAM roles the app can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
custom_properties
Each element of the payload can have property_values, validated against the custom_property_definition.
tags
Veza Tags list
Any tags to create and apply to the group.
operation
enum
For incremental updates, the operation to use (optional).
custom_properties
Each element of the payload can have property_values, validated against the custom_property_definition.
mode
enum
Entities to connect: USERS (the default) connects IdP users to destination users, GROUPS connects IdP groups to destination groups, ROLE_TO_USER connects IdP roles to destination users
property_matchers
IdentityMappingPropertyMatchersSubmission
List of properties to match on
transformations
list enum
Optional transformations to perform on the property values, available values: ignore_special, ignore_domain
custom_destination_property
string
With PROPERTY or CUSTOM_PROPERTY, the destination property name to match on. With TEMPLATE, the template expression to evaluate
{
"name": "My IdP",
"idp_type": "custom_idp",
"domains": [
{
"name": "example.com",
"tags": [],
}
],
"users": [
{
"name": "m_richardson",
"email": "mrichardson@example.com",
"identity": "m_richardson",
"full_name": "Michelle Richardson",
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
},
{
"identity": "developers"
}
],
"assumed_role_arns": [
{
"identity": "arn:aws:iam::123456789012:role/role001"
},
{
"identity": "arn:aws:iam::123456789012:role/role002"
}
],
"tags": [],
},
{
"name": "evargas",
"email": "evargas@example.com",
"identity": "evargas",
"full_name": "Elizabeth Vargas",
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
},
{
"identity": "developers"
},
{
"identity": "sec-ops"
}
],
"assumed_role_arns": [],
"tags": [],
},
{
"name": "willis",
"email": "willis@example.com",
"identity": "c_williams",
"full_name": null,
"department": null,
"is_active": true,
"is_guest": false,
"groups": [
{
"identity": "everyone"
}
],
"assumed_role_arns": [],
"tags": []
}
],
"groups": [
{
"name": "developers",
"identity": "developers",
"full_name": null,
"is_security_group": null,
"tags": []
},
{
"name": "sec-ops",
"identity": "sec-ops",
"full_name": null,
"is_security_group": null,
"tags": []
},
{
"name": "everyone",
"identity": "everyone",
"full_name": "All Company Employees",
"is_security_group": null,
"tags": []
}
],
"identity_mapping_configuration": {
"mappings": [
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
},
{
"destination_datasource_type": "SQL_SERVER",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
}
]
}
}{
"incremental_change": true,
"identity_mapping_configuration": {
"operation": "modify",
"mappings": [
{
"destination_datasource_type": "GITHUB_USERS",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "UNIQUE_ID"
}
]
},
{
"destination_datasource_type": "SQL_SERVER",
"property_matchers": [
{
"source_property": "EMAIL",
"destination_property": "EMAIL"
}
],
"transformations": [
"IGNORE_DOMAIN"
]
}
]
}
}