Template for pushing IdP domain, user, and group metadata
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 authorization 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.
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:
Provider
provider_type string
Active Directory
active_directory
Any
any
AzureAD
azure_ad
OAA
custom
Google Workspace
google_workspace
Okta
okta
One Login
one_login
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."
Custom Identity Provider definitionThe identity provider object models one instance of the custom IdP:
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)
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
identity_mapping_configuration
Configuration for mapping identities between IdP User and other User types from external data sources
IdP DomainOne domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:
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
tags
Any tags to create and apply to the domain.
operation
enum
IdP UsersEach IdP user object contains the display name, login email, and identity, along with other identity-related properties:
name
string
Primary ID for user
email
string
Optional email for user
identity
string
Optional unique identifier for user
groups
string list
Assign groups memberships by group identity (optional)
full_name
string
Full name to display in Veza
department
string list
Any departments 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
Any tags to create and apply to the user.
dynamic_properties
Dynamic Properties
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
manager_id
string
entities_owned
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
source_identity
Optionally link IdP user to user from another IdP for federation use cases.
IdP GroupsAdd a group by name in the groups section of the template to enable mapping IdP users to those groups:
name
string
IdP group name.
identity
string
Unique ID used for user-group assignments.
full_name
string
Optional display name for group
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
custom_properties
Each element of the push payload can have property_values, validated against the custom_property_definition.
dynamic_properties
Dynamic Properties
operation
enum
assumed_role_arns
array
AWS IAM roles the group can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).
IdP AppsUse 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.
id
string
App unique identifier.
name
string
IdP app name.
description
string
Description for the App (optional).
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
operation
enum
Users and Groups can be assigned to an application by setting the app_assignments in the user or group.
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.
custom_properties
Each element of the payload can have property_values, validated against the custom_property_definition.
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:
Identity Mapping ConfigurationThe 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.
mappings
IdentityMappingSubmission
List of mappings to create between IDP Users and external data sources
operation
enum
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
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
Supported transformations:
IGNORE_SPECIAL: Ignore special characters (_, -, .) when matching identities
IGNORE_DOMAIN: Match identities after removing domain portions (e.g., "@example.com")
source_property
enum
IDP User property to match on, unique_id, email, property or custom_property
destination_property
enum
Destination User property to match on, unique_id, email, property or custom_property
custom_source_property
string
When using property or custom_propert the property name to match on
custom_destination_property
string
When using property or custom_propert the property name to match on
Use this template to model authorization metadata for custom identity providers using the .
This document includes an example template and notes for designing and a model of your IdP.
A can define additional properties, used to add supplemental metadata to entities in the payload.
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.
are the recommended method for adding additional metadata to custom identities and resources.
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.
When true, enables operations (optional).
Up to 5 attributes to apply to the domain (deprecated, use instead)
list
For , the operation to use.
list
Up to 5 attributes to apply to the user (deprecated, use instead)
If the same as another user's identity, that user will be recommended for reviews. Entity details for the user will be updated on push to include the manager as a searchable property.
array
For , the operation to use (optional).
Any to create and apply to the group.
Up to 5 attributes to apply to the domain. (deprecated, use instead)
For , the operation to use (optional).
IdP entities can be granted permissions on custom applications in the identity_to_permissions section of the .
Any to create and apply to the group.
For , the operation to use (optional).
For , the operation to use.
OAA Template for Human Resources Information Systems
Use this Open Authorization API template to publish employee metadata for Human Resources Information Systems (HRIS) platforms, typically used by organizations as a single source of truth for employee information.
Unlike an Identity Provider, HR platforms typically do not provide access to other systems. Employee profiles within an HRIS platform are instead used to store important details such as employment status, who individuals report to, department, and country. Veza can use this metadata to:
Correlate employees in the HRIS system with identities in your identity provider (IdP).
Enrich Access Reviews with details about linked HRIS employees for users under review.
The template supports:
A top-level System entity representing the HRIS tenant, organization, or account.
Employee entities representing current and inactive workers
Group entities representing teams, departments, cost centers, or other units to which users are assigned.
Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or id value in the HRIS payload with the IdP entity's Name, Principal Name, or Identity. The matching process checks these fields in the following sequence:
idp_id
email
id
If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the id is used. Veza issues a warning if no matching entity is found.
The account/tenant/etc. that contains the HR information.
URL
String
Y
N
The url for this HRIS system.
Used to represent any person who has been employed by a company.
Employee Number
String
Y
Y
The employee's number that appears in the third-party integration.
Company
String
N
N
The company (or subsidiary) the employee works for.
First Name
String
Y
N
The employee's first name
Last Name
String
Y
N
The employee's last name
Preferred Name
String
N
N
The employee's preferred first name.
Display Full Name
String
N
N
The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.
Canonical Name
String
N
N
The employee's canonical name.
Username
String
N
N
The employee's username that appears in the integration UI.
String
N
Y
The employee's work email.
IDP ID
String
N
N
The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used
Personal Email
String
N
N
The employee's personal email.
Home Location
String
N
N
The employee's home location.
Work Location
String
N
N
The employee's work location.
Cost Center
String
N
N
The cost center ID (Group ID) that the employee is in.
Department
String
N
N
The department ID (Group ID) that the employee is in.
Managers
STRINGLIST
N
N
The employee IDs of the employee's managers.
Groups
STRINGLIST
N
N
The IDs of groups this user is in
Employment Status
String
Y
N
The employment status of the employee. Possible values include - ACTIVE, PENDING, INACTIVE.
Is Active
BOOLEAN
Y
N
If the employee is active or not.
Start Date
TIMESTAMP
N
N
The date that the employee started working. If an employee was rehired, the most recent start date will be returned.
Termination Date
TIMESTAMP
N
N
The employee's termination date.
Job Title
String
N
N
The title of the employee.
Employment Types
STRINGLIST
N
N
The employee's type of employment. Possible values include - FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.
Primary Time Zone
String
N
N
The time zone which the employee primarily lives.
Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.
Group Type
String
Y
N
The type of group, possible values include - TEAM, DEPARTMENT, COST_CENTER, BUSINESS_UNIT, GROUP. This is intended as to not have each type as their own nodes.
Parent
String
N
N
The group ID of its parent group.
JSON schemas for describing custom applications and identity providers
OAA utilizes templates (JSON schema) for structuring authorization and identity metadata, combined with a REST API to register, update and manage the data. Once uploaded, Veza processes the template payload and incorporates the entities and permissions into the Authorization Metadata Graph.
Choosing the appropriate template (application or identity provider) is the first step in creating a new integration with OAA. The template provides a schema for describing the identities, resources, and authorization relationships local to the OAA data source.
A custom application is structured with the following main entities:
Application
Resource
Sub-resource
Sub-resource
Additional sub-resources
Local Users
Local Groups
Local Roles
Local Permissions
Identity-to-permissions binding
A Custom Identity Provider can have the following entities:
Domains
Users
Groups
The Custom IdP template also includes the option to define AWS Roles that are assumable by users and groups and can work with Access Review Workflows to auto-assign resource managers.
Template for pushing custom data source entities and authorization
The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.
The template has three primary elements, covered in detail in this document:
Applications - describes one or more application instances for the custom data source. An application may consist of any of the following entities:
Local Users - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as last_login_at) and can be linked to a source identity like Okta or AzureAD.
Local Groups - defines a group of users, permissions to the application or resources can be assigned to a group.
Local Roles - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.
Resources - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.
Sub Resources - resources can additionally have sub-resources for additional levels of depth.
Permissions - define the applications specific permissions and map to Veza canonical permissions.
Identity to Permissions - Assign local and federated users and groups to permissions or roles to the application and resources.
To use the generic app template, set the template type to application when creating a new data provider:
Define custom properties
In the rest of the payload, for each object that should have additional properties, add a custom_properties array containing the property keys and values:
Validation and Troubleshooting
The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:
Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.
Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.
A 200 OK response may include warnings when matching IDP identities can't be found
The OAA payload must contain at least one top-level application. To model data systems with multiple components (such as different servers or repositories), applications can have resources and sub-resources.
You can also specify more than one application in the OAA payload, each with its own identities, permissions, roles, and resources.
The application_typeis applied to all application resources and identities, and can be used as a filterable property in Veza search.
Optional fields: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:
Any type of data in a JSON payload can be null (not set).
Unused optional arrays and objects should be empty {} or [].
Unused optional strings, numbers, and booleans should be null.
Strings and string lists intended to have constant values (enums) such as identity_type may have a default value when not set.
Each application can contain one or more resources that users can access. Resources can have additional searchable properties and may contain additional sub-resources.
Sub-resources describe additional layers of the application principals can have authorization to, and support the same properties as resources, including additionally nested sub-resources.
An application can have any number of nested sub resources.
* A specific resource type must have only resources with an id, or only resources without an id. When used identity_to_permissions assignments are made by the id value and name functions as a display name.
In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza authorization graph.
If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the connections to another graph entity node_type and id:
The following node types are currently available:
SnowflakeUser
GoogleCloudServiceAccount
AwsIamRole
AzureADEnterpriseApplication
TrinoUser
Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), you can map the principal to the IdP entity name or login email in identities.
Contains any users whose profiles and authentication are handled and stored by the custom application. Local users include their group assignments and any federated identities that should be mapped to the local user:
If the application has any groups, describe each one in the local_groups array.
Group assignments for entities are defined in
identity_to_permissions.
*Must match a discovered Okta or Azure entity Name, PrincipalName, or Identity
Local roles define collections of local permissions that can be assigned to multiple resources. In the applications section, roles are named and mapped to permissions. Role assignments are defined in identity_to_permissions.
permissions
Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.
Canonical permission types are:
DataRead
DataWrite
MetadataRead
MetadataWrite
NonData
DataCreate
DataDelete
MetadataCreate
MetadataDelete
Uncategorized
To better model systems where roles can contain different permissions to different types of resources, permissions can apply to individual resource_types.
When the payload is parsed, individual permissions are created for each type of resource the permission applies to.
Without resource_types specified, the permission will function normally. When directly connecting principals and resources, resource_type is ignored.
identity_to_permissions
Contains an object for each local and IdP identity, and the individual permissions to applications and resources.
You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the identity, and setting the identity_type to idp.
Permissions and role assignments can apply to the entire application or scoped to specific resources.
For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:
Each identity can be either a local_user, local_role, or local_group name, or the identifier of an IdP user, group, or role (email address or group name).
identity_type must be one of (idp (default), local_group, local_role, or local_user.
application_permissions
Binds the identity (IdP entity, local user, or local group) to local permission, by application and resources.
role_assignments
Local roles are assigned to identities in the role_assignments array. Roles can apply to the entire application or only to specific (sub) resources.
Trigger events when there is a change in the integrated HRIS data source.
To enable this payload format, specify the hris custom template when with the API.
The HRIS template supports . After specifying a custom property definition in the payload, you can assign additional attributes to entities. These enable attribute filters for searches and access reviews in Veza, and enrich results with entity metadata unique to the source system or your organization.
For most applications, SaaS Apps and systems the provides a generic and flexible model to capture authorization data for users and groups to the system and its resources.
Intended for modeling sources of users, group, and federated identity metadata, the can be used to enumerate users and groups that access other external applications and resources, similar to built-in connectors for Okta and AzureAD. These users and groups typically represent the top-level corporate identities within an organization.
Additionally, a may describe user-configured key:pair values that can be applied to entities in the payload.
and can be applied to most objects in the OAA payload: the application and its local_users, local_groups, local_roles and resources/sub_resources.
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.
OAA apps need to contain at least one identity, which could be a local_group, local_role, or an IdP identity. Role assignments are made in the section.
name
string
Name of the local role. Primary ID for mapping role to permissions.
unique_id
string
Optional identifier to use for permissions mapping
permissions
array
Permissions associated with the role. Must exist in permissions
tags
array
Specify tags with a key and optional value (optional)
name
string
Native permission name, such as “Push” (used to bind local and IdP identities to native permissions).
permission_type
enum
List of canonical privilege(s) the permission represents.
application_type
enum
Optional list of custom application application_type the permission applies to.
apply_to_sub_resources
bool
To more accurately model applications where permissions should apply to any children of a resource, set TRUE to define the permission as inheritable. This eliminates the need to include the permission at each sub level.
identity
string
Principal name or email address. Maps to IdP login email or group name.
identity_type
string
Sets whether the identity corresponds to an IdP identity, or is local to the application
application_permissions
array
List each local permission available to the identity (must be a valid permission name from the previous section).
role_assignments
array
Any roles assigned to the identity, and the resources they apply to (role/resource must exist in applications).
application
string
Maps to an application name from the first section. Must exist in applications
resources
array
List of application resource or sub-resource names to apply the permission. Must exist in applications
apply_to_application
boolean
Set to true to model environments where permissions apply to the top-level application as well as its resources.
permission
string
Maps to a permission name from the second section. Must exist in permissions
application
string
The application where the role applies. Must exist in applications
role
string
The role name. Must exist in local_roles
apply_to_application
boolean
Set to true to model environments where the role applies to the top-level application and all its resources.
resources
array
List of resources and sub-resources where the role applies. Must exist in applications
name
string
Identifies the app in Veza Search. Used to bind permissions to the application
application_type
string
Applied to all entities within the application as a searchable property. Multiple instances of an application can share the same type
description
string
Any additional notes to show in the entity details, limit 256 characters
custom_properties
dictionary
tags
array
Specify tags with a key and optional value (optional)
local_users
array
local_groups
array
local_roles
array
resources
array
name
string
Resource name. Primary ID for mapping users to individual resource permissions.
id
string
Optional value to use as the unique ID, instead of the resource name*.
resource_type
string
Searchable label for the resource type. The application entity details in Veza will show the contained resource types as properties.
description
string
Shown in Veza entity details, max 255 characters.
custom_properties
dictionary
sub_resources
array
Used for additional resource layers, nested data sources, services, and so on.
connections
Optional list of resource connections to external entities discovered by Veza
tags
array
Specify tags with a key and optional value (optional)
name
string
Name of the local user, shown in the Veza UI.
unique_id
string
Optional identifier to use for mapping users to groups, roles, and permissions.
identities
identities array
Maps the user to a federated identity by login email or group name. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Must match a discovered Okta, Google Workspace, or Azure AD entity Name, PrincipalName, or Identity.
groups
groups array
is_active
boolean
If activity state is available from the provider, use this field to make the value available as a searchable property (optional).
created_at
RFC3339 string
User creation date (optional), for example 1996-12-19T16:39:57-08:00
last_login_at
RFC3339 string
(optional)
password_last_changed_at
RFC3339 string
(optional)
deactivated_at
RFC3339 string
(optional)
custom_properties
dictionary
tags
Specify tags with a key and optional value (optional)
name
string
Name of the local group. Primary ID for mapping group to permissions.
unique_id
string
Optional identifier to use for permissions mapping
custom_properties
dictionary
identities
array
If IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.*
groups
array
List of local group this group is a member of (for applications that support adding groups to other groups)
tags
array
Specify tags with a key and optional value (optional)
contain property_values validated against the custom_property_definition
Contains zero or more local users (see ).
Contains zero or more (collections of users).
Defines permissions for any within the application.
Contains any and sub-resources.
See .
list of any memberships as strings. Must exist in local groups.
See .
array
See .