Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Strategies and best practices for OAA connector development
See the included topics for more information about developing an Open Authorization API connector.
Naming, typing, and searching for top OAA entities
Before uploading entity metadata for an OAA integration, you must create a custom provider and at least one data source under that provider. The provider represents the type of application (such as "Jira Server") and determines the template used for all data sources (e.g."dev", "prod")created under that provider.
The OAA payload is pushed to a specific data source and updates the existing data.
A display icon can be set for the provider, shown throughout the Veza UI to identify the integration and its entities.
Naming the provider and data source is an important step in integration creation. In general,
The provider name should be unique to the integration. Avoid common terms such as "application". Separating providers for systems with several instances such as "production" and "development" can be a good idea.
The provider or data source value should be unique to the integration and incorporate an identifier such as hostname or other instance ID. This ensures that multiple instances of the integration can be separated if necessary.
Do not user random or date values in provider or data source names. Each run of the connector should result in the same provider and data source name, based on discovered values or a configuration parameter.
Each OAA Template supports a concept of name and type. The type enables search for all instances of a specific entity. For example, the Application Type identifies application entities such as users, groups, roles, and resources. It will enable search for all entities in an application. Setting the application type to Widget will allow for search Widget Users, Widget Groups, and other entity types:
The app name appears when searching for individual entities, and, to differentiate more than one instances of the same system. For example two instances of an application "Widget - Production" and "Widget - Stagging".

Setting unique identifiers and human-readable names using OAA templates
Veza requires each entity to have a unique identifier, used within the template to reference entities (which groups a user is a member of) and for Veza to use to track and display the entity. This is true for both the Application and IdP templates
By default the templates use the name field for this purpose. However, names are not unique within some applications. In this case the templates offer an optional id as a unique identifier, allowing name to function as a non-unique display name.
Local User, Local Group and Local Role have an optional value id that can be provided for each entity that serves as the unique identifier.
To use id all Local Users, Local Groups and Local Roles must be defined with an ID. The name and id can be the same value as long it is unique for the entity type. For example a local role can have admin for both the name and id.
The id value becomes the key for referencing local users, groups and roles in the identity_to_permissions section of the payload and for referencing group memberships.
Using ids for mapping, instead of name is recommended in most cases, especially if any of the following are true:
Entity names aren't unique in the application (if two users can have the name "Joe Doe" but each have a unique user id such as email or login or the applications unique id).
The API references users, resources, and other entities by an ID instead of name. Using the same ID for the OAA payload will limit scenarios where you need to maintain a mapping of id to name in your connector.
For Custom Application to use
idfor Local Users, Groups and Roles all entities must use theidfield. To use theidfield for Resources all Resources and Sub-Resources must have anid
Resources and Sub-resource each can have an optional id value. When provided, the resource name does not need to be unique. To use id, all resources and sub-resources must be defined with a unique ID. The id value will be used to assign resource permissions in identity_to_permissions.
Custom IdP also supports a optional unique identifier value identity for Users and Groups. If not used, the entity name must be unique and will be the primary identifier.
Both custom properties and Veza Tags can be used to add rich metadata and apply labeling strategies across entities in the Veza Access Graph. Both can be viewed by checking an entity's details, and are fully available when searching and filtering results.
Veza tags can be assigned to objects in an OAA payload. One typical use case for tagging within the OAA payload is assigning resource managers with Veza SYSTEM_resource_managers tags.
Tags are applied by providing a key and an optional value for each. A new tag will be created if a matching one doesn't already exist.
{
"resource_type": "Cluster",
"description": "release staging cluster",
"sub_resources": [],
"tags": [
{
"key": "environment",
"value": "development"
}
]
}Due to superior integration with other Veza functionality and ease of updates, custom properties are recommended as the best approach for adding metadata to OAA entities, unless tagging is required as part of a larger campaign.
Note that while tags can be removed using the Tags API, tags applied within the template are persistent: an existing tag won't be deleted when pushing a payload with a new tag or empty tag.
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 incremental update is enabled by setting "incremental_change": true in the json_data push payload, and specifying the update operation for each entity to change.
The operation field indicates the change to make. Valid operations are:
"add", "modify", "delete" to create, change, or remove an entity.
"add_tag", "delete_tag" to update a tag without altering the entity.
...
"local_groups": [
{
"name": "LGroup1",
"identities": [
"localgroup1@company.com"
],
"tags": [
{
"key": "NewTag2Key",
"value": "NewTag2Value"
}
],
"operation": "add_tag"
}
]
...Data structures supporting the OAA templates.
Case-insensitive collection types used to track entities such as local users, groups, roles and resources by name or unique ID.
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
CaseInsensitiveDictCase Insensitive Key Dictionary
Dictionary like object with case insensitive keys for types that support .lower() such as strings.
Keys do not have to be strings, in the case where the key type does not support .lower() such as integers the value is used as is.
Example: from oaaclient.structures import CaseInsensitiveDict >>> x = CaseInsensitiveDict() >>> x["User"] = "value" >>> x.get("user") 'value' >>> "USER" in x True >>> print(x) {'user': 'value'} >>> x CaseInsensitiveDict({'user': 'value'})
__init__(data=None, **kwargs) → NoneStrategies for extracting authorization, identity, and resource metadata
When planning an OAA connector, consider how you will gather the information you want to import into Veza. Refer to the application’s documentation to confirm you can obtain the required metadata from the host application.
Ideally, you will be able to list and collect metadata for:
User records
Group memberships
User roles and permissions
Resource names and metadata
For example, the Veza-GitHub connector utilizes the following endpoints (in addition to basic authentication and authorization APIs):
Web-based APIs are a common solution for SaaS apps, but not required for an OAA integration. Just because an endpoint exists does not mean that it returns useful information (some APIs are more designed for client automation than audits). Possible choices for sourcing metadata include:
From a database: Is data for a hosted app available in a database your connector can query?
File-based extraction: is the metadata available in source code or a configuration file, or an exportable report (such as CSV)?
Other options: does the provider have an SDK or CLI interface you can use to retrieve data?
If no machine-readable data is readily available, even screen scraping could be a solution. There are many creative options for extracting the information to populate the template, although an API will typically be the most usable option.
- orgs/{org_name} - Get Organization information
- orgs/{org_name}/members - List members for an organization
- orgs/{org_name}/teams - List teams for an organization
- orgs/{org_name}/teams/{team}/members - List members for a given team
- orgs/{org_name}/repos - List organization repositories
- repos/{org_name}/{repo}/teams - List Team permissions for repository
- repos/{org_name}/{repo}/collaborators?affiliation=direct - List team members with direct permissionsMapping OAA objects to external and federated identities
In Veza, the Identity Provider (IdP) serves as the representation of the source of an identity (human or otherwise). That identity can have access to many applications, clouds and other data sources. By connecting OAA entities to source IdP identities, Veza can show all the access for that identity. This can also enable powerful correlation queries such as finding deactivated Okta Users with active application accounts.
Veza makes these connections based on the identity information provided in the OAA payload.
Veza Supports Mapping for the following Identity Providers:
Active Directory
Azure AD
Custom IdP
Google Workspace
Okta
OneLogin
For all Identity Providers, the IdP Unique ID and email attributes are used to match the source identity to an OAA principal. Some entity types have additional properties usable for identity mapping:
Active Directory
Account Name
Distinguished Name
Azure AD
Comparison ignores case, and is otherwise an exact match on the whole value. Veza does not strip domains, ignore punctuation, or compare email aliases when resolving identities from a payload. For Google Workspace, the compared values are the primary email address only.
For the full per-provider attribute list, the attributes Veza does not compare, such as employee IDs, and guidance on identities that fail to resolve, see . To correlate on an attribute outside that list, configure a on the identity provider integration.
The Application Template's Local User entity represents a user within the application. That Local User can map to an Identity Provider (IdP) by setting the identity value(s) in the Local Users identities array. Veza will use these identities to create an association between the IdP Identity and the Local User.
The Local User's email property is a display attribute and is not compared. Populate identities even when the same address is already set in email.
Veza uses the first value in identities that resolves and creates one connection per Local User, so additional values act as alternatives rather than as additional connections. A Local User in the , used by several built-in connectors, connects to every identity that resolves.
Setting external IdP Group identities is also supported on Local Groups. This should be used when there are no Local User records in the application that correlate to the external user identities. Veza will create a connection between the IdP Group and the Local Group, indicating that all IdP users from that group will have the access granted to the Local Group.
Unknown identities set on users will result in a warning that the identity can not be found. The OAA Local User will still be successfully created.
Note on Identity Mapping from the IdP: You can confirm these values by finding the corresponding entity in Veza search or the data catalog and checking the identities Idp Unique Id and other fields in the details view. Identities that cannot be resolved are returned as warnings when the application payload is pushed.
For applications that use Okta for SSO, you can also enrich local users with last login timestamps from Okta activity data. Set okta_app_id on the application object to enable this enrichment — Veza uses the same identities values to match local users to their Okta profiles. See .
OAA Identity Provider Users can be connected to other IdPs by using the source_identity property on the IdP users. For details see
Veza correlates HRIS Employee records to IdP identities using one value per employee, taking the first of idp_id, email, and employee_number that is set. Set the optional idp_id when the value that identifies the employee in the IdP is not their email address. Veza then compares that single value against the IdP attributes listed above, so an employee_number correlates only when it is also the IdP login, principal name, or email address.
For details, see .
On Premises SAM Account Name
Okta
User Login
Building blocks for your custom OAA integration
The Veza package provides data models, methods, and helpers for using the Open Authorization API. It provides helper methods to populate OAA templates for custom applications, filesystems, HRIS systems, and identity providers, and push the payloads to Veza. The SDK can also be used as a generic Veza API client.
The Veza SDK includes the following core components:
Veza.Sdk.Client: A base API client for making REST calls to a Veza tenant
Veza.OAA.Client: An OAA API client for interacting with integration providers, data sources, and pushing OAA metadata to a Veza tenant.
For example usage, see .
Sample Workflow
Create the Veza API connection and a new custom application:
Once the CustomApplication class is instantiated, you can use its public methods to populate the new app with users, groups, resources, and permissions metadata:
Once all identities, permissions, and resources are added to the CustomApplication object, use the client connection to push the data to Veza:
See the directory for full examples.
The Veza.OAA namespace provides exception types for common errors that occur when interacting with Veza APIs.
An OAAClientException is raised if there are errors interacting with the Veza API.
A TemplateException is raised if a provided payload does not conform to the template requirements. The inner exception will contain details about the exact issues encountered.
Each OAA connector will be slightly different, depending on the methods each source application or service provides for retrieving entities, authorization, and other required metadata. You should consult the API documentation for your application when considering how you will source the information, and refer to existing Veza-supported OAA connectors for real-world examples.
OAA connector source code and Veza components are thoroughly annotated for reference when building your own integrations.
For additional information about developing a custom OAA integration, please see section of the User Guide.
using Veza.OAA;
using Veza.OAA.Application;
using Veza.OAA.Base;
// inside namespace/class
OAAClient oaaClient = new(api_key: <your_api_key>, url: <veza_tenant_url>);
CustomApplication customApp = new(name: "sample app",
applicationType: "sample", description: "This is a sample application"); // add custom permissions
customApp.AddCustomPermission(name: "Admin", permissions: new List<Permission>
{
Permission.DataRead,
Permission.DataWrite,
Permission.MetadataRead,
Permission.MetadataWrite,
Permission.NonData
},
applyToSubResources: true
);
// define custom user properties
customApp.DefinedProperties[typeof(User)].DefineProperty("is_guest", typeof(bool));
// add user
User user = customApp.AddUser(name: "bob");
user.AddIdentity("bob@example.com");
user.IsActive = true;
user.CreatedAt = "2001-01-01T00:00:00.000Z".FromRFC3339();
user.DeactivatedAt = "2003-03-01T00:00:00.000Z".FromRFC3339();
user.LastLoginAt = "2002-02-01T00:00:00.000Z".FromRFC3339();
user.PasswordLastChangedAt = "2004-04-01T00:00:00.000Z".FromRFC3339();
user.SetProperty(name: "is_guest", value: false);
// define group properties
customApp.DefinedProperties[typeof(Group)].DefineProperty("group_id", typeof(int));
// add group
Group group1 = customApp.AddGroup("group1");
group1.CreatedAt = "2001-01-01T00:00:00.000Z".FromRFC3339();
group1.SetProperty(name: "group_id", 1);
customApp.Users["bob"].AddGroup("group1");
Group group2 = customApp.AddGroup("group2");
group2.AddGroup("group1");
// idp identities
customApp.AddIdPIdentity("user01@example.com");
// define role properties
customApp.DefinedProperties[typeof(Role)].DefineProperty("custom", typeof(bool));
// add roles
Role role1 = customApp.AddRole(name: "role1", permissions: new List<string> { "all", "Admin", "Manage_Thing" });
role1.SetProperty(name: "custom", value: false);
// define resource properties
customApp.DefineResourceProperty("private", typeof(bool), "thing");
// add resources
Resource thing1 = customApp.AddResource(name: "thing1", resourceType: "thing", description: "thing1");
thing1.SetProperty(name: "private", false);
thing1.AddTag(name: "tag1", value: "This is a value @,-_.");
Resource cog1 = thing1.AddSubResource(name: "cog1", resourceType: "cog");
cog1.AddConnection(id: "service_account@some-project.iam.gserviceaccount.com", nodeType: "GoogleCloudServiceAccount");
// authorizations
customApp.Users["bob"].AddRole(name: "role1", applyToApplication: true);
customApp.Groups["group2"].AddRole(name: "role1", resources: new List<Resource> { thing1 });
customApp.IdPIdentities["user01@example.com"].AddRole(name: "role1", applyToApplication: true);
return customApp; await oaaClient.CreateProvider(provider_name: "sample app", custom_template: "application");
await oaaClient.PushApplication(provider_name: "sample app", data_source_name: "sample app 1", customApp);Using Veza APIs to add custom data and identity providers to the Veza Entity Catalog
The Open Authorization API (OAA) is used to publish information about identities, authorization, and resources to the Veza Access Graph, making custom-built or otherwise-unsupported applications available for search, workflows, and monitoring. A typical motivation for using OAA is the need to integrate with enterprise applications that don't have an official Veza integration, such as a custom identity broker or source control management system.
Several community connectors built on OAA are already available for immediate use, enabling easy connection to SaaS providers such as GitHub, Salesforce, and others. You can also develop a custom connector using the Veza-provided Python SDK oaaclient or your language of choice.
To integrate a custom application using OAA, you will typically rely on an API (or another method) to list identities and resources within the host system, and retrieve entity and authorization metadata such as permissions, roles, and activity status. You must then structure this information according to one of the supported OAA templates. Once you have assembled the JSON payload, you can publish it using REST API calls or the oaaclient CLI.
Customers have utilized the Open Authorization API to accommodate many different scenarios. A few use cases include:
Using the GitHub connector to ensure that repositories holding critical source code are correctly configured.
Collecting infrastructure-as-a-code (IaC) configurations to audit which users can log in to important hosts.
Auditing the permissions granted by an internal developer portal.
Automating Lifecycle Management and Access Requests for custom applications that expose SCIM endpoints, enabling provisioning workflows for home-grown systems (see ).
introduces important OAA workflows, the custom application template, and common API operations. When planning your connector, you may also want to review the for more information about naming considerations, mapping custom applications to the OAA schema, and other topics.
Veza provides a and , which you can download using GitHub or pip install oaaclient. Examples and documentation are included with the source code.
Alternatively, you can parse a data source, compile the JSON payload, and publish it using your language of choice. For detailed documentation on the OAA schema and API operations, see:
- suitable for most applications
- for custom Identity Providers
- operations for creating, updating, and deleting OAA providers and data sources
oaaclient utility functions.
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
helper functions commonly used by OAA integrations
log_arg_errorlog_arg_error(log: object, arg: str = None, env: str = None) → NoneHelper function for logging errors when loading parameters
Helper function used to create consistent messages in connectors when required parameters can be set at command line or as environment variables.
Message can include information on parameter and/or environment variable but must provide one.
Args:
log (object): logging facility object to log to
arg (str, optional): Command line option for parameter such as --veza-url. Defaults to None.
env (str, optional): OS Environment variable for parameter such as VEZA_URL. Defaults to None.
Raises:
Exception: if neither arg or env are supplied
Load JSON from file
Args:
json_path (str): path to JSON file on disk
Raises:
Exception: Unable to process JSON
Exception: Error reading JSON file
Returns:
dict: JSON decoded to dictionary
read an icon file to a base64 encoded string
Args:
icon_path (str): Path to icon file on disk
Returns:
str: base64 encoding of file
Creates or updates a Veza report from a dictionary
Creates a report and containing queries from a dictionary definition. Function will create any queries it does not find based on name. If a query with the same name already exists the existing query will be added to the report.
If a report already exists with the same name any missing queries will be added to the report.
report_definition must be a dictionary with name for the report and queries list of Veza query definitions:
{"name": "My Report", "queries": [{..},{...}]}
Args:
veza_con (OAAClient): OAAClient connection to make Veza API calls
report_definition (dict): Report definition
Raises:
ValueError: Missing name or queries key
Returns:
dict: API response from Report creation or update
Helper function to truncate strings
Helper function to truncate strings to conform to maximum length requirements for templates.
Returns a string that is the first N bytes of the source string
Args:
source_str (str): Source string to truncate
length (int, optional): Length to shorten to. Defaults to 256.
Returns:
str: truncated string
JSON schemas for describing custom applications, identity providers, principals, file systems, and other authorization sources
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 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.
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.
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
Intended for modeling sources of users, group, and federated identity metadata, the Custom Identity Provider Template 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.
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.
For modeling sources of identities (users, groups, and tenants) that connect to other OAA data sources on the same provider, the Custom Principal Template provides a lightweight identity model. Unlike the Custom IdP, which models a full identity provider with domains, the Principal template is designed to feed users and groups into Custom Application or other templates on the same provider.
A Custom Principal is structured with:
Tenant
Users
Groups
For publishing employee metadata from an HR platform, the HRIS Template captures employment status, reporting lines, and organizational units. Unlike an identity provider, an HRIS does not usually grant access to other systems, so this template feeds Lifecycle Management events, identity correlation, and Access Review enrichment rather than authorization paths.
An HRIS submission is structured with:
System
Employees
Groups
For modeling secret and credential management systems, the Secret Store Template captures vaults, entries, permissions, and identity access mappings. Use this template to connect custom or self-hosted credential management systems that are not covered by a native Veza integration.
A Secret Store is structured with:
Secret Store
Permissions
Vaults
Entries
Identities
Identity-to-Permission Bindings
The Entity Enrichment Template adds custom property values to entities that already exist in the Veza authorization graph from other integrations. Use this template to attach supplemental metadata (such as compliance status, cost center, or internal identifiers) to entities discovered by native integrations.
An Entity Enrichment submission contains:
Enriched entity property definitions (schema declarations)
Enriched entities (entity references with property values)
For modeling file servers and file storage platforms, the File System Template captures which identities hold which permissions on servers, shares, and directories. Use it for storage systems that are not covered by a native Veza integration.
A File System has two submission modes, one for a server and its mounts and one for the folders within a mount:
Server
Mounts
Folders
Permissions
Identity-to-permission bindings
For bringing asset inventory into Veza, the CMDB Template captures configuration items from a configuration management database and correlates each one to the identity that owns it and to the Veza entity it describes.
A CMDB submission is structured with:
CMDB instance
Configuration items
Owner and asset correlation configuration
For submitting findings from an external secret scanning tool, the Secret Scanner Template records where credentials were found in source control so they can be correlated with matching credentials in Azure Key Vault. Unlike the other templates, a submission is a single flat list of findings with no entity hierarchy.
For modeling access to host machines such as Linux and Windows servers, the Host Template captures the accounts, groups, and credentials on each host. It also captures the privileges that principals hold on the host and on services or commands inside it. Grants can name identity provider users and groups directly, so directory principals allowed to sign in need no local definition.
A Host submission is structured with:
Environment
Hosts
Users
Groups
Credentials
Resources
Identity-to-privilege grants
Privilege definitions
load_json_from_file(json_path: str) → dictencode_icon_file(icon_path: str) → strexists_in_query_array(value_to_find, input_array) → boolbuild_report(veza_con, report_definition: dict) → dicttruncate_string(source_str: str, length: int = 256) → strException raised for OAA template schema violations.
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
OAATemplateExceptionGeneral exception used for violations of the template schema.
__init____init__(message)Upload large OAA payloads using chunked multipart requests
For OAA payloads that exceed 100 MB after compression, you can use multipart upload to split the payload into smaller chunks and upload them sequentially. The Veza platform assembles the chunks server-side before processing.
Multipart upload is useful when:
The payload is too large for a single HTTP request
Network reliability is a concern for large transfers
You need to monitor upload progress for very large data sources
Start the upload by sending a start request — the server creates an upload session and returns an upload_id.
Upload chunks sequentially, each base64-encoding a raw slice of the payload. Include the upload_id from step 1 and an incrementing sequence_number.
Finalize by sending a complete request with the upload_id and total sequence_count.
Each chunk must be base64-encoded from raw bytes before sending. The server decodes and reassembles chunks in sequence order when the complete operation is received.
The response returns an upload_id (UUID string) to use in all subsequent requests for this upload session.
Send a separate POST to the same endpoint after all chunks are uploaded:
The oaaclient Python SDK handles multipart upload automatically when enabled:
When enable_multipart is set to True, the SDK automatically switches to multipart for payloads exceeding 50 MB (uncompressed) and:
Splits the payload into chunks and base64-encodes each one individually
Starts an upload session and tracks the upload_id
Uploads each chunk sequentially with the correct sequence_number
Sends the completion operation to trigger server-side assembly
All chunks for a given upload_id must be uploaded before sending the completion operation.
You can re-upload a chunk with the same sequence_number and upload_id if needed — the last upload for a given sequence number is used. All chunks must be present before the completion operation is sent.
Chunk order is determined by sequence_number, not upload order.
oaaclient.templates: Classes for constructing an OAA JSON payload, one page per supported template.
client: Classes for calling Veza APIs and managing OAA providers and data sources.
structures: Data structures supporting the OAA templates.
: oaaclient utility functions.
: Class for OAA API Connection and Management.
: Error raised by OAAClient.
: Error with API Connection
: Error returned from API Call
: Entry point for oaaclient-report-builder command
: Creates or updates a Veza report from a dictionary
: read an icon file to a base64 encoded string
Classes for constructing an OAA JSON payload for Entity Enrichment
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
Class for modeling Entity Enrichment using the OAA Entity Enrichment template.
The Entity Enrichment template attaches custom properties to existing Veza entities (such as AwsIamRole, AwsIamUser or OktaUser
client.OAARetry: Super class for urllib3.util.retry
structures.CaseInsensitiveDict: Case Insensitive Key Dictionary
utils.load_json_from_file: Load JSON from file
utils.log_arg_error: Helper function for logging errors when loading parameters
utils.truncate_string: Helper function to truncate strings
string
Base64-encoded chunk of the raw payload
operation
string
Must be start
operation
string
Must be upload
upload_id
string
UUID returned by the start response
sequence_number
integer
Sequence number for this chunk, starting from 1. Maximum 99 chunks per upload.
operation
string
Must be complete
upload_id
string
UUID from the start response
sequence_count
integer
Total number of chunks uploaded
data
Enriched entities are tracked internally in a case insensitive dictionary keyed by the composite of entity type, data source id, and id so the same entity id can be enriched across multiple data sources or types. The index is private; use add_entity to add entities and get_entity to retrieve them.
Args:
name (str): Name for the Entity Enrichment instance. Used when creating the provider but not included in the payload itself.
Attributes:
name (str): Name for the Entity Enrichment instance
property_definitions (EntityEnrichmentPropertyDefinitions): Custom property definitions grouped by Veza entity type
Add an entity to enrich
Creates a new EnrichedEntity for an existing Veza entity. The entity is tracked internally keyed by the composite of entity type, data source id, and id so each entity may appear only once within the payload.
Args:
entity_type (str): Veza entity type (e.g. "AwsIamRole", "OktaUser")
id (str): Veza unique ID for the entity. For AWS entities this is the ARN.
data_source_id (str): ID of the Veza data source that owns the entity. For AWS this is the account
ID combined with the data source type (e.g. "339083562601: awsiam").
Raises:
OAATemplateException: Entity with the same type, id, and data_source_id already exists
Returns:
EnrichedEntity: Entity for the new enrichment record
Get a previously added entity to enrich.
Looks up an entity added with add_entity by its type, id, and data source id.
Args:
entity_type (str): Veza entity type (e.g. "AwsIamRole", "OktaUser")
id (str): Veza unique ID for the entity. For AWS entities this is the ARN.
data_source_id (str): ID of the Veza data source that owns the entity.
Raises:
OAATemplateException: No entity with the given type, id, and data_source_id has been added
Returns:
EnrichedEntity: The matching enrichment record
Get the OAA payload.
Returns the complete OAA template payload for entity enrichment as serializable dictionary
Returns:
dict: OAA payload as dictionary
Enriched Entity
Represents a single Veza entity to enrich with custom property values. The entity is identified by the combination of entity_type, id and data_source_id. Init variables are all required and must not be empty such as "".
Args:
entity_type (str): Veza entity type, e.g. "AwsIamRole", "OktaUser"
id (str): Veza unique ID for the entity. For AWS entities this is the ARN.
data_source_id (str): ID of the Veza data source that owns the entity.
Raises:
ValueError: Any of the required arguments are empty.
Set Enriched Entity custom property value
Property name must be defined for the entity's type before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined for the entity type.
Output enriched entity to dictionary for payload.
Model for defining custom properties for Entity Enrichment.
Property definitions are grouped by Veza entity type. Each entity type maintains its own set of property names and types that may be set on enriched entities of that type.
Attributes:
entity_properties (dict): Property definitions keyed by entity type. Each value is a dictionary mapping property name to its OAAPropertyType.
Define a property for an entity type.
Args:
entity_type (str): Veza entity type the property applies to (e.g. "AwsIamRole")
name (str): name for property
property_type (OAAPropertyType): type for property
Raises:
OAATemplateException: entity_type is not a non-empty string
OAATemplateException: name contains invalid characters or is not a string
OAATemplateException: property_type is not an OAAPropertyType enum
Return property definitions as list ready for OAA payload
Check property name for valid characters
Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.
Args:
name (str): name of property to validate
Raises:
OAATemplateException: Name is not a string
OAATemplateException: Name contains invalid characters or does not start with a letter
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:partsPAYLOAD_FILE="large_payload.json"
CHUNK_SIZE=10485760 # 10 MB per chunk
# 1. Start the upload session
RESPONSE=$(curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"start"}')
UPLOAD_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_id'])")
# 2. Split into raw chunks and upload each
SEQUENCE=0
split -b $CHUNK_SIZE "$PAYLOAD_FILE" /tmp/oaa_chunk_
for CHUNK_FILE in $(ls /tmp/oaa_chunk_* | sort); do
SEQUENCE=$((SEQUENCE + 1))
ENCODED=$(base64 -w 0 < "$CHUNK_FILE") # use -b 0 on macOS
curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"operation\": \"upload\",
\"upload_id\": \"$UPLOAD_ID\",
\"sequence_number\": $SEQUENCE,
\"data\": \"$ENCODED\"
}"
done
# 3. Finalize the upload
curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"operation\": \"complete\",
\"upload_id\": \"$UPLOAD_ID\",
\"sequence_count\": $SEQUENCE
}"
rm /tmp/oaa_chunk_*from oaaclient.client import OAAClient
client = OAAClient(url=veza_url, token=veza_api_key)
client.enable_multipart = True
# Push as usual - the SDK automatically chunks large payloads
client.push_application(provider_name, data_source_name, application_object=app)__init__(name: 'str')add_entity(
entity_type: 'str',
id: 'str',
data_source_id: 'str'
) → EnrichedEntityget_entity(
entity_type: 'str',
id: 'str',
data_source_id: 'str'
) → EnrichedEntityget_payload() → dict__init__(entity_type: 'str', id: 'str', data_source_id: 'str')set_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__()define_property(
entity_type: 'str',
name: 'str',
property_type: 'OAAPropertyType'
) → Noneto_dict() → listvalidate_name(name: 'str') → NoneClasses for constructing an OAA JSON payload for custom HRIS
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
Class for modeling Human Resource Information Systems (HRIS) Template
HRIS template consists of base information about the HRIS instance, Employees and Groups.
Employees and Groups are tracked in case insensitive dictionaries that can be used to reference entities after creation.
Args:
name (str): Name for HRIS Instance
hris_type (str): Type for HRIS. Typically the vendor or product name.
url (str): Instance URL for HRIS.
Attributes:
employees (dict[string]): Dictionary of HRISEmployee instances keyed by Employee ID
groups (dict[string]): Dictionary of HRISGroup instances keyed by Group ID
Add a new Employee
Function creates a new HRISEmployee instance and adds it to the HRISProvider.employees keyed by the unique_id
Args:
unique_id (str): Unique Identifier for Employee
name (str): Display name for employee
employee_number (str): The employee's number that appears in the third-party integration.
first_name (str): Employee first name
last_name (str): Employee last name (family name)
is_active (bool): Boolean for employee active status
employment_status (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING"
Raises:
OAATemplateException: Employee with ID already exists
Returns:
HRISEmployee: Entity for new employee
Add a new Group
Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups. Groups can also be members of other groups to create hierarchy.
Some properties of HRISEmployee such as department must reference an existing HRISGroup by its ID.
Args:
unique_id (str): Unique ID for group
name (str): Display name
group_type (str): Type for group such as "Team", "Department", "Cost Center"
Returns:
HRISGroup: Entity for new group
Get the OAA payload.
Returns the complete OAA template payload for HRIS as serializable dictionary
Returns:
dict: OAA payload as dictionary
HRISSystem information
Representation for HRISSystem information. The system information is used to represent additional details for the HRIS Instance.
Args:
name (str): Name for system Instance
url (str, optional): URL for instance . Defaults to "". TODO: Is this right?
Attributes:
identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().
Link HRIS to External IdP of given type
Sets the IdP types (Okta, AzureAD, etc.) for Veza to link employee identities to.
Args:
provider_type (IdPProviderType): Type of IdP for source identities
Raises:
ValueError: provider_type must be IdPProviderType enum
Returns:
list[IdPProviderType]: List of configured IdP types
Create and set the identity mapping configuration.
Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.
Returns:
IdentityMappingConfigurationSubmission: The identity mapping configuration.
HRIS Employee Entity
Represents an employee record in the HRIS system. Each employee must have a unique ID to identify it in the payload. This ID is also used to reference one employee to the other for manager hierarchy.
Init variables are all required and must not be empty such as ""
Args:
unique_id (str): Unique Identifier for Employee
name (str): Name for employee record.
employee_number (str): The employee's number that appears in the third-party integration.
first_name (str): Employee first name
last_name (str): Employee last name (family name)
is_active (bool): Boolean for employee active status
employment_status (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING"
Parameters:
company (str): The company (or subsidiary) the employee works for.
preferred_name (str): The employee's preferred first name.
display_full_name (str): The employee's full name, to use for display purposes.
canonical_name (str): The employee's canonical name.
username (str): The employee's username that appears in the integration UI.
email (str): The employee's work email.
idpid (str): The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used.
personal_email (str): The employee's personal email.
home_location (str): The employee's home location.
work_location (str): The employee's work location.
cost_center (str): The cost center ID (Group ID) that the employee is in.
department (str): The department ID (Group ID) that the employee is in.
managers (str): The employee IDs of the employee's managers.
groups (str): The IDs of groups this user is in
start_date (str): The date that the employee started working. RFC3339 timestamp.
termination_date (str): The employee's termination date. RFC3339 timestamp.
job_title (str): The title of the employee.
employment_typ (str): The employee's type of employment. For example: FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.
primary_time_zone (str): The time zone which the employee primarily lives.
Raises:
ValueError: Any of the required arguments are empty.
Add employee to group
Adds employee to a group by the group ID. Group must also be defined for HRISInstance with HRISProvider.add_group()
Args:
group_id (str): Unique ID of HRISGroup to add employee too
Add manager to Employee
Adds a manager to the employee by the manager's HRISEmployee instance unique ID. Manger employee record must also exist.
Args:
manager_id (str): Unique ID for manager HRISEmployee instance
Set Employee custom property value
Property name must be defined for employee before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Output employee to dictionary for payload.
HRIS Group
Represents any group of employees in the HRIS system. HRISGroups can be used to represent teams, departments, cost centers or any organizational unit. Each group has a type to make searching and grouping easier.
Group's Unique ID must be unique across all group types.
Args:
unique_id (str): Unique ID for group
name (str): Display name
group_type (str): Type for group such as "Team", "Department", "Cost Center"
Set HRIS Group custom property value
Property name must be defined for group before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Dictionary output for inclusion in payload
Check property name for valid characters
Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.
Args:
name (str): name of property to validate
Raises:
OAATemplateException: Name is not a string
OAATemplateException: Name contains invalid characters or does not start with a letter
__init__(name: 'str', hris_type: 'str', url: 'str')add_employee(
unique_id: 'str',
name: 'str',
employee_number: 'str',
first_name: 'str',
last_name: 'str',
is_active: 'bool',
employment_status: 'str'
) → HRISEmployeeadd_group(unique_id: 'str', name: 'str', group_type: 'str') → HRISGroupget_payload() → dict__init__(name: 'str', url: 'str' = '')add_idp_type(provider_type: 'IdPProviderType') → list[IdPProviderType]set_identity_mapping_configuration() → IdentityMappingConfigurationSubmissionto_dict() → dict__init__(
unique_id: 'str',
name: 'str',
employee_number: 'str',
first_name: 'str',
last_name: 'str',
is_active: 'bool',
employment_status: 'str'
)add_group(group_id: 'str') → Noneadd_manager(manager_id: 'str') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(unique_id: 'str', name: 'str', group_type: 'str')set_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__()define_employee_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_group_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_system_property(name: 'str', property_type: 'OAAPropertyType') → Noneto_dict() → dictvalidate_name(name: 'str') → NoneOverview and first steps for building an Open Authorization API connector
A built-in Veza integration or OAA connector might not be available for an application or identity provider you want to connect to Veza. However, you can still use the Open Authorization API to integrate compatible applications and identity providers with the rest of your Veza data catalog.
The adaptable OAA schema can model a wide range of authorization models and resource hierarchies, and you will typically have several options for sourcing authorization metadata from the application provider. To integrate a custom application with Veza, you will need to be able to:
Extract metadata from the source application using an API, command line, or another method to collect the needed authorization-related data. Depending on the application, this could include data resources and sub-resources as well as local users, groups, roles, permissions, and correlation to federated identities or external IDs.
Generate a payload describing the users, resources, and permissions, according to a standard JSON schema. The payload can describe any number of application resources and sub-resources, along with information about identities, groups, permissions, and relationships to other graph entities.
for processing using Veza APIs (after registering a new custom provider and data source if they don't already exist).
The process of retrieving user records, along with lists of resources, group and permissions information, will be unique to each technology and OAA connector. You may also need to consider how to adapt the application's implementation of roles, federated identities, and resource hierarchies to fit the .
Before building a connector, you should read the best practices for and , or see the current list of for real-world examples.
Most programming languages offer ways to populate and manipulate a JSON schema. You can also use the for prebuilt functions:
Below is an example of a populated application template. It demonstrates the basic principles of modeling local user permissions on application resources. For more details on all the available entities and properties see the full reference:
In addition to built-in properties such as department or last_login_at, most entities can have additional user-defined custom properties. Using enables integrations to capture application-specific data that can be useful for reporting and provide additional insight during investigations.
You can also apply to entities within the payload.
You will use the Veza REST API to create, delete, and update a custom data source under v1/providers/custom/{provider_id}/{datasource_id}. Before you can push an OAA payload, you will need to:
Add a custom Provider to represent the generic application provider (such as "GitHub"), and set the name and template (application or IdP).
Bind a custom Data Source to the new custom Provider (such as "GitHub Organization") to activate it in the data pipeline. The data source will be the destination for future pushes and updates, and should usually represent the top-level instance of the modeled application.
Push the payload to populate the Veza Access Graph with new entities and metadata for the custom data source.
Identity Providers and HR Information Systems can be used as identity sources in Provisioning Policies by marking the Provider as a provisioning source. Identities from these sources will be available when configuring Provisioning Policies.
Applications integrated via OAA can be managed through LCM Workflows via one of two methods:
SCIM - If the application supports SCIM provisioning, you can configure Veza to manage application access directly through SCIM. See for more information.
REST - For applications that support REST API calls to manage access, actions can be created in LCM Workflows to manage access.
To update the data, push a new payload to the original provider ID and data source ID. By default, Veza will overwrite any existing data. The previous state will be available in the graph history, based on Veza's snapshot retention schedule.
Optionally, subsequent changes can be , where the payload only contains entities to modify, add, or remove.
The module can be used to instantiate a Veza connection and manage OAA providers:
See for additional documentation.
Alternatively, you can make the required REST API calls using the client of your choice or by invoking oaaclient as a .
Typically, the provider should represent the provider name (such as "CustomSCM"). Any payload pushes will target the data source ("CustomSCMInstance") under the custom provider. The pushed payload can include many nested resources (such as multiple repositories). The template also supports resources with a variety of different types within a single application.
The data source and provider name are primarily for internal use. The application_type specified in the template is used when viewing and searching the custom app from the Veza UI.
Veza enforces strict validation of the json_data field containing the OAA payload. Three checks are performed:
All required fields must be present.
String fields must be valid UTF-8 strings, no larger than 512 characters for names and IDs, and 4,096 for all other string values.
The maximum single payload size is 100MB. If you need to compress the payload, you can enable the option when . You can use multi-part upload for large payloads.
A successful response may include warnings for issues that didn't prevent the processing of OAA data but should still be investigated. When mapping identities to an , a warning will be raised if a matching IdP group name or user principal name can't be found.
To validate an Azure AD or other type of user, go to the Access Graph, search for the node of interest, select Show Details, and confirm the principal name is correct.
To validate the identifier for a group, find the node for the group and verify the name is as expected.
Veza will always return the warnings key in the response. If a response is empty, there are no warnings.
For all Veza APIs, include an error code (in standard gRPC error, such as 3 for Invalid Argument) and a descriptive error message. The error message consists of two parts:
The field in which the error occurs
The detailed reason for the error
Open Authorization API usage examples
The official Veza connectors are useful references for understanding the decisions and strategies that come into play when building a custom Open Authorization API (OAA) integration.
Each connector is similar in basic function, yet adapts to the resource hierarchies and interfaces unique to the technology provider. Each uses the oaaclient Python package to construct a payload, create a custom provider and data source, and publish the extracted metadata.
Veza provides working connectors and source code for:
GitHub
GitLab
Jira
Looker
PagerDuty
Zendesk
See the for setup instructions and the most recent releases. The repository also includes sample applications demonstrating basic oaaclient usage. You can also browse these examples in the .
custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
jane = custom_app.add_local_user("jane", identities="jane@example.com")
resource1 = custom_app.add_resource(name="customers", resource_type="database")
jane.add_permission(permission="owner", resources=[customers])from oaaclient.client import OAAClient
from oaaclient.templates import CustomApplication, OAAPermission
# creates a connection class to communicate with Veza
veza_con = OAAClient(url=veza_url, token=veza_api_key)
# creates a new Custom Application model
custom_app = CustomApplication(name="Sample App", application_type="sample"){
"warnings": [
{
"message": "Cannot find identity by names (values: unknown_user@veza.com)"
}
]
}{
"applications": [
{
"name": "Support Portal",
"application_type": "support_portal",
"description": "Our customer support portal",
"local_users": [
{
"name": "bob",
"identities": [
"bob@example.com"
],
"groups": [
"admins"
],
"is_active": true,
"last_login_at": "2022-03-21T18:56:38Z"
},
{
"name": "sue",
"identities": [
"sue@example.com"
] }
],
"local_groups": [
{
"name": "admins"
}
]
}
],
"permissions": [
{
"name": "admin",
"permission_type": [
"DataWrite",
"DataRead",
"DataDelete",
"MetadataWrite",
"MetadataRead"
]
},
{
"name": "login",
"permission_type": [
"DataRead",
"MetadataRead"
]
}
],
"identity_to_permissions": [
{
"identity": "bob",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Support Portal",
"permission": "login"
}
]
},
{
"identity": "sue",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Support Portal",
"permission": "login"
}
]
},
{
"identity": "admins",
"identity_type": "local_group",
"application_permissions": [
{
"application": "Support Portal",
"permission": "admin"
}
]
}
]
}Classes for constructing an OAA JSON payload, one page per supported template.
application: Classes for constructing an OAA JSON payload for Custom Application
common: Shared base classes, enums and identity-mapping submission types used across the OAA templates.
enrichment: Classes for constructing an OAA JSON payload for Entity Enrichment
: Exception raised for OAA template schema violations.
: Classes for constructing an OAA JSON payload for the Host template
: Classes for constructing an OAA JSON payload for custom HRIS
: Classes for constructing an OAA JSON payload for Custom IDP
: Classes for constructing an OAA JSON payload for Custom Principal Submission
: Classes for constructing an OAA JSON payload for Secret Store
: Access Credential derived from Identity base class.
: Base class for CustomApplication.
: Model for defining custom properties for application and its entities (users, groups, roles, resources).
: Class for modeling application authorization using the OAA Application template.
: Veza supported IdP provider types.
: Identity mapping configuration submission.
: Identity mapping destination datasource.
: Enriched Entity
: Class for modeling Entity Enrichment using the OAA Entity Enrichment template.
: Model for defining custom properties for Entity Enrichment.
: General exception used for violations of the template schema.
: A credential that authenticates as an account on a Host.
: Environment for a Host fleet.
: Whether a HostGrant's principal is a user or a group.
: A group on a Host.
: HRIS Employee Entity
: HRIS Group
: Class for modeling Human Resource Information Systems (HRIS) Template
: App model for CustomIdPProvider
: Domain model for Custom IdP provider.
: Group model for CustomIdPProvider.
: CustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template.
: CustomPrincipal class for modeling Principal services using OAA Custom Principal Template.
: Group model for CustomPrincipal.
: Tenant model for Custom Principal submission.
: User model for CustomPrincipal
: Identity to Permission Mapping
: Permission Assignment
: Secret Store Entity
: Secret Store Permission Entity
: Helper function to simplify appending.
: Returns a list of unique strings from input list case insensitive
Template for submitting leaked secret findings from external secret scanning tools
Use this template to bring findings from an external secret scanning tool into Veza using the . Each finding records one place a credential was found in source control, so that leaked credentials can be correlated with the matching secrets in Azure Key Vault.
This template is smaller than the others. It has no application, resource, or identity entities, no permission model, and no custom properties. A submission is a single flat list of findings.
Using local roles, local users, and canonical permissions to describe access
Most applications will have some concept of a “local user” that can have varying permissions to data and metadata. Most modern cloud applications offer some form of single sign-on. In some cases, local user accounts correspond to an external federated identity, or even only exist ephemerally.
The Open Authorization API is able to represent local users, local groups, and external identities. An external identity could be an user connecting directly to a resource through Single Sign On, or an SSO group. A local user could be a just-in-time account created when an IdP user first connects.
You should represent system users using objects, even for apps that are SSO-enabled. The local user object is able to contain useful attributes such as activity status and timestamps, enabling rich search on those entities. A local user can also reference a federated identity, creating graph relationships between IdP entities and local users and groups when the payload is parsed. Veza handles these cross service connections similarly to built-in integrations such as Snowflake.
The OAA template supports direct permissions from IdP users to resources. However, including a local user entity in your OAA mapping strategy is still recommended when possible.
application.CustomPermission: CustomPermission class for defining CustomApplication permissions.
application.CustomResource: Class for resources and sub-resources.
application.IdPIdentity: IdP identity derived from Identity base class.
application.Identity: Base class for deriving all identity types (should not be used directly).
application.LocalAgent: Local Agent identity, derived from Identity base class.
application.LocalGroup: LocalGroup identity.
application.LocalModel: Represents an AI model entity within an application.
application.LocalRole: Represent a Custom Application Local Role.
application.LocalUser: LocalUser identity, derived from Identity base class.
application.LocalUserType: Types of local user account, human or service account.
application.OAAIdentityType: Types of identities for permission mapping.
application.OAAPermission: Canonical permissions used by Veza Authorization Framework.
common.IdentityMappingMode: Identity mapping mode.common.IdentityMappingProperty: Identity property used as source or destination in a property matcher.
common.IdentityMappingPropertyMatchersSubmission: Identity mapping property matcher.
common.IdentityMappingSubmission: Identity mapping submission.
common.IdentityMappingTransformation: Identity mapping transformation applied to identity values before matching.
common.IdentityMappingType: Identity mapping match type.
common.OAAOwnerType: Node types for entity owners
common.OAAPropertyType: Supported types for custom properties on OAA entities such as application, resource, and identity.
common.Provider: Base class for CustomProvider.
common.Tag: Veza Tag data model.
host.HostIdentityType: Whether a HostUser stands for a person or not.host.HostNode: A single host machine.
host.HostPrivilegeDefinition: A privilege defined once on the fleet and referenced by name wherever it is granted.
host.HostPropertyDefinitions: Model for defining custom properties for a Host fleet's hosts, users, groups and resources.
host.HostProvider: Class for modeling host machine authorization using the OAA Host template.
host.HostResource: Something inside a host that a privilege can apply to.
host.HostUser: A user account on a Host.
hris.HRISSystem: HRISSystem informationidp.CustomIdPUser: User model for CustomIdPProvider.
idp.IdPEntityType: IdP entity types.
idp.IdPPropertyDefinitions: Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain).
idp.IdPUserIdentityType: Types of identities for permission mapping.
principal.PrincipalEntityType: Principal entity types.
principal.PrincipalPropertyDefinitions: Model for defining custom properties for CustomPrincipal and its entities (tenant, users, groups).
secret_store.SecretStorePropertyDefinitions: Property Definitions for Secret Store entitiessecret_store.SecretStoreSubmission: Class for modeling Secret Store Template
secret_store.SecretStoreVault: Secret Store Vault Entity
secret_store.SecretStoreVaultEntry: Secret Store Vault Entry Entity
secret_store.VaultEntryIdentity: Vault Entry Identity
Users can also be grouped and assigned permissions with local_groups.
Veza understands an identity's level access to a resource in terms of raw system permissions in the provider's terms (such as AWS IAM s3:DeleteBucket), and canonical permissions (such asDATA DELETE). This allows Veza to answer the questions: "Who has MERGE permission on production repositories?" and "who can read data from any resource flagged for PII compliance?".
OAA requires you to map each granular application permission (like "view ticket" or "close ticket") to its corresponding C/R/U/D permission. This enables search and audit of effective and configured access.
Manage Access
Metadata Write
Merge
Data Write
Pull
Data Read
SaaS apps tend to be role-based, and organizations that follow security best practices will typically restrict the assignment of permissions directly to users. Following standard RBAC concepts, an OAA role represents a collection of permissions which can be scoped to individual resources or specific resource types.
If permissions granted by a role only apply to specific resource types or sub-resources, create the custom permissions individually and add them to the role in a list:
Under the custom application OAA schema, users can have direct permissions and role-based permissions to resources. Modeling these role-based permission assignments will enable searches such as "show all users with the maintain role in GitHub."
Note that “roles” in some apps actually function more like groups (lists of users), in which case they should be modeled using
local_groups.
For payloads where permissions apply for the entire application, you can create a single custom permission for a role, containing all the associated canonical permissions:
As demonstrated in the OAA PagerDuty connector, this is a quick way to model authorization structures such as:
Account Owner
owner
Data Write, Data Read, Data Delete, Metadata Read, Metadata Write
Responder
limited_user
Data Read, Metadata Read
Observer
limited_user
Data Read, Metadata Read
self.app.add_local_role("Write", ["Pull", "Fork", "Push", "Merge"])self.app.add_custom_permission("limited_user", permissions=[OAAPermission.DataRead, OAAPermission.MetadataRead])
self.app.add_local_role("Responder", unique_id="limited_user", permissions=["limited_user"])Custom properties
not supported
supported
Permissions
none
declared and bound to identities
Incremental updates
not supported
supported by several templates
Entity hierarchy
derived by Veza from the findings
declared in the payload
If you are modeling a credential management system rather than the output of a scanner, use the Secret Store template instead. Secret Store describes vaults, entries, and who can read them. Secret Scanner describes credentials that were found where they should not be.
You submit findings. Veza groups them and creates two entity types:
Custom Leaked Secret - one per distinct fingerprint, representing a single credential
Custom Leaked Secret Finding - one per submitted finding, representing one occurrence of that credential
A credential committed to three repositories produces one leaked secret and three findings. Veza also rolls up first and last seen timestamps and a finding count onto the leaked secret.
To use the secret scanner template, set the template type to secret_scanner when creating a new data provider:
When a leaked secret has a key_id, Veza looks for an Azure Key Vault secret, key, or certificate whose name equals the key_id. The match isn't case-sensitive. Veza connects the leaked secret to the first matching Key Vault secret, key, or certificate in each Azure subscription where Veza discovers Key Vault objects. A leaked secret without a key_id, or with no matching Key Vault object, isn't connected to a credential.
Azure Key Vault is the only correlation target for this template. Matching to AWS IAM access keys and to Secret Store entries applies only to leaked secrets found by GitHub Secret Scanning.
findings
array
Required. Array of objects. The only field in the payload
Veza rejects a payload that contains a field it doesn't recognize, either at the top level or inside a finding.
Each finding is one occurrence of one credential in one location. Findings are flat: there is no nesting, so every finding repeats the details of the credential it belongs to.
fingerprint
string
Required. Stable identifier for the credential, used to group findings. Two findings sharing a fingerprint describe the same credential
secret_hash
string
Required. A short hash prefix of the credential, for display. Submit this prefix rather than the credential itself
credential_type
string
Required. The kind of credential. See
source_system
string
Required. The scanner that produced the finding
repository_name
string
Required. The repository the credential was found in
repository_url
string
Link to the repository (optional)
discovered_at
string
Required. RFC3339 timestamp for when the scanner found the credential. Veza uses it to derive first and last seen dates for the leaked secret
scanner_confidence
integer
How confident the scanner is, by convention from 0 to 100. A value of 0, or an omitted value, isn't recorded (optional)
scanner_rule_id
string
The scanner rule that matched (optional)
When several findings share a fingerprint, Veza takes the credential details from the most recently validated one. If that finding leaves key_id, credential_type, or cloud_provider empty, Veza takes the value from another finding in the group. secret_hash and the validation fields come only from the most recently validated finding.
Four fields hold values that are conventions rather than a set Veza enforces. Any string is accepted.
credential_type
AWS_ACCESS_KEY, AZURE_CLIENT_SECRET, GCP_SERVICE_ACCOUNT_KEY, GITHUB_PAT, OTHER
cloud_provider
AWS, AZURE, GCP, GITHUB, OTHER
validation_status
NOT_VALIDATED, VALIDATED_ACTIVE, VALIDATED_INACTIVE
source_system
the name of the scanner that produced the finding
A finding that omits validation_status is recorded as NOT_VALIDATED.
Readers coming from a vulnerability management tool often look for these. None of them exists in this template:
Severity. There is no severity field. scanner_confidence records how sure the scanner is that the match is real, which is a different thing.
Remediation or resolution state. validation_status records whether the credential still works, not whether anyone has rotated or revoked it.
Assignment and ticketing. There is no assignee, owner, or ticket link.
Custom properties. This template accepts no custom_properties and no custom_property_definition.
For a JSON push, Veza also does not check required fields, either when the push is accepted or when the findings are processed. A finding missing a required field is stored with that value empty. Findings with no fingerprint are all grouped into a single leaked secret, so validate submissions before pushing them. A CSV upload does check fingerprint.
You can also upload findings as a CSV file, with each row holding one finding. A column mapping on the provider assigns CSV columns to finding fields.
Create the provider with the CSV push type and a column mapping:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"name": "MyScannerCSV",
"custom_templates": ["secret_scanner"],
"push_type": "CSV",
"csv_mapping_configuration": {
"template_type": "secret_scanner",
"column_mappings": [
{"column_name": "fingerprint", "destination_type": "finding", "destination_property": "fingerprint"},
{"column_name": "hash", "destination_type": "finding", "destination_property": "secret_hash"},
{"column_name": "type", "destination_type": "finding", "destination_property": "credential_type"},
{"column_name": "provider", "destination_type": "finding", "destination_property": "cloud_provider"},
{"column_name": "scanner", "destination_type": "finding", "destination_property": "source_system"},
{"column_name": "repo", "destination_type": "finding", "destination_property": "repository_name"},
{"column_name": "path", "destination_type": "finding", "destination_property": "file_path"},
{"column_name": "line", "destination_type": "finding", "destination_property": "line_number"},
{"column_name": "key_id", "destination_type": "finding", "destination_property": "key_id"},
{"column_name": "found_at", "destination_type": "finding", "destination_property": "discovered_at"}
]
}
}'Each mapping names a CSV column in column_name, sets destination_type to finding, and sets destination_property to a finding field. Custom properties aren't supported.
Create a data source on the provider, as for a JSON push.
Upload the file to the data source's :push_csv endpoint, with the CSV contents base64-encoded in csv_data. See .
These rules apply to the uploaded file:
The first row holds the column headers. Header names aren't case-sensitive, and each must be unique.
Every column named in the mapping must be present in the header row. Veza ignores columns that aren't mapped.
A row without a fingerprint value fails the upload. Veza rejects the file and reports the affected lines.
validation_timestamp and validation_response can't be mapped, so a workflow that needs them must push JSON.
If discovered_at isn't mapped, Veza records the time of the upload. Timestamp columns accept the .
As with a JSON push, each upload replaces the contents of the data source.
To create the OAA provider and push data:
Create the provider with the secret_scanner template type:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyScanner","custom_template":"secret_scanner"}'Create a data source on the provider:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"my_scanner_source"}'Push the payload to the data source:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.
Updates follow the same push workflow. Because this template replaces the data source contents on every push, submit the full current set of findings rather than only new ones. Veza removes a credential that the payload no longer lists.
Payload shape
one flat array of findings
nested entities
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyScanner","custom_template":"secret_scanner"}'"findings": [
{
"fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
"secret_hash": "9f2b1c",
"credential_type": "AWS_ACCESS_KEY",
"cloud_provider": "AWS",
"source_system": "EXAMPLE_SCANNER",
"repository_name": "example-org/billing-service",
"file_path": "config/settings.yaml",
"line_number": 42,
"discovered_at": "2026-09-02T04:15:00Z"
}
]Classes for constructing an OAA JSON payload for Custom Principal Submission
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
PrincipalEntityTypePrincipal entity types.
CustomPrincipalCustomPrincipal class for modeling Principal services using OAA Custom Principal Template.
Principals represent a source of identities (users and groups) to other OAA template types on the same provider.
Class uses dictionaries to track most components, dictionaries are all keyed by case insensitive string of the entity name
Args:
name (str): Name of Principal Provider
principal_type (str): Type descriptor for Principal Provider
tenant_id (str): Unique identifier for the tenant
Attributes:
name (str): Name of custom Principal Provider
principal_type (str): Type for Principal Provider
property_definitions (PrincipalPropertyDefinitions): Custom Property definitions for Principal instance
Add group to Principal submission
Arguments:
name (str): name for group
unique_id (str, optional): unique ID for group
group_unique_id (str, optional): unique identifier for group. Used in identity correlation.
Returns: CustomPrincipalGroup
Add user to Principal submission
Arguments:
name (str): name for user
unique_id (str, optional): unique ID for user
email (str, optional): email address for user
Returns: CustomPrincipalUser
Return formatted payload as dictionary for JSON conversion and upload
Tenant model for Custom Principal submission.
Args:
name (str): tenant name
unique_id (str): unique ID for tenant
tenant_unique_id (str, optional): unique identifier for tenant, usually a URL
Attributes:
name (str): tenant name
id (str): unique ID for tenant
tenant_unique_id (str): unique identifier for tenant
Add a new tag to Principal Tenant.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for tenant.
Property name must be defined for tenant before calling set_property().
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Output function for payload.
User model for CustomPrincipal
Args:
name (str): name for user
unique_id (str): unique ID for user
email (str, optional): email address for user
Attributes:
name (str): name for user
unique_id (str): unique ID for user
email (str): email address for user
user_unique_id
Add user to group by group ID.
Args:
group_id (str): ID of group to add user to
Add an identity to user.
Args:
identity (str): Identity string for user
Add a new tag to Principal User.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for user.
Property name must be defined for users before calling set_property().
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Function to prepare user entity for payload
Group model for CustomPrincipal.
Args:
name (str): name of group
unique_id (str): unique ID for group
property_definitions (PrincipalPropertyDefinitions, optional): Property definitions for custom properties
Attributes:
name (str): name of group
id (str): unique ID for group
group_unique_id (str): Optional unique identifier for group. Used for identity_unique_id
Add an identity to group.
Args:
identity (str): Identity string for group
Add a new tag to Principal Group.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set parent group for hierarchical group structure.
Args:
parent_group_id (str): ID of parent group
Raises:
OAATemplateException: If parent_group_id matches the group's own id
Set custom property value for group.
Property name must be defined for groups before calling set_property().
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Function to prepare group entity for payload.
Model for defining custom properties for CustomPrincipal and its entities (tenant, users, groups).
Property definitions define the names for additional entity properties and the expected type.
Attributes:
tenant_properties (dict): property definitions for Principal Tenant
user_properties (dict): property definitions for Principal users
group_properties (dict): property definitions for Principal groups
Define a group custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define a tenant custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define a user custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Returns custom Principal property definitions.
Validate that a property name has been defined for a given Principal entity.
Raises exception if property name has not been previously defined for entity
Args:
property_name (str): name of property to validate
entity_type (PrincipalEntityType): type of entity custom property is for (TENANT, USER, or GROUP)
Raises:
OAATemplateException: If property name is not defined
Template for setting custom property values on existing entities in the Veza authorization graph
Use this template to set custom property values on existing entities in the Veza authorization graph using the . Unlike other OAA templates that create new entities, the Entity Enrichment template adds metadata to entities that already exist from other integrations.
Entity enrichment is useful when you have supplemental data about entities that Veza already discovers through native integrations. For example, you might enrich AWS IAM roles with internal compliance metadata, or tag Okta users with cost center information from a custom source.
The template has two sections:
Enriched entity property definitions - declares the custom properties and their types for each entity type being enriched.
Enriched entities - the list of existing entities to enrich, with values for each declared property.
tenant (CustomPrincipalTenant): Tenant modelusers (dict[CustomPrincipalUser]): Dictionary of CustomPrincipalUser class instances
groups (dict[CustomPrincipalGroup]): Dictionary of CustomPrincipalGroup class instances
user_unique_idproperty_definitionsproperty_definitionsdisplay_name (str): display name for user
is_active (bool): whether user is active
created_at (str): date user was created (RFC3339 format)
deactivated_at (str): date user was deactivated (RFC3339 format)
last_login_at (str): date user last logged in (RFC3339 format)
group_typeparent_group_id (str): ID of parent group for hierarchical groups
cloud_provider
string
Required. The provider the credential belongs to. See Conventional values
key_id
string
The credential's public identifier, such as an access key ID. Used to correlate the leaked secret to a credential Veza already knows about (optional)
file_path
string
Required. Path to the file within the repository
line_number
integer
The line holding the credential. Submit it: a finding without this field records line zero
branch
string
The branch the finding was seen on (optional)
commit_hash
string
The commit the credential was found in (optional)
commit_date
string
RFC3339 timestamp for the commit (optional)
commit_message
string
The commit message (optional)
author_email
string
Email address of the commit author (optional)
author_name
string
Name of the commit author (optional)
finding_context
string
Surrounding context for the match, for triage (optional)
validation_status
string
Whether the credential was tested and found to work. See Conventional values (optional)
validation_timestamp
string
RFC3339 timestamp for when validation ran. Also decides which finding's details win when several share a fingerprint (optional)
validation_response
string
Free-form detail from the validation attempt (optional)
__init__(name: 'str', principal_type: 'str', tenant_id: 'str') → Noneadd_group(
name: 'str',
unique_id: 'str' = None,
group_unique_id: 'str' = None
) → CustomPrincipalGroupadd_user(
name: 'str',
unique_id: 'str' = None,
email: 'str' = None,
user_unique_id: 'str' = None
) → CustomPrincipalUserget_payload() → dict__init__(
name: 'str',
unique_id: 'str',
tenant_unique_id: 'str' = None,
property_definitions: 'PrincipalPropertyDefinitions' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
email: 'str' = None,
property_definitions: 'PrincipalPropertyDefinitions' = None
) → Noneadd_group(group_id: 'str') → Noneadd_identity(identity: 'str') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
property_definitions: 'PrincipalPropertyDefinitions' = None
) → Noneadd_identity(identity: 'str') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_parent_group(parent_group_id: 'str') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__() → Nonedefine_group_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_tenant_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_user_property(name: 'str', property_type: 'OAAPropertyType') → Noneto_dict() → dictvalidate_property_name(
property_name: 'str',
entity_type: 'PrincipalEntityType'
) → None{
"findings": [
{
"fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
"secret_hash": "9f2b1c",
"credential_type": "AWS_ACCESS_KEY",
"cloud_provider": "AWS",
"source_system": "EXAMPLE_SCANNER",
"repository_name": "example-org/billing-service",
"repository_url": "https://git.example.com/example-org/billing-service",
"file_path": "config/settings.yaml",
"line_number": 42,
"commit_hash": "4b7c2a91d8e3f560172bc4a9e8d3f102",
"branch": "main",
"author_email": "alice@example.com",
"author_name": "Alice Chen",
"commit_date": "2026-08-14T16:22:10Z",
"commit_message": "Add billing service configuration",
"scanner_confidence": 90,
"scanner_rule_id": "aws-access-key-id",
"key_id": "AKIAIOSFODNN7EXAMPLE",
"discovered_at": "2026-09-02T04:15:00Z",
"validation_status": "VALIDATED_ACTIVE",
"validation_timestamp": "2026-09-02T04:16:30Z"
},
{
"fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
"secret_hash": "9f2b1c",
"credential_type": "AWS_ACCESS_KEY",
"cloud_provider": "AWS",
"source_system": "EXAMPLE_SCANNER",
"repository_name": "example-org/deploy-scripts",
"file_path": "scripts/deploy.sh",
"line_number": 7,
"branch": "main",
"discovered_at": "2026-09-02T04:15:00Z",
"validation_status": "VALIDATED_ACTIVE"
}
]
}entity_enrichment when creating a new data provider:enriched_entity_property_definitions
array
List of for each entity type
enriched_entities
array
List of to enrich with property values
Each entry declares the custom properties that will be added to a specific entity type, along with their data types. Property types determine how Veza stores and indexes values. For example, TIMESTAMP properties enable relative date filters in queries (such as "last 90 days").
entity_type
string
Veza entity type to enrich (e.g., AwsIamRole, OktaUser)
enriched_properties
dictionary
Map of property names to their types. See
STRING
Text value
NUMBER
Numeric value (integer or float)
BOOLEAN
true or false
TIMESTAMP
Date/time value. Enables relative date filters in Veza queries
STRING_LIST
List of string values
The list of existing entities to enrich with property values. Each entity must appear exactly once with all properties that should be set. Including an entity with no properties clears all enriched property values from that entity. Only entities in the list are updated; other entities are not affected.
type
string
Veza entity type (must match an entity_type in the property definitions)
id
string
Veza unique ID for the entity. For AWS entities, this is the ARN. Each entity must appear only once in the list
data_source_id
string
Veza data source ID for the entity. For AWS, combine the account ID with the data source type (e.g., 339083562601:awsiam)
To create the OAA provider and push enrichment data:
Create the provider with the entity_enrichment template type:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Enrichment Provider","custom_template":"entity_enrichment"}'Create a data source on the provider:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Enrichment Data Source"}'Push the enrichment payload to the data source:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string. See for compression options.
Updates follow the same push workflow. Each push replaces the enrichment data for the entities included in the payload. Entities not included in the push are not affected.
Property values vs. property definitions: You can clear a property value by omitting its key in a subsequent push, or by including the entity with an empty properties object. This clears the stored value but does not remove the property definition from the entity type. Once a property name is defined for an entity type, the definition persists in the graph and cannot be removed.
Provider deletion: Deleting an enrichment provider does not remove enrichment data from the Veza graph. Data pushed through the provider remains associated with the enriched entities after the provider is deleted. Contact Veza support if you need to fully remove enrichment data from the graph.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"My Enrichment Provider","custom_template":"entity_enrichment"}'"enriched_entity_property_definitions": [
{
"entity_type": "AwsIamRole",
"enriched_properties": {
"my_company_id": "STRING",
"is_compliance_validated": "BOOLEAN"
}
}
]"enriched_entities": [
{
"type": "AwsIamRole",
"id": "arn:aws:iam::339083562601:role/Administrator",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
"is_compliance_validated": true
}
}
]Modifying custom providers using a partial OAA payload
After the initial metadata push, you can modify, add, or remove OAA entities, permissions, and properties without needing to submit the full payload each time. A first push can't be an incremental update.
An incremental update is specified by setting "incremental_change": true in the json_data push payload and adding an update operation for each entity to change. Most payload objects support incremental update operations:
The operation field indicates the change to make. Valid operations are:
"add", "modify", "delete" to create, change, or remove an entity.
"add_resource", "delete_resource" to modify resources in applications, permissions and role scopes.
"add_tag"
The object to update must contain an ID (name or identity) and the properties to create or modify. An error response will provide more details if an operation is invalid or unavailable.
See the sample payload below for .
When modifying dynamic properties, all five properties must be present.
add and modify can't be used on the same object. For example, to update both tags and properties on an entity, use:
The following JSON example for includes a range of update operations. Note that when modifying tags, only include the identity and tags (no other properties such as manager_id can be present).
Setting Entity Owners in OAA Payloads
OAA supports setting Entity Owners on OAA Entities as part of the submission for some templates. This enables a single operation to submit the OAA Entity and its owner.
Entity Owners enable automated assignment and accountability in access management and other workflows:
Owners can be used by Access Workflows for automatic assignment of review rows
Assigning owners for entities that represent non-human identities enables visibility into those users on the Non-Human Identities (NHI) overview page.
If Veza assigns a Risk Score to the entity, an owner assignment can help identify the user best able to remediate the risk.
Currently supported OAA Templates and entity types for Entity Owners:
Application Template:
Application (owners can be set at the application level itself)
Users
Groups
Roles
Resources
Requirements:
Entity Owners must be a User entity type from an Identity Provider integration enabled in Veza. If a is configured, the owner must be a user entity from the Global IDP.
Identity-provider application entities (such as OktaApp and AzureADEnterpriseApplication) also support entity owners, but owners are not set in the OAA payload. See for the full list and assignment methods.
Use the owners property on supported entities to specify entity owners as an array of objects.
For example, setting the owner on a role may look like the following:
For custom identity providers, you will need to determine the correct owner_type format to identify the entities in Veza Graph. You can find this information through the Veza UI or using an API request:
In the Veza UI:
Go to Access Visibility > Graph
Search for a user from your custom identity provider
Click on the user to open the sidebar and choose Basic Actions > View Details
The entity type is displayed in the user details (e.g., "OAA.Custom_IDP.IDPUser")
Alternately, you can use GET /api/v1/providers/custom to list all custom providers and their idp_type values. The owner_type format should be OAA.{idp_type}.IDPUser
See the table below for common IdP types and corresponding owner entity types:
If an Owner entry is malformed, references an unsupported owner type, or conflicts with the Global IDP setting a Field Violation error will be returned and the OAA payload will be rejected.
If an owner identity cannot be found, a warning will be returned with the successful response and the OAA payload will be accepted and processed with the unknown owner(s) being ignored.
Entity owners must originate from the primary Global IdP source. Users from cannot be used as entity owners.
After submitting an OAA payload with entity owners, verify the assignment by locating the entity in Query Builder or Graph Search. You can then configure to use these owners in access review workflows.
properties
dictionary
Map of property names to values. Keys must be defined in the property definitions, and values must match the declared type. Omitting a key that is defined in the property definitions removes that property value from the entity
{
"enriched_entity_property_definitions": [
{
"entity_type": "AwsIamRole",
"enriched_properties": {
"my_company_id": "STRING",
"company_purpose": "STRING",
"is_compliance_validated": "BOOLEAN"
}
},
{
"entity_type": "AwsIamUser",
"enriched_properties": {
"company_purpose": "STRING"
}
}
],
"enriched_entities": [
{
"type": "AwsIamRole",
"id": "arn:aws:iam::339083562601:role/Administrator",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
"company_purpose": "Built in Admin role",
"is_compliance_validated": true
}
},
{
"type": "AwsIamRole",
"id": "arn:aws:iam::650251689811:role/andrew_s3_all",
"data_source_id": "339083562601:awsiam",
"properties": {
"my_company_id": "A3F40BAC-1871-4EFC-A0EE-CD77E3F513C27",
"company_purpose": "Some role for Andrew",
"is_compliance_validated": false
}
},
{
"type": "AwsIamUser",
"id": "arn:aws:iam::339083562601:user/andrew",
"data_source_id": "339083562601:awsiam",
"properties": {
"company_purpose": "Engineering service account"
}
}
]
}"delete_tag"application, user, group, role, permission, role_assignments
domain, group, user
Access Credentials
Use this exact node type as your owner_type value
OneLogin
"OneLogin"
OneLoginUser
AWS IAM Identity Center
"AwsSso"
AwsSsoUser
Google Workspace
"Google"
GoogleWorkspaceUser
Custom LDAP
"company_ldap"
OAA.company_ldap.IDPUser
Custom Identity Provider
"custom_idp"
OAA.custom_idp.IDPUser
external_id
The ID of the owner from the IDP. External ID supports the same lookup attributes as identities
owner_type
The node type of the owner (case insensitive). For custom identity providers, use format OAA.{idp_type}.IDPUser, where {idp_type} is the value specified when creating the custom IdP provider. To find your idp_type value, use the List Custom Providers API. The attribute is optional when the Global IDP is configured
primary
If true, user is the primary owner, defaults to false
Provider Type
idp_type Value
owner_type Format
Standard Okta
"Okta"
OktaUser
Standard Azure AD
"AzureAD"
AzureADUser
Active Directory
"ActiveDirectory"
ActiveDirectoryUser
Ping Identity
"PingOne"
PingOneUser
"resources": [
{
"name": "resource1",
"resource_type": "type1",
"tags": [
{
"key": "keyDelta1",
"value": "valDelta1"
}
],
"operation": "add_tag"
},
{
"name": "resource1",
"resource_type": "type1",
"operation": "modify"
}
]{
"incremental_change": true,
"applications": [
{
"name": "Controller1",
"application_type": "WebServer",
"description": "The base web server",
"local_users": [
{
"name": "LUser1",
"identities": [
"localuser1@company.com"
],
"operation": "delete"
},
{
"name": "LUser1",
"identities": [
"localuser1Mod@company.com"
],
"operation": "add"
}
],
"local_groups": [
{
"name": "LGroup1",
"identities": [
"localgroup1@company.com"
],
"tags": [
{
"key": "groupTag2Key",
"value": "groupTag2Value"
}
],
"operation": "add_tag"
}
],
"local_roles": [
{
"name": "LRole2",
"permissions": [
"FULL"
],
"operation": "delete"
}
],
"resources": [
{
"name": "resource1",
"sub_resources": [
{
"name": "sub1b",
"operation": "delete"
}
],
"operation": "modify"
}
]
}
],
"permissions": [
{
"name": "Just Access",
"operation": "modify"
},
{
"name": "NonData",
"PermissionType": [
"NonData"
],
"operation": "add"
},
{
"name": "READ",
"permission_type": [
"DataRead"
],
"operation": "delete"
},
{
"name": "READ",
"permission_type": [
"DataRead"
],
"operation": "add"
}
],
"identity_to_permissions": [
{
"identity": "testuser1@company.com",
"identity_type": "IDP",
"role_assignments": [
{
"application": "Controller1",
"role": "LRole1",
"apply_to_application": true,
"operation": "delete"
},
{
"application": "Controller1",
"role": "LRole2",
"resources": [
"resource1",
"resource1.sub1a.sub2b"
],
"operation": "add"
}
]
},
{
"identity": "testuser3@company.com",
"identity_type": "IDP",
"role_assignments": [
{
"application": "Controller1",
"role": "LRole1",
"resources": [
"resource1.sub1b",
"resource1.sub1c"
],
"operation": "delete_resource"
},
{
"application": "Controller1",
"role": "LRole1",
"resources": [
"resource1.sub1a"
],
"operation": "add_resource"
}
],
"application_permissions": [
{
"application": "WebServer2",
"permission": "Just Access",
"operation": "delete"
}
]
}
]
}{
"external_id": "some_user@example.com",
"owner_type": "OktaUser",
"primary": true
} "local_roles": [
{
"name": "User Admin",
"permissions": [
"view_all",
"manage_users"
],
"owners": [
{
"external_id": "some_user@example.com",
"owner_type": "OktaUser",
"primary": true
}
]
}
]Enrich OAA custom application users with SSO last login timestamps from Okta
Veza can enrich custom application (OAA) users with SSO last login timestamps by correlating Okta sign-in activity with your application's local users. When enabled, each local user in the Veza graph gains a sso_last_login_at property showing the last time that user accessed the application through Okta SSO.
This is useful for identifying dormant accounts, auditing access patterns, and supporting access reviews.
You specify the Okta Application ID (okta_app_id) for your custom application.
For this enrichment, Veza matches your OAA local users to Okta users using the matching property you set with the Veza API in Step 2.
On each data push, Veza looks up Okta SSO activity for your application and writes the last login timestamp to matching local users.
Enrichment runs in the OAA service after data submission. If Okta activity data is unavailable, the push completes normally without SSO timestamps, and no data is lost.
Veza queries Okta activity at push time, stores the result with the submission, and replays that stored result on later parses without querying again. A sso_last_login_at value therefore reflects the most recent push of that application, not the most recent parse or Okta extraction.
After an Okta audit log extraction completes, push the application again to include the new activity. A scheduled parse of the application does not retrieve it, because the parse replays the stored result. For a CSV integration, upload the file again. A second extraction of the Okta integration is not required: the regular Okta extraction only places the Okta users in Access Graph so that they can be matched.
An active Okta integration in Veza with . Audit log data is the source for sso_last_login_at timestamps.
A custom application (OAA) integration, using either API push or CSV upload.
The Okta App ID (okta_app_id) set on the application, described in Step 4.
Ask Veza Support to enable Okta SSO last login enrichment for your tenant. You can't enable it yourself.
Configure which Okta user property Veza uses to correlate Okta users with your application's local users. You can set this yourself using the Veza API.
The string you pass as value specifies which OktaUser attribute to use for identity mapping. The attribute value on each Okta user must match the identities field on the linked OAA local users.
For example, if local users have identities: ["jane.doe@company.com"] and OktaUser nodes have login: "jane.doe@company.com", use login.
Custom attributes (e.g., customprop_employee_id) are also supported.
To set the property, send a PUT request with an API key that has the admin or system_monitoring role:
Replace <okta_user_property_name> with the OktaUser property to match on (e.g., login, email, or a custom attribute such as customprop_idx_uid).
To verify the current value:
Look for the okta_sso_user_matching_property key in the response.
Locate the Okta Application ID (0oa…) for the application you want to enrich:
Log in to your Okta Admin Console.
Navigate to Applications > Applications.
Select the application.
Copy the application ID from the URL (format: 0oaXXXXXXXXXXXXXXXX).
The method depends on how you push data to Veza.
Add the okta_app_id field to your application payload at the application level:
okta_app_id (application level): Your Okta Application ID.
identities (user level): One or more identity strings matched against the configured Okta user property.
Navigate to Integrations > Custom Application (CSV).
Enter your Okta Application ID in the Okta App ID field in the application configuration form.
Upload your CSV as usual, ensuring users have identity values that match their Okta profiles.
After pushing data, verify enrichment is working:
Open Query Builder in Veza.
Query for your custom application's local users.
Check the sso_last_login_at column on user nodes.
Users whose identities matched an Okta user with SSO activity for your application will have a sso_last_login_at timestamp. Users without a match (such as service accounts or users not in Okta) will not have this property — this is expected.
Matching is case-insensitive. Jane.Doe@company.com and jane.doe@company.com are treated as the same identity.
First match wins. If a user has multiple identities, the first one that matches an Okta user is used.
Enrichment is non-blocking. If Okta data is unavailable, the push completes without SSO timestamps. No data is lost.
How to use the Application Template to represent various types of application
The OAA Application template allows for representing the basic elements of an application and is flexible to allow for multiple different patterns.
The custom application template provides a framework for describing:
Who: Users, Groups, and other identities
What: Application, resources, sub-resources
How: Permissions, canonical mappings, roles, authorization
Application
The Application itself is the first entity as part of the Application submission. The application has a name and a type. The name can be specific such as "West Production" and the type is typically the vendor, technology, or product such as "GitLab". Veza will group the rest of the entities by the application type such as "GitLab Users" across all instances of an application type, however, entities will only be directly associated with the application they are submitted with. Applications additionally can have custom properties assigned to further enrich the data. This can be especially useful to distinguish between multiple instances of an application type.
Local Users
The Local User object represents the local user of the application. It can store application-specific information such as the identifier, name, active status, last login time, and custom properties specific to the application. An external Identity can be associated with the user, enabling Veza to connect the source Identity Provider (IdP). This creates a connection in Access Graph between the application user and a source identity such as Okta or Active Directory. Users can be added to groups, or have roles and permissions directly assigned.
Local Groups
Local Groups represent a collection of users. Groups can store additional metadata about the group to support search and filters. Groups can also contain other groups, to model applications that support nested groups. Groups can have role and permission assignments in the application.
Local Roles
Local Roles represent a collection of permissions within an application. When a user or group is assigned a role, that user or group is assigned all the permissions from the role. Like other entities, roles can contain additional properties to enrich the metadata of the role, such as description or application-specific attributes.
Permissions
OAA allows for expressing the permissions of the application in its own terms. In the Application Template, permissions are defined by application-specific terms such as "Close Ticket" or "Approve User". These permissions will also allow for setting corresponding Veza Canonical Permissions such as "Data Read", "Data Write", or "Metadata Read". This enables search and filters across permissions using CRUD-like equivalents.
Available Canonical Permissions: - DataRead - DataWrite - DataCreate - DataDelete - MetadataRead - MetadataWrite - MetadataCreate - MetadataDelete - NonData - Uncategorized
Resources
Resources can be used to model components within applications that users can be assigned roles or permissions on. For example, an OAA resource may be used to model a Project in an application like Jira. Users can have different roles in different projects, by assigning the correct users or groups their respective roles on the resources. Each resource has a Type which Veza uses when displaying and searching the resources for an application. Applications can have multiple types of Resources. Like other entities, resources can have properties containing additional resource metadata.
Below are some examples of how applications may be modeled in OAA. These examples have all been implemented using the Application template.
PagerDuty is an example of an application where users can have roles at the application level (global roles) but also within the PageDuty Teams that a user is a member of. Understanding which Users are part of which Teams and what level of access they have in those Teams is important for reviewing access in an application like PagerDuty. The OAA Application template can be used to model this type of application using the following mappings.
With this model, Veza can show the levels of access users have within the overall Application and their individual Teams. In this example, we can see the User Gary Ward has the Role "Restricted Access" in the PagerDuty Application, and the "Observer" Role in the "Support" Team Resource.
Python Code for the can be referenced on the Veza GitHub
GitLab is a good example of a more complex application that can be modeled using the Veza OAA Application Template. By correctly modeling the applications, Veza can show which users have access to GitLab Groups and Projects to show details beyond just "who has access to GitLab?"
Each GitLab User is represented with the Application Local User. GitLab assigns each user a unique ID number to each user, using this as the ID for the Local User makes it easier when associating groups and roles to Projects later. The Local User also allows for setting properties to represent the user's state such as is_active or last_login_at, custom properties to represent GitLab-specific properties can also be utilized like if the user is licensed or not. The identity for the Local User is set to enable OAA connection to source Identity Providers configured in Veza.
A GitLab Group represents both a collection of Users, a collection of Projects, and possibly other sub-groups. This is a good example of where some mapping needs to be done to represent GitLab using the Application Template. Since GitLab Users have a specific role in the GitLab Group, it is correct to represent the GitLab Group as an OAA Resource. Members are assigned an
Python Code for the can be referenced on the Veza GitHub
Template for modeling file systems with servers, mounts, folders, and permissions
Use this template to model file systems and file storage platforms using the . The File System template captures which identities hold which permissions on servers, mounts, and folders, for systems that are not covered by a native Veza integration.
The template models a hierarchical structure:
Server - a file server or storage account hosting one or more mounts
Mount - a share, drive, or volume on that server
Local Resource
To represent the User's role in the Team
Team Role
Local Role
Applied to the Team Resource
GitLab Roles are assigned to users or Groups as part of a Group or Project. GitLab is an example of an application with fixed roles where the roles and behaviors are coded directly into the application. For the OAA Application Template, the corresponding Local Roles are also coded directly into the connector by reviewing the GitLab documentation on available roles and the permissions associated with the roles. It is not always necessary to capture every Permission as part of the Local Role. Which permissions are important and how much detail is needed will be determined by the queries you intend to run, and the scope of Access Reviews that will be conducted in Veza.
GitLab Projects are also represented as an OAA Sub-Resource with the type set to Project. The Project Sub-Resource is added to the corresponding Group resource. Local User and Local Groups can be assigned roles on the project based on their direct assignments. In the case of GitLab, permissions can be inherited from above. This is an optional behavior for permissions, which can be set to automatically apply to sub-resources, or only apply directly to the assigned resources. Additionally, permissions can be set to apply to certain types of resources so that roles can be used across resources and only the correct permissions will be applied.
User
Local User
Team
Local Group
To group the Users
Application Role
Local Role
Applied to the Application
User
Local User
Group
Resource
Project
Sub Resource





Team
okta_sso_user_matching_property set to the Okta user property that holds your join key, described in Step 2. Veza uses this one property tenant-wide; it does not search every property on the Okta profile.identities values on your OAA local users that equal that Okta property's value for each user.
Timestamps reflect Okta access pattern data. The sso_last_login_at value comes from Okta's recorded activity for your specific application.
No Okta SSO activity
The user may not have accessed this application through Okta SSO
sso_last_login_at missing on specific users
No audit log activity for the app
Check Audit Logs for entries where the identity (GPID) accessed the OktaApp matching your okta_app_id. Enrichment only occurs when Veza has recorded SSO activity for that identity and application. This requires on the Okta integration.
Okta App ID field not visible in CSV form
Feature not enabled for the tenant
Contact Veza support to enable the feature
sso_last_login_at is older than the sign-in Okta reports
No push has run since that sign-in
Veza refreshes these values only during a push, even when the data source was parsed more recently or the Okta integration extracted activity more recently. Push the application again. For a CSV integration, upload the file again. See
curl -X PUT \
"https://<tenant>.vezacloud.com/api/private/namespaces/integrations/configurations/okta_sso_user_matching_property" \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" \
-d '{"value": "<okta_user_property_name>"}'curl -s "https://<tenant>.vezacloud.com/api/private/namespaces/integrations/configurations?page_size=100" \
-H "Authorization: Bearer <api_key>"{
"name": "My Application",
"application_type": "my_app_type",
"okta_app_id": "0oaABCDEF1234567890",
"local_users": [
{
"unique_id": "jdoe",
"name": "Jane Doe",
"identities": ["jane.doe@company.com"],
"email": "jane.doe@company.com"
}
]
}sso_last_login_at not appearing on any users
Feature not enabled for the tenant
Ask Veza Support to confirm Okta SSO last login enrichment is enabled for your tenant
sso_last_login_at not appearing on any users
Matching property not configured
Use the API in Step 2 to set okta_sso_user_matching_property, or contact Veza support to verify it is set
sso_last_login_at missing on specific users
Identity mismatch
Ensure the user's identities values match the OktaUser property values (check casing and email format)
sso_last_login_at missing on specific users
Folder - a directory within a mount, which can contain further folders
Permissions - a catalog of named permissions declared once and referenced wherever granted
Identity-to-permission bindings - map identities to permissions on a specific mount or folder
A custom property definition can define additional properties for servers, mounts, folders, and permissions.
To use the file system template, set the template type to file_system when creating a new data provider:
This template has two submission modes, and a single payload must use one or the other. The mode is selected by which fields you send, not by a flag.
Server mode
server and mounts
folders
A collector can see the server and enumerate its shares
Folder mode
folders and server_unique_id
server and mounts
A collector enumerates directories within one share
Veza rejects a payload that mixes them. Sending server and folders together, sending mounts without server, or sending server with an empty mounts array all fail validation.
Most integrations use both modes across separate data sources on the same provider: one data source submits the server and its mounts, and further data sources submit the folders for each mount. A folder joins its mount by setting parent_id to that mount's unique_id. Veza connects the two across data sources after both have been pushed, so order does not matter. A folder whose mount has not been submitted yet remains unattached until it is.
file_system_type
string
Required. Type descriptor for the file system, for example Windows File Server or Google Drive. Applied as a searchable property and used to interpret folder paths
server_unique_id
string
Required in folder mode. The unique_id of the server these folders belong to
server
object
The object. Sending this field selects server mode
identity_provider_types accepts any, active_directory, azure_ad, custom, google_workspace, okta, and one_login.
The server represents the machine or storage account hosting the mounts. Send it only in server mode.
unique_id
string
Required. Identifier for the server, unique within the payload. Maximum 512 characters
name
string
Required. Display name for the server
description
string
Description shown in Veza entity details (optional)
A mount is a share, drive, or volume on the server. Mounts carry identity bindings and can contain folders.
unique_id
string
Required. Identifier for the mount, unique within the payload
name
string
Required. Display name for the mount
description
string
Description shown in Veza entity details (optional)
A folder is a directory within a mount. Folders nest by referencing another folder, and attach to a mount by referencing the mount. Send them only in folder mode.
unique_id
string
Required. Identifier for the folder, unique within the payload
name
string
Required. Display name for the folder
description
string
Description shown in Veza entity details (optional)
Setting inherit_parent_permissions to true copies the parent's identity_to_permissions onto the folder, but only when the folder declares no bindings of its own. The rules are:
A folder with its own identity_to_permissions keeps them. The flag is ignored.
A folder with an empty identity_to_permissions and the flag set to true receives a copy of its parent's bindings.
A folder whose parent is not present in the same payload receives nothing, even with the flag set.
Inheritance is resolved when the payload is received, so the resulting bindings appear on the folder itself rather than being computed at query time. A folder that should show no access at all can set the flag to false and omit the bindings.
The permission catalog declares each permission once, at the top level of the payload. Mounts and folders then reference permissions by name.
name
string
Required. Serves as both the permission's identifier and its display name. There is no separate ID field. Maximum 512 characters
description
string
Description shown in Veza entity details (optional)
permission_type
array
Required, and must not be empty. One or more canonical permission types. See the list below
permission_type accepts DataRead, DataWrite, DataCreate, DataDelete, MetadataRead, MetadataWrite, MetadataCreate, MetadataDelete, NonData, and Uncategorized. These are the canonical types Veza uses to calculate effective permissions, and they are the same set used by the other custom templates.
Permission names are matched without regard to letter case or spaces, so Full Control, full control, and full_control refer to the same permission. Declaring two permissions whose names differ only in case or spacing is an error.
identity_to_permissions sits on mounts and folders, and maps each identity to the permission names it holds on that resource:
Every permission name must appear in the top-level permissions catalog. A name that does not resolve fails validation.
This template defines no local users or groups. The keys are identities belonging to an identity provider, and Veza matches them after the push against the integrations for the identity provider types you declared. Matching is case-insensitive, but the attributes a key can match depend on the identity provider:
active_directory
User principal name, account name, distinguished name, or email address
Distinguished name only
azure_ad
User principal name, onPremisesSamAccountName, identity provider ID, or email address
Name, principal name, or identity provider ID
okta
Login, identity provider ID, or email address
Name or identity provider ID
An Active Directory group must be keyed by its distinguished name. A share whose access control list holds DOMAIN\FinanceAdmins is submitted as CN=FinanceAdmins,OU=Groups,DC=example,DC=com, not as FinanceAdmins.
An identity that matches nothing yields a permission with no identity attached to it. That can mean the identity does not exist, or that the integration owning it has not been added yet.
Custom properties allow you to attach additional metadata to file system entities. Define properties in the custom_property_definition object, then set values on individual entities.
server_properties
Custom properties for server entities
mount_properties
Custom properties for mount entities
permission_properties
Custom properties for permission entities
folder_properties
Custom properties for folder entities
Property values must match their declared type. Supported types are described in Custom properties.
Property names are stored in lowercase, so two names differing only in letter case are an error. Each entity accepts at most 50 custom properties. Setting a custom property that the definition does not declare fails the push.
To create the OAA provider and push data:
Create the provider with the file_system template type:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyFileSystem","custom_template":"file_system"}'Create a data source on the provider:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"my_file_server"}'Push the payload to the data source:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.
When a file system spans both modes, create one data source for the server and its mounts, and a further data source for each set of folders. Push each independently.
Updates follow the same push workflow. Veza processes the full payload and replaces the contents of that data source. Unrecognized fields cause the push to fail, so remove any field this template does not define.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyFileSystem","custom_template":"file_system"}'"server": {
"unique_id": "fs-prod-01",
"name": "fs-prod-01.example.com",
"description": "Primary file server",
"custom_properties": {},
"tags": []
}"mounts": [
{
"unique_id": "finance-share",
"name": "Finance",
"description": "Finance department share",
"created_at": "2025-03-14T00:00:00Z",
"updated_at": "2025-09-01T00:00:00Z",
"identity_to_permissions": {
"CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"]
},
"custom_properties": {},
"tags": []
}
]"folders": [
{
"unique_id": "finance-reports",
"name": "Reports",
"path": "\\\\fs-prod-01\\Finance\\Reports",
"parent_id": "finance-root",
"inherit_parent_permissions": true,
"created_at": "2025-03-14T00:00:00Z",
"updated_at": "2025-09-01T00:00:00Z",
"identity_to_permissions": {},
"custom_properties": {},
"tags": []
}
]"permissions": [
{
"name": "Full Control",
"description": "Read, write, and change permissions",
"permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"],
"custom_properties": {},
"tags": []
}
]"identity_to_permissions": {
"CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"],
"alice@example.com": ["Read"]
}"custom_property_definition": {
"server_properties": {
"datacenter": "STRING"
},
"mount_properties": {
"quota_gb": "NUMBER",
"encrypted": "BOOLEAN"
},
"permission_properties": {},
"folder_properties": {
"owner": "STRING"
}
}API calls for managing and updating custom data sources
Use these REST API calls to manage and update custom providers and data sources with Open Authorization API.
Creates a custom provider for pushing OAA payloads, and returns the provider ID. Set custom_template (or custom_templates) to the OAA template the provider will use, such as application, identity_provider, or hris. See Using the Push API for template options and example requests.
This endpoint is shared with Create CSV Upload Custom Provider below, so the request schema in the reference includes fields for both workflows. For an OAA push provider, use only the following fields:
* Set one of custom_template or custom_templates.
Creates a custom provider configured for integrations, and returns the provider ID.
Typically, you will create and configure a CSV integration with the Add Integration flow in the Veza web interface, which builds the mapping configuration for you rather than requiring you to construct it directly. If you build the request yourself, this endpoint is shared with above, so the request schema in the reference includes fields for both workflows. For a CSV Upload provider, use only the following fields:
Lists all configured custom providers.
Returns details for an individual custom provider.
Update a custom provider.
Delete a custom provider by ID.
Return all data sources for a Custom Provider ID.
You can constrain large responses by adding a filter to the request query string. Include the operator (eq), and value, for example:
CURL <VEZA_URL>/api/v1/providers/custom?filter=name eq "GitHub"&order_by=state
Register a new datasource for a custom provider. There can be more than one datasource for a single provider.
Returns details for a single datasource.
Unbind a datasource from a custom provider, and delete it.
To push authorization metadata for a custom datasource, you can specify the source and provider IDs, and upload a payload with the entities and permissions in JSON format.
A warning is returned for any non-critical errors during payload processing. These can indicate incomplete or inaccurate data in the payload that do not prevent processing, but may warrant attention.
For large payloads that exceed 100 MB, use the multipart upload endpoint to upload the payload in chunks. See for details, examples, and Python SDK usage.
For , this endpoint pushes CSV data to an existing datasource. Typically, you will first create the integration and define column mappings using the "Add Integration" flow in Veza.
CSV data must base64 encoded into the JSON body of the request.
The populated template can be compressed and encoded, for significantly reduced payload size.
Specify the compression_type. Currently supported: GZIP.
If compression is selected, Veza will expect the payload json_data as a compressed, base64-encoded string.
To compress using shell commands:
Size is typically not an issue when updating custom datasources. However, you may want to compress large payloads. The maximum body size is 100MB (compressed or uncompressed).
Veza expects the populated template as a single JSON string, enclosed in the request body json_data field. Any "s and non-ASCII characters must be escaped.
To convert a template to JSON string using Python, the json.dumps() method could be used:
You can optionally add an icon for your custom provider by uploading a PNG or SVG file (less than 64kb) as a base64-encoded string:
Upload a custom icon to display for an OAA provider.
Return the type and string-encoded icon for a custom provider.
Delete the icon associated with an OAA provider.
This document provides a high-level overview of and examples for getting started with a new OAA connector to integrate Veza with SaaS applications, infrastructure systems, custom-built applications, and other systems. These examples use C# and the Veza.OAA SDK.
When developing a connector, source system specifics and individual customer requirements will require alterations to code flow. However, the overall goals, best practices, and development flow are common to most integrations.
The example code was written with the following goals in mind:
Connector should be easy to run from automation platforms and the Command Prompt.
Parameters are passed through environment variables as well as command line flags.
Roles become permissions, not entities. Drive has no local users or groups, so the permission catalog carries the role names and identities are referenced by email address.
Identities are Google email addresses for both users and groups, matched against the Google Workspace integration through identity_provider_types.
Link sharing becomes a property. A "anyone with the link" grant has no identity to bind, so it is recorded in shared_anyone and anyone_role where it remains visible and reportable.
Folders arrive on separate data sources and join their shared drive by setting parent_id to the drive ID.
mounts
array
Array of mount objects. Server mode only, and required when server is sent
folders
array
Array of folder objects. Folder mode only
permissions
array
Array of permission objects. The catalog referenced by every binding
custom_property_definition
object
Defines custom properties for servers, mounts, folders, and permissions. See Custom property definitions
identity_provider_types
array
Restricts which kinds of identity provider are searched when resolving identities. When absent or empty, all of them are searched
incremental_change
boolean
Must be false or omitted. This template does not support incremental updates
PushTime
string
Optional timestamp. Veza overwrites any value you send with the time the push was received
TagsDeleteRequests
array
Optional tag removal requests, each with node_id, type, and tags
custom_properties
dictionary
Custom properties validated against server_properties
tags
array
Specify tags with a key and optional value
created_at
string
RFC3339 timestamp for when the mount was created (optional)
updated_at
string
RFC3339 timestamp for when the mount was last modified (optional)
identity_to_permissions
dictionary
Maps an identity to a list of permission names from the catalog. See Granting permissions
custom_properties
dictionary
Custom properties validated against mount_properties
tags
array
Specify tags with a key and optional value
path
string
Full path to the folder. Veza derives a display name from it using conventions for the declared file_system_type
parent_id
string
The unique_id of the containing folder, or of the mount this folder sits directly beneath
inherit_parent_permissions
boolean
When true and identity_to_permissions is empty, Veza copies the parent folder's bindings onto this folder
created_at
string
RFC3339 timestamp for when the folder was created (optional)
updated_at
string
RFC3339 timestamp for when the folder was last modified (optional)
identity_to_permissions
dictionary
Maps an identity to a list of permission names from the catalog
custom_properties
dictionary
Custom properties validated against folder_properties
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
Custom properties validated against permission_properties
tags
array
Specify tags with a key and optional value
google_workspace
Email address or identity provider ID
Name or email address
one_login
Identity provider ID or email address
Not matched
custom
Identity provider ID or email address
Identity provider ID only
Connector does not require maintenance of state:
Connector does not require any persistent data between invocations.
There is no special invocation for the first execution.
The connector handles all provider and data source management logic.
Data source name is unique to the discovered environment.
The exact flow of an OAA connector can change to meet specific requirements, but the general steps are as follows:
Process and validate configuration parameters. Ensure that all required values are present and valid.
Initialize the API client connection to the Veza tenant. Doing so early in the application flow validates the URL and API key before continuing discovery.
Create an instance of the Veza.OAA.Application.CustomApplication class to populate with application metadata.
Connect to the system and perform discovery of required entities.
In your custom integrations, discovery order for users, groups, roles, and other entities can adapt to suit application requirements.
Populate the CustomApplication instance with the identity, role, permission, resource, and authorization information collected.
Check if the Provider and Data Source exist on Veza. Create them if they do not exist.
Push the application to the Data Source on Veza. The SDK creates the required JSON payload from the CustomApplication instance.
Process any returned warnings or errors.
Exit.
To use this example as a starting point for your application integration, follow these steps:
Update the name, applicationType, and description of the CustomApplication object based on the source system for integration with Veza.
Define any custom_properties needed. Properties must be defined on the CustomApplication object before their values are set on any entities.
Implement the discovery steps in the Discover() function to collect user, group, role, resource, and permission data for the application. As entities are collected, add them to the CustomApplication object.
Run the connector to validate the output in Veza.
The following code provides a template and examples for creating a new application integration using the Veza.OAA SDK.
{
"file_system_type": "Windows File Server",
"identity_provider_types": ["active_directory"],
"custom_property_definition": {
"server_properties": {
"datacenter": "STRING"
},
"mount_properties": {
"quota_gb": "NUMBER",
"encrypted": "BOOLEAN"
},
"permission_properties": {},
"folder_properties": {}
},
"permissions": [
{
"name": "Full Control",
"description": "Read, write, and change permissions",
"permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
},
{
"name": "Read",
"description": "Read files and list contents",
"permission_type": ["DataRead", "MetadataRead"]
}
],
"server": {
"unique_id": "fs-prod-01",
"name": "fs-prod-01.example.com",
"description": "Primary file server",
"custom_properties": {
"datacenter": "iad1"
},
"tags": [
{
"key": "environment",
"value": "production"
}
]
},
"mounts": [
{
"unique_id": "finance-share",
"name": "Finance",
"description": "Finance department share",
"created_at": "2025-03-14T00:00:00Z",
"identity_to_permissions": {
"CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"],
"alice@example.com": ["Read"]
},
"custom_properties": {
"quota_gb": 500,
"encrypted": true
}
},
{
"unique_id": "public-share",
"name": "Public",
"identity_to_permissions": {
"CN=Domain Users,CN=Users,DC=example,DC=com": ["Read"]
}
}
]
}{
"file_system_type": "Windows File Server",
"server_unique_id": "fs-prod-01",
"permissions": [
{
"name": "Full Control",
"description": "Read, write, and change permissions",
"permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
},
{
"name": "Read",
"description": "Read files and list contents",
"permission_type": ["DataRead", "MetadataRead"]
}
],
"folders": [
{
"unique_id": "finance-root",
"name": "Finance",
"path": "\\\\fs-prod-01\\Finance",
"parent_id": "finance-share",
"inherit_parent_permissions": false,
"identity_to_permissions": {
"CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"]
}
},
{
"unique_id": "finance-reports",
"name": "Reports",
"path": "\\\\fs-prod-01\\Finance\\Reports",
"parent_id": "finance-root",
"inherit_parent_permissions": true
},
{
"unique_id": "finance-payroll",
"name": "Payroll",
"path": "\\\\fs-prod-01\\Finance\\Payroll",
"parent_id": "finance-root",
"inherit_parent_permissions": false,
"identity_to_permissions": {
"CN=PayrollTeam,OU=Groups,DC=example,DC=com": ["Full Control"]
}
}
]
}{
"file_system_type": "Google Drive",
"identity_provider_types": ["google_workspace"],
"custom_property_definition": {
"mount_properties": {
"admin_managed_restrictions": "BOOLEAN",
"domain_users_only": "BOOLEAN",
"drive_members_only": "BOOLEAN",
"shared_anyone": "BOOLEAN",
"anyone_role": "STRING",
"shared_domain": "BOOLEAN",
"domain_role": "STRING"
},
"folder_properties": {
"shared_anyone": "BOOLEAN",
"anyone_role": "STRING",
"shared_domain": "BOOLEAN",
"domain_role": "STRING"
}
},
"permissions": [
{
"name": "organizer",
"description": "Manage members, content, and settings",
"permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
},
{
"name": "fileOrganizer",
"description": "Manage content but not members",
"permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
},
{
"name": "writer",
"description": "Add and edit content",
"permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
},
{
"name": "commenter",
"description": "Comment on content",
"permission_type": ["DataRead", "MetadataRead", "MetadataWrite"]
},
{
"name": "reader",
"description": "View content",
"permission_type": ["DataRead", "MetadataRead"]
}
],
"server": {
"unique_id": "C01abc234",
"name": "C01abc234"
},
"mounts": [
{
"unique_id": "0ABcDeFgHiJkLmNoPQ",
"name": "Engineering",
"created_at": "2024-06-01T12:00:00Z",
"identity_to_permissions": {
"alice@example.com": ["organizer"],
"engineering@example.com": ["writer"]
},
"custom_properties": {
"admin_managed_restrictions": true,
"domain_users_only": false,
"drive_members_only": true,
"shared_anyone": false,
"shared_domain": false
}
}
]
}using RestSharp;
using RestSharp.Authenticators;
using Veza.OAA;
using Veza.OAA.Application;
using Veza.OAA.Client;
using NLog;
namespace Example.Integrations
{
/// <summary>
/// Example application group object
/// </summary>
public class AppGroup {
public string Name { get; set; }
public string Type { get; set; }
public string CreatedAt { get; set; }
public List<string> Users { get; set; }
}
/// <summary>
/// Example application resource object
/// </summary>
public class AppResource {
public string Name { get; set; }
public int SiteId { get; set; }
public string ResourceType { get; set; }
}
/// <summary>
/// Example application role object
/// </summary>
public class AppRole {
public string Name { get; set; }
public int SystemId { get; set; }
public string CreatedAt { get; set; }
public List<string> Users { get; set; }
public List<string> Resources { get; set; }
}
public class ExampleApp
{
// Optional NLog logger; can be replaced with any standard logging interface
private static Logger logger = LogManager.GetCurrentClassLogger();
// The base64-encoded logo for the application (displayed on the Veza UI)
public string LogoBase64;
// The name of the provider for the application
public string ProviderName;
// The custom application object for the example application
// This object is used to build the application payload for Veza
public CustomApplication CustomApp { get; set; }
// The example application client for the example application API (not shown in this example)
private ExampleAppClient AppClient { get; set; }
# region "Construction"
public ExampleApp()
{
// Instantiate the example application
CustomApp = new CustomApplication(
name: "Example Application 1",
applicationType: "Example App",
description: "Example application for Veza integration"
);
// Define an "uncategorized" permission for the example application
// This can be used to group permissions that do not fit into another category,
// or if the application API does not provide permission information
CustomApp.AddCustomPermission(
name: "Uncategorized",
permissions: new List<Permission> { Permission.Uncategorized }
);
// define custom properties for the example application
DefineCustomProperties();
// Set the application icon for the Veza UI
// This should be a base64-encoded SVG or PNG image
LogoBase64 = "abc123...def987654"
}
/// <summary>
/// Define custom properties for the example application.
/// This method is called by the constructor to define any custom properties
/// that the example application entities may have.
/// </summary>
private void DefineCustomProperties()
{
CustomApp.DefinedProperties[typeof(User)].
DefineProperty("locked_out", typeof(bool);
CustomApp.DefinedProperties[typeof(Group)].
DefineProperty("type", typeof(string));
CustomApp.DefinedProperties[typeof(Role)].
DefineProperty("system_id", typeof(int));
CustomApp.DefineResourceProperty("site_id", typeof(int)), "widget");
}
# endregion
# region "Discovery"
// Individual methods for discovering users, groups, roles, and resources.
// Should be scoped as private to ensure that they are called only by the Discover method
// and not directly by the client application.
/// <summary>
/// Discover users for the example application.
/// This method is called by the Discover method to discover users for the example application.
/// </summary>
private void DiscoverUsers()
{
Logger.Info("Discovering users for the example application");
// Get users from the example application client.
// In this example, the GetUsers method returns a list of dictionaries of user data.
List<Dictionary<string, string>> users = AppClient.GetUsers();
// Iterate over the users response and add them to the application payload
foreach (Dictionary<string, string> u in users)
{
// Create a new user object and add it to the application payload
User user = CustomApp.AddUser(name: u["username"]);
user.AddIdentity(u["email"]);
user.IsActive = u["active"];
user.CreatedAt = u["created_at"];
}
Logger.Info("User discovery complete");
}
/// <summary>
/// Discover groups for the example application.
/// This method is called by the Discover method to discover groups for the example application.
/// </summary>
private void DiscoverGroups()
{
Logger.Info("Discovering groups for the example application");
// Get groups from the example application client
// in this example, the GetGroups method returns a list of AppGroup objects
List<AppGroup> groups = AppClient.GetGroups();
// Iterate over the groups response and add them to the application payload
foreach (AppGroup g in groups)
{
// Create a new group object and add it to the application payload
Group group = CustomApp.AddGroup(name: g.Name);
group.CreatedAt = g.CreatedAt;
group.SetProperty(name: "type", value: g.Type);
// Iterate users in the group and add them to the group
foreach (string user in g.Users)
{
CustomApp.Users[user].AddGroup(g.Name);
}
}
Logger.Info("Group discovery complete");
}
/// <summary>
/// Discover resources for the example application.
/// This method is called by the Discover method to discover resources for the example application.
/// </summary>
private void DiscoverResources()
{
Logger.Info("Discovering resources for the example application");
// Get resources from the example application
// In this example, the GetResources method returns a list of AppResource objects
List<AppResource> resources = AppClient.GetResources();
foreach (AppResource r in resources)
{
// Create a resource object and add it to the application payload
Resource resource = CustomApp.AddResource(name: r.Name, resourceType: r.ResourceType);
// Set the `site_id` property for the resource if the resource is a "widget"
// Cstom resource properties are defined per-resource type, so non-"widget" resources will not have this property
if (r.ResourceType == "widget")
{
resource.SetProperty(name: "site_id", value: r.SiteId);
}
}
Logger.Info("Resource discovery complete");
}
/// <summary>
/// Discover roles for the example application.
/// This method is called by the Discover method to discover roles for the example application.
/// </summary>
private void DiscoverRoles()
{
Logger.Info("Discovering roles for the example application");
// get roles from the example application
// in this example, the GetRoles method returns a list of AppRole objects
List<AppRole> roles = AppClient.GetRoles();
foreach (Role role in roles)
{
// create a new role object and add it to the application payload
Role role = CustomApp.AddRole(name: role.Name);
role.CreatedAt = role.CreatedAt;
role.SetProperty(name: "system_id", value: role.SystemId);
// iterate users in the role and add them to the role
// set the applyToApplication flag to true to apply the role to the entire application
foreach (string user in role.Users)
{
CustomApp.Users[user].AddRole(name: role.Name, applyToApplication: true);
}
Application.AddRole(role);
}
Logger.Info("Role discovery complete");
}
# endregion
# region "Execution"
/// <summary>
/// Discover the example application.
/// This method is called by the Run method to discover the example application.
/// It serves as a place to instantiate a client for the example application API
/// and then call each of the discovery methods required to build the application payload.
/// </summary>
/// <param name="exampleApiKey">The API key for the example application API</param>
/// <param name="exampleUrl">The URL for the example application API</param>
/// <returns></returns>
public void Discover(string exampleApiKey, string exampleUrl)
{
// instantiate an API client for the example application
AppClient = new ExampleAppClient(exampleApiKey, exampleUrl);
Logger.Info("Beginning example application discovery");
// discover the example application components
DiscoverUsers();
DiscoverGroups();
DiscoverResources();
DiscoverRoles();
Logger.Info("Example application discovery complete");
}
/// <summary>
/// Handle integration execution.
/// This is separated from the Main method to more easily adapt to changes
/// to application execution (e.g. from Command Prompt, as part of another application, etc.)
/// </summary>
/// <param name="exampleApiKey">The API key for the Example application API</param>
/// <param name="exampleUrl">The URL for the Example application API</param>
/// <param name="vezaApiKey">The API key for the Veza tenant</param>
/// <param name="vezaUrl">The URL for the Veza tenant</param>
/// <returns></returns>
public async Task Run(
string exampleApiKey,
string exampleUrl,
string vezaApiKey,
string vezaUrl
)
{
Logger.Info("Starting example application discovery");
// Instantiate a connection to the Veza API.
// The client will attempt to reach the Veza API and throw an exception if it fails.
// This is to ensure that the Veza API is reachable before attempting to discover and push data.
try
{
OAAClient oaaClient = new(vezaApiKey, vezaUrl);
}
catch (ClientException e)
{
Logger.Error("Failed to connect to Veza API: {0}", e.Message);
return;
}
// Discover the example application
Discover(exampleApiKey, exampleUrl);
// Get or create the Veza provider for the payload
Logger.Debug("Checking Veza for an existing provider for the example application");
Sdk.Client.ApiClient.VezaApiResponse providerResponse = await oaaClient.GetProvider(ProviderName);
// Create the provider if none exists
if (providerResponse is null)
{
Logger.Info("No Veza provider exists; creating provider");
await oaaClient.CreateProvider(ProviderName, "application", base64_icon: LogoBase64);
}
// Push OAA payload to Veza
Logger.Info("Pushing example application metadata to Veza");
RestResponse<Sdk.Client.ApiClient.VezaApiResponse> pushResponse = await oaaClient.PushApplication(ProviderName, Environment.MachineName, CustomApp, save_json: true);
if (pushResponse.IsSuccessful)
{
Logger.Info("Example application discovery complete");
} else
{
Logger.Error($"Push response code: {pushResponse.StatusCode}");
Logger.Error($"Push response content: {pushResponse.Content}");
}
}
# endregion
}
}provisioning
boolean
No
Set to true to use the provider with Lifecycle Management: as a source of identity with the hris or identity_provider template, or as a provisioning target with external_lifecycle_management_type.
external_lifecycle_management_type
string
No
How Lifecycle Management provisions to the application: SCIM, SEND_REST_PAYLOAD, SEND_XML_PAYLOAD, or SEND_SQL_COMMAND. Requires provisioning set to true.
configuration_json
string
With SCIM
JSON-encoded SCIM connection details. See . Leave empty otherwise.
data_plane_id
string
With SEND_REST_PAYLOAD, SEND_XML_PAYLOAD, or SEND_SQL_COMMAND
ID of the Insight Point that sends the requests. See . Leave empty when external_lifecycle_management_type is not set.
notification_preferences
object
No
Configure notifications for this provider.
array
No
A list with the template named in csv_mapping_configuration.template_type, for example ["secret_scanner"]. A CSV integration created in Veza sets it the same way.
csv_mapping_configuration
object
Yes
The template in template_type (application, hris, secret_store, or secret_scanner) and the column mappings. See , and for the Secret Scanner template, .
provisioning
boolean
No
For the HRIS template, this is derived from csv_mapping_configuration.hris.hris_provisioning_source rather than set directly.
notification_preferences
object
No
Configure notifications for file upload and extraction status. See .
name
string
Yes
Provider name.
custom_template
string
Yes*
OAA template type, such as application, identity_provider, hris, principal, or secret_store.
custom_templates
array
Yes*
Use instead of custom_template to combine multiple templates on one provider, for example principal and application.
name
string
Yes
Provider name.
push_type
string
Yes
Set to CSV.
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:parts{
"csv_data": "abc123="
}CSV_PAYLOAD=$(cat my_app_data.csv | base64)
curl --location https://example.vezacloud.com/api/v1/providers/custom/40bdd318-d320-4574-be90-ca556d59889a/datasources/9bc29dc6-8cd0-4926-992e-7d720305ae2f:push_csv \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $VEZA_API_KEY" \
--data "{\"csv_data\": \"${CSV_PAYLOAD}\"}"cat app_payload.json | gzip | base64 -o json_data.b64payload = {"id": provider_id,
"data_source_id": data_source_id,
"json_data": json.dumps(template_contents)
}curl -X POST '{{VezaURL}}/api/v1/providers/custom/962d5eff-285c-4b08-a54e-400eead1e680:icon' \
-H "authorization: Bearer $API_KEY" \
-d '{"icon_base64": "PHN2ZyBmaWxsPSIjMDAwMDAwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciICB2aWV3Qm94PSIwIDAgNjQgNjQiIHdpZHRoPSIzMnB4IiBoZWlnaHQ9IjMycHgiPjxwYXRoIGQ9Ik0zMiA2QzE3LjY0MSA2IDYgMTcuNjQxIDYgMzJjMCAxMi4yNzcgOC41MTIgMjIuNTYgMTkuOTU1IDI1LjI4Ni0uNTkyLS4xNDEtMS4xNzktLjI5OS0xLjc1NS0uNDc5VjUwLjg1YzAgMC0uOTc1LjMyNS0yLjI3NS4zMjUtMy42MzcgMC01LjE0OC0zLjI0NS01LjUyNS00Ljg3NS0uMjI5LS45OTMtLjgyNy0xLjkzNC0xLjQ2OS0yLjUwOS0uNzY3LS42ODQtMS4xMjYtLjY4Ni0xLjEzMS0uOTItLjAxLS40OTEuNjU4LS40NzEuOTc1LS40NzEgMS42MjUgMCAyLjg1NyAxLjcyOSAzLjQyOSAyLjYyMyAxLjQxNyAyLjIwNyAyLjkzOCAyLjU3NyAzLjcyMSAyLjU3Ny45NzUgMCAxLjgxNy0uMTQ2IDIuMzk3LS40MjYuMjY4LTEuODg4IDEuMTA4LTMuNTcgMi40NzgtNC43NzQtNi4wOTctMS4yMTktMTAuNC00LjcxNi0xMC40LTEwLjQgMC0yLjkyOCAxLjE3NS01LjYxOSAzLjEzMy03Ljc5MkMxOS4zMzMgMjMuNjQxIDE5IDIyLjQ5NCAxOSAyMC42MjVjMC0xLjIzNS4wODYtMi43NTEuNjUtNC4yMjUgMCAwIDMuNzA4LjAyNiA3LjIwNSAzLjMzOEMyOC40NjkgMTkuMjY4IDMwLjE5NiAxOSAzMiAxOXMzLjUzMS4yNjggNS4xNDUuNzM4YzMuNDk3LTMuMzEyIDcuMjA1LTMuMzM4IDcuMjA1LTMuMzM4LjU2NyAxLjQ3NC42NSAyLjk5LjY1IDQuMjI1IDAgMi4wMTUtLjI2OCAzLjE5LS40MzIgMy42OTdDNDYuNDY2IDI2LjQ3NSA0Ny42IDI5LjEyNCA0Ny42IDMyYzAgNS42ODQtNC4zMDMgOS4xODEtMTAuNCAxMC40IDEuNjI4IDEuNDMgMi42IDMuNTEzIDIuNiA1Ljg1djguNTU3Yy0uNTc2LjE4MS0xLjE2Mi4zMzgtMS43NTUuNDc5QzQ5LjQ4OCA1NC41NiA1OCA0NC4yNzcgNTggMzIgNTggMTcuNjQxIDQ2LjM1OSA2IDMyIDZ6TTMzLjgxMyA1Ny45M0MzMy4yMTQgNTcuOTcyIDMyLjYxIDU4IDMyIDU4IDMyLjYxIDU4IDMzLjIxMyA1Ny45NzEgMzMuODEzIDU3Ljkzek0zNy43ODYgNTcuMzQ2Yy0xLjE2NC4yNjUtMi4zNTcuNDUxLTMuNTc1LjU1NEMzNS40MjkgNTcuNzk3IDM2LjYyMiA1Ny42MSAzNy43ODYgNTcuMzQ2ek0zMiA1OGMtLjYxIDAtMS4yMTQtLjAyOC0xLjgxMy0uMDdDMzAuNzg3IDU3Ljk3MSAzMS4zOSA1OCAzMiA1OHpNMjkuNzg4IDU3LjljLTEuMjE3LS4xMDMtMi40MTEtLjI4OS0zLjU3NC0uNTU0QzI3LjM3OCA1Ny42MSAyOC41NzEgNTcuNzk3IDI5Ljc4OCA1Ny45eiIvPjwvc3ZnPg=="}'custom_templates
Classes for constructing an OAA JSON payload for Secret Store
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
SecretStoreSubmissionClass for modeling Secret Store Template
SecretStore template consists of base information about the secret store instance, permissions, vaults, entries, and identity mappings.
Args:
name (str): Name for Secret Store Instance
secret_store_type (str): Type for Secret Store. Typically the vendor or product name.
unique_id (str): Unique identify for secret store instance. Optional, defaults to name.
skip_local_users_creation (bool, optional): Skip creation of local user identities for this secret store. Defaults to None.
Attributes:
secret_store (SecretStore): The secret store entity
property_definitions (SecretStorePropertyDefinitions): Custom property definitions
identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().
Get the OAA payload.
Returns the complete OAA template payload for Secret Store as serializable dictionary
Returns:
dict: OAA payload as dictionary
Raises:
OAATemplateException: If secret_store is not set
Create and set the identity mapping configuration.
Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.
Returns:
IdentityMappingConfigurationSubmission: The identity mapping configuration.
Secret Store Entity
Represents a secret store application with permissions, vaults, and identity mappings.
Args:
name (str): Display name for secret store
unique_id (str, optional): Unique identifier for secret store
description (str, optional): Description of the secret store
Add identity to permission mapping
Args:
identity (str): The identity ID
identity_type (str): The type of identity (e.g., "local_user")
permission_assignments (list[PermissionAssignment], optional): Permission assignments for this identity
Returns:
IdentityToPermission: The identity to permission mapping
Raises:
OAATemplateException: Identity to permission mapping for identity and identity_type already exists
Add a new Permission
Args:
name (str): Display name for permission
unique_id (str, optional): Unique identifier for permission. Defaults to name if not provided.
resource (str, optional): Resource this permission applies to
Returns:
SecretStorePermission: Entity for new permission
Raises:
OAATemplateException: Permission with ID already exists
Add a new tag to secret store.
Args:
key (str): Tag key/name
value (str, optional): Tag value. Defaults to "".
Add a new Vault
Args:
name (str): Display name for vault
vault_type (str): Type of vault (user-defined)
unique_id (str, optional): Unique identifier for vault. Defaults to name if not provided.
Returns:
SecretStoreVault: Entity for new vault
Raises:
OAATemplateException: Vault with ID already exists
Set secret store custom property value
Property name must be defined before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Return the dictionary representation of secret store.
Secret Store Permission Entity
Represents a permission in a secret store.
Args:
name (str): Display name for permission
unique_id (str, optional): Unique identifier for permission
resource (str, optional): Resource this permission applies to
Attributes:
permission_type (list[OAAPermission]): List of OAAPermission enums that represent the canonical permissions
Add a permission type to the permission_type list.
Extends the list of canonical OAAPermission types this permission grants.
Args:
permission_type (OAAPermission): The OAAPermission enum value to add
Raises:
OAATemplateException: If permission_type is not an OAAPermission enum
Add a new tag to permission.
Args:
key (str): Tag key/name
value (str, optional): Tag value. Defaults to "".
Set permission custom property value
Property name must be defined before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Return the dictionary representation of permission.
Secret Store Vault Entity
Represents a vault in a secret store.
Args:
name (str): Display name for vault
vault_type (str): Type of vault (user-defined)
unique_id (str, optional): Unique identifier for vault
Add a new Entry to vault
Args:
name (str): Display name for entry
unique_id (str, optional): Unique identifier for entry. Defaults to name if not provided.
description (str, optional): Description of the entry
Returns:
SecretStoreVaultEntry: Entity for new entry
Raises:
OAATemplateException: Entry with ID already exists
Add a new tag to vault.
Args:
key (str): Tag key/name
value (str, optional): Tag value. Defaults to "".
Set vault custom property value
Property name must be defined before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Return the dictionary representation of vault.
Secret Store Vault Entry Entity
Represents an entry (credential) in a vault.
Args:
name (str): Display name for entry
unique_id (str, optional): Unique identifier for entry
description (str, optional): Description of the entry
Add an identity to this vault entry
Args:
identity_type (str): The type of identity (e.g., "OktaUser", "AzureADUser")
external_id (str): The external ID of the identity
Returns:
VaultEntryIdentity: The identity entity
Add a new tag to entry.
Args:
key (str): Tag key/name
value (str, optional): Tag value. Defaults to "".
Set entry custom property value
Property name must be defined before calling set_property
Args:
property_name (str): Name of property
property_value (any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Return the dictionary representation of entry.
Vault Entry Identity
Represents identity information for a vault entry.
Args:
identity_type (str): The type of identity (e.g., "OktaUser", "AzureADUser")
external_id (str): The external ID of the identity
Return the dictionary representation of identity.
Identity to Permission Mapping
Maps an identity to permissions on vaults.
Args:
identity (str): The identity ID
identity_type (str): The type of identity (e.g., "local_user")
permission_assignments (list[PermissionAssignment], optional): Permission assignments for this identity
Add a permission assignment
Args:
vault (list[str]): List of vault IDs or names
permissions (list[str]): List of permission names
Returns:
PermissionAssignment: The permission assignment
Return the dictionary representation of identity to permission.
Permission Assignment
Assigns permissions to vaults.
Args:
vault (list[str]): List of vault IDs or names
permissions (list[str]): List of permission names
Return the dictionary representation of permission assignment.
Property Definitions for Secret Store entities
Define a custom property for entries
Args:
name (str): Property name
property_type (OAAPropertyType): Property type
Define a custom property for permissions
Args:
name (str): Property name
property_type (OAAPropertyType): Property type
Define a custom property for secret store
Args:
name (str): Property name
property_type (OAAPropertyType): Property type
Define a custom property for vaults
Args:
name (str): Property name
property_type (OAAPropertyType): Property type
Convert property definitions to dictionary
Check property name for valid characters
Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.
Args:
name (str): name of property to validate
Raises:
OAATemplateException: Name is not a string
OAATemplateException: Name contains invalid characters or does not start with a letter
Template for modeling configuration management databases with configuration items and owner correlation
Use this template to model a configuration management database using the . The CMDB template brings asset inventory into Veza as configuration items, and correlates each item to the identity that owns it and to the Veza entity it represents.
The template models a shallow structure:
CMDB instance - the source system, such as a ServiceNow or Freshservice tenant
Configuration item - one asset tracked in that system, such as a server, a database, or a laptop
Only the configuration item becomes an entity in the Authorization Graph. The instance supplies the cmdb_type
skip_local_users_creation (bool, optional): Skip creation of local user identities for this secret store.
allow_identity_assume (bool, optional): Whether this permission allows identity assumptionpermission_type (list[OAAPermission], optional): List of OAAPermission enums that represent the canonical permissions
description (str, optional): Description of the vaultallow_identity_assume (bool, optional): Whether this permission allows identity assumptionpermission_type (list[OAAPermission], optional): List of OAAPermission enums that represent the canonical permissions
description__init__(
name: 'str',
secret_store_type: 'str',
unique_id: 'str' = None,
skip_local_users_creation: 'Optional[bool]' = None
)get_payload() → dictset_identity_mapping_configuration() → IdentityMappingConfigurationSubmission__init__(name: 'str', unique_id: 'str' = None, description: 'str' = None)add_identity_to_permission(
identity: 'str',
identity_type: 'str',
permission_assignments: 'List[PermissionAssignment]' = None
) → IdentityToPermissionadd_permission(
name: 'str',
unique_id: 'str' = None,
resource: 'str' = None,
allow_identity_assume: 'bool' = None,
permission_type: 'List[OAAPermission]' = None
) → SecretStorePermissionadd_tag(key: 'str', value: 'str' = '') → Noneadd_vault(
name: 'str',
vault_type: 'str',
unique_id: 'str' = None,
description: 'str' = None
) → SecretStoreVaultset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str' = None,
resource: 'str' = None,
allow_identity_assume: 'bool' = None,
permission_type: 'List[OAAPermission]' = None
)add_permission_type(permission_type: 'OAAPermission') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
vault_type: 'str',
unique_id: 'str' = None,
description: 'str' = None
)add_entry(
name: 'str',
unique_id: 'str' = None,
description: 'str' = None
) → SecretStoreVaultEntryadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(name: 'str', unique_id: 'str' = None, description: 'str' = None)add_identity(identity_type: 'str', external_id: 'str') → VaultEntryIdentityadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(identity_type: 'str', external_id: 'str')to_dict() → dict__init__(
identity: 'str',
identity_type: 'str',
permission_assignments: 'List[PermissionAssignment]' = None
)add_permission_assignment(
vault: 'List[str]',
permissions: 'List[str]'
) → PermissionAssignmentto_dict() → dict__init__(vault: 'List[str]', permissions: 'List[str]')to_dict() → dict__init__()define_entry_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_permission_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_secret_store_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_vault_property(name: 'str', property_type: 'OAAPropertyType') → Noneto_dict() → dictvalidate_name(name: 'str') → NoneA custom property definition can define additional properties for configuration items.
To use the CMDB template, set the template type to cmdb when creating a new data provider:
cmdb_instances
array
Required. Array of objects
custom_property_definition
object
Declares custom properties per cmdb_type. See
An instance identifies the source system. It contributes cmdb_type to each of its configuration items and carries the correlation configuration.
name
string
Display name for the instance
cmdb_type
string
The kind of CMDB, for example Freshservice or ServiceNow. Labels every configuration item in the instance and keys the custom property definitions
configuration_items
array
Required. Array of objects
Veza does not check that name or cmdb_type is present. cmdb_type is a free-form string. Veza records the distinct values a provider has submitted so they can be filtered on, but does not restrict them to a fixed list.
A configuration item is one tracked asset. It is the only entity this template creates in the Authorization Graph.
id
string
Required. Identifier for the item, unique within its instance
name
string
Display name for the item
cmdb_asset_type
string
The kind of asset, for example Server or Laptop. Used to map the item to a Veza entity type. See
cmdb_asset_type is a free-form string. Veza does not validate it against a list, and values such as Server, Database, Application, and Laptop are conventions rather than an enumeration. Use whatever your source system calls the asset type.
What the value does is select how the item is correlated to the rest of the graph. Veza first looks for an entry in assetConnections whose assetTypeValue matches. When none matches, it attempts to infer the target entity type from the name, so common values resolve without configuration. Declaring the mapping explicitly is more reliable than relying on inference.
Two relationships make a configuration item useful: who owns the asset, and which Veza entity the asset already corresponds to. Both are resolved after the push, from values you supply, and both appear as properties on the configuration item rather than as relationships in the graph.
Two keys are sent inside custom_properties but are not custom properties. Veza reads them, promotes them to standard properties on the configuration item, and removes them from the custom property map.
owner_external_id
Identifies the person who owns the asset, typically an email address
asset_external_id
Identifies the Veza entity this item describes, typically a resource name
csc_global_config tells Veza where to look for each match.
ownerIdColumnName
string
The field in the source system that holds the owner identifier
assetIdColumnName
string
The field in the source system that holds the asset identifier
assetTypeColumnName
string
The field in the source system that holds the asset type
Each entry in assetConnections has three fields:
assetTypeValue
string
The cmdb_asset_type value this entry applies to
assetNodeType
string
The Veza entity type that asset type corresponds to
assetPropertyName
string
The property on that entity type to match asset_external_id against
assetNodeType must be an entity type that represents a resource, role, identity, or entitlement, written exactly as Veza names it, for example S3Bucket rather than AwsS3Bucket. An entry whose assetNodeType is not a valid entity type is skipped, and the push still succeeds, so a misspelled type falls back to inference without any error.
Veza matches owner_external_id against the named property on the named entity type, without regard to letter case, and records a match on the configuration item. If several entities share the same value, any one of them can be recorded, so match on a property that is unique. When nothing matches, Veza clears the owner rather than leaving a previous value in place, so a stale correlation cannot persist across pushes.
The asset side clears the same way when the item's cmdb_asset_type still maps to an entity type but no entity of that type matches asset_external_id. If the asset type no longer maps to any entity type, the previous asset correlation is left in place.
Neither side clears when its input is removed. Taking owner_external_id or asset_external_id off an item leaves that side's previous correlation in place, and removing csc_global_config leaves the previous owner in place.
Resolution runs after the payload has been processed, so a correlation can succeed on a later push once the integration owning the matched entity has been added.
Custom properties allow you to attach additional metadata to configuration items. Definitions are declared per cmdb_type, so one payload can carry definitions for several instances.
configuration_item_properties
Custom properties for configuration item entities
Configuration items are the only entity type in this template, so there is one scope. Property values must match their declared type. Supported types are described in Custom properties.
Custom properties are processed only when custom_property_definition is present. When it is absent, custom properties are ignored. When it is present, the push itself is accepted without checking custom properties. A property that the definition does not declare, or custom properties sent for a cmdb_type the definition does not cover, causes processing of the whole data source to fail after the push.
To create the OAA provider and push data:
Create the provider with the cmdb template type:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyCMDB","custom_template":"cmdb"}'Create a data source on the provider:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"my_cmdb_source"}'Push the payload to the data source:
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.
Updates follow the same push workflow. Veza processes the full payload and replaces the contents of that data source.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyCMDB","custom_template":"cmdb"}'"cmdb_instances": [
{
"name": "Freshservice",
"cmdb_type": "Freshservice",
"configuration_items": [],
"csc_global_config": {}
}
]"configuration_items": [
{
"id": "ci-1001",
"name": "web-server-01",
"cmdb_asset_type": "Server",
"cmdb_id": "1001",
"cmdb_url": "https://cmdb.example.com/ci/1001",
"status": "active",
"asset_tag": "ASSET-001",
"serial_number": "SN-44120",
"location": "IAD1",
"department": "Engineering",
"cost_center": "eng-platform",
"environment": "production",
"is_active": true,
"custom_properties": {}
}
]"csc_global_config": {
"ownerIdColumnName": "Managed By",
"assetIdColumnName": "Host Name",
"assetTypeColumnName": "Asset Type",
"ownerNodeType": "OktaUser",
"ownerIdProperty": "email",
"assetConnections": [
{
"assetTypeValue": "AWS S3 Bucket",
"assetNodeType": "S3Bucket",
"assetPropertyName": "name"
}
]
}"custom_property_definition": {
"cmdb_instances": [
{
"cmdb_type": "Freshservice",
"configuration_item_properties": {
"owner_external_id": "STRING",
"patch_group": "STRING"
}
}
]
}Shared base classes, enums and identity-mapping submission types used across the OAA templates.
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
Helper function to simplify appending.
Handles multiple cases:
cmdb_instancesAsset types come from the customer's own catalog, so cmdb_asset_type holds whatever the tenant has configured rather than a Veza-defined value.
is_active is derived, not copied. Freshservice records a detailed asset state, and the integration treats only assets in use as active.
The item ID becomes the asset correlation value when the administrator has configured an asset ID column, which lets the configuration item and the cloud resource it describes share an identifier.
Correlation fields are administrator-supplied. Freshservice exposes display labels rather than fixed field names, so the column names in csc_global_config are whatever the tenant calls them.
csc_global_config
object
Correlation configuration for resolving owners and assets
cmdb_id
string
The item's native identifier in the source system (optional)
cmdb_url
string
Link to the item in the source system (optional)
status
string
Status as reported by the source system (optional)
asset_tag
string
Asset tag (optional)
serial_number
string
Serial number (optional)
location
string
Location (optional)
department
string
Department (optional)
cost_center
string
Cost center (optional)
environment
string
Environment, for example production (optional)
is_active
boolean
Whether the item is currently in service
custom_properties
dictionary
Custom properties validated against configuration_item_properties, plus the two reserved correlation keys
ownerNodeType
string
The Veza entity type to search for the owner, for example OktaUser
ownerIdProperty
string
The property on that entity type to match owner_external_id against, for example email
assetConnections
array
Maps asset type values to Veza entity types. See below
addition is list: extends base with list
addition is anything else: append element to list
Args:
base (List or None): base list to append to, can be None
addition (*): What to append to the list
Returns:
list: will always return a list
Returns a list of unique strings from input list case insensitive
Returns the unique list of strings from input list in a case insensitive manner. For duplicate strings with different cast (e.g. "STRING" and "string") the case of the first occurrence is returned.
Args:
input (list): list of strings
Returns:
list: list of unique strings
Veza supported IdP provider types.
Node types for entity owners
Supported types for custom properties on OAA entities such as application, resource, and identity.
Identity mapping match type.
Corresponds to IdentityMapping.Type in identitymapping.proto.
Identity mapping mode.
Corresponds to IdentityMapping.Mode in identitymapping.proto.
Identity mapping transformation applied to identity values before matching.
Corresponds to IdentityMapping.Transformations in identitymapping.proto.
Identity property used as source or destination in a property matcher.
Corresponds to IdentityMapping.Property in identitymapping.proto.
Base class for CustomProvider.
Veza Tag data model.
Args:
key (str): key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only.
Attributes:
key (str): key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str): Value for tag, will appear in Veza as key:value. Must be letters, numbers and the special characters @,._ only.
Identity mapping configuration submission.
Top-level container for identity mapping configuration in an OAA payload.
Args:
use_email (bool): Whether to use email for identity mapping. Defaults to False.
operation (str, optional): Operation type for this configuration.
Attributes:
use_email (bool): Whether to use email for identity mapping. Default False.
mappings (list[IdentityMappingSubmission]): List of identity mappings.
operation (str): Operation type. Default None.
Add an identity mapping.
Args:
destination_datasource_type (str): Destination datasource type.
destination_datasource_oaa_type (str): Destination datasource OAA app type.
mapping_type (str): Mapping type. Use IdentityMappingType for valid values.
mapping_mode (str, optional): Mapping mode. Use IdentityMappingMode for valid values. Defaults to "".
transformations (list[str], optional): List of transformations. Use IdentityMappingTransformation for valid values. Defaults to None.
custom_value (str, optional): Custom value. Defaults to "".
Returns:
IdentityMappingSubmission: The new mapping.
Return the dictionary representation.
Identity mapping submission.
Represents a single identity mapping configuration entry.
Args:
destination_datasource_type (str): Destination datasource type.
destination_datasource_oaa_type (str): Destination datasource OAA app type.
mapping_type (str): Mapping type (serialized as type). Use IdentityMappingType for valid values.
mapping_mode (str, optional): Mapping mode (serialized as mode). Use IdentityMappingMode for valid values. Defaults to "".
transformations (list[str], optional): List of transformations. Use IdentityMappingTransformation for valid values. Defaults to None.
custom_value (str, optional): Custom value. Defaults to "".
Attributes:
destination_datasource_type (str): Destination datasource type.
destination_datasource_oaa_type (str): Destination datasource OAA app type.
mapping_type (IdentityMappingType): Mapping type.
mapping_mode (IdentityMappingMode): Mapping mode.
transformations (list[IdentityMappingTransformation]): List of transformations.
custom_value (str): Custom value.
property_matchers (list[IdentityMappingPropertyMatchersSubmission]): Property matchers.
destination_datasources (list[IdentityMappingDestinationDatasourceSubmission]): Destination datasources.
Add a destination datasource.
Args:
datasource_type (str): Datasource type.
oaa_type (str): OAA app type.
Returns:
IdentityMappingDestinationDatasourceSubmission: The new destination datasource.
Add a property matcher.
Args:
source_property (str): Source property to match on. Use IdentityMappingProperty for valid values.
destination_property (str): Destination property to match against. Use IdentityMappingProperty for valid values.
custom_source_property (str, optional): Custom source property name, used when source_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".
custom_destination_property (str, optional): Custom destination property name, used when destination_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".
Returns:
IdentityMappingPropertyMatchersSubmission: The new property matcher.
Return the dictionary representation.
Identity mapping property matcher.
Defines how source and destination properties are matched.
Args:
source_property (str): Source property to match on. Use IdentityMappingProperty for valid values.
destination_property (str): Destination property to match against. Use IdentityMappingProperty for valid values.
custom_source_property (str, optional): Custom source property name, used when source_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".
custom_destination_property (str, optional): Custom destination property name, used when destination_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".
Return the dictionary representation.
Identity mapping destination datasource.
Specifies a destination datasource for an identity mapping.
Args:
datasource_type (str): Datasource type (serialized as type).
oaa_type (str): OAA app type (serialized as oaa_app_type).
Return the dictionary representation.
{
"cmdb_instances": [
{
"name": "Example CMDB",
"cmdb_type": "ExampleCMDB",
"csc_global_config": {
"ownerIdColumnName": "Managed By",
"assetIdColumnName": "Host Name",
"assetTypeColumnName": "Asset Type",
"ownerNodeType": "OktaUser",
"ownerIdProperty": "email",
"assetConnections": [
{
"assetTypeValue": "AWS S3 Bucket",
"assetNodeType": "S3Bucket",
"assetPropertyName": "name"
}
]
},
"configuration_items": [
{
"id": "ci-1001",
"name": "web-server-01",
"cmdb_asset_type": "Server",
"cmdb_id": "1001",
"cmdb_url": "https://cmdb.example.com/ci/1001",
"status": "active",
"asset_tag": "ASSET-001",
"serial_number": "SN-44120",
"location": "IAD1",
"department": "Engineering",
"cost_center": "eng-platform",
"environment": "production",
"is_active": true,
"custom_properties": {
"owner_external_id": "alice@example.com",
"asset_external_id": "web-server-01",
"patch_group": "weekly"
}
},
{
"id": "ci-1002",
"name": "reports-archive",
"cmdb_asset_type": "AWS S3 Bucket",
"cmdb_id": "1002",
"status": "active",
"is_active": true,
"custom_properties": {
"owner_external_id": "bob@example.com",
"asset_external_id": "reports-archive"
}
}
]
}
],
"custom_property_definition": {
"cmdb_instances": [
{
"cmdb_type": "ExampleCMDB",
"configuration_item_properties": {
"owner_external_id": "STRING",
"patch_group": "STRING"
}
}
]
}
}{
"cmdb_instances": [
{
"name": "Freshservice",
"cmdb_type": "Freshservice",
"csc_global_config": {
"ownerIdColumnName": "Managed By",
"assetIdColumnName": "Host Name",
"assetTypeColumnName": "Asset Type",
"ownerNodeType": "OktaUser",
"ownerIdProperty": "email",
"assetConnections": [
{
"assetTypeValue": "AWS S3 Bucket",
"assetNodeType": "S3Bucket",
"assetPropertyName": "name"
},
{
"assetTypeValue": "AWS Security Group",
"assetNodeType": "EC2SecurityGroup",
"assetPropertyName": "name"
}
]
},
"configuration_items": [
{
"id": "asset-4471",
"name": "LT-4471",
"cmdb_asset_type": "Laptop",
"cmdb_id": "4471",
"cmdb_url": "https://example.freshservice.com/cmdb/items/4471",
"status": "In Use",
"asset_tag": "ASSET-4471",
"serial_number": "C02XL0ABCDEF",
"is_active": true,
"custom_properties": {
"owner_external_id": "alice@example.com"
}
},
{
"id": "reports-archive",
"name": "reports-archive",
"cmdb_asset_type": "AWS S3 Bucket",
"cmdb_id": "4482",
"status": "In Use",
"is_active": true,
"custom_properties": {
"owner_external_id": "bob@example.com",
"asset_external_id": "reports-archive"
}
}
]
}
],
"custom_property_definition": {
"cmdb_instances": [
{
"cmdb_type": "Freshservice",
"configuration_item_properties": {
"owner_external_id": "STRING"
}
}
]
}
}append_helper(base, addition)unique_strs(input: 'list') → list__init__(name, custom_template)serialize()__init__(key: 'str', value: 'str' = '') → None__init__(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → None__init__() → Noneadd_mapping(
destination_datasource_type: 'str',
destination_datasource_oaa_type: 'str',
mapping_type: 'str',
mapping_mode: 'str' = '',
transformations: 'List[str]' = None,
custom_value: 'str' = ''
) → IdentityMappingSubmissionto_dict() → dict__init__(
destination_datasource_type: 'str',
destination_datasource_oaa_type: 'str',
mapping_type: 'str',
mapping_mode: 'str' = '',
transformations: 'List[str]' = None,
custom_value: 'str' = ''
) → Noneadd_destination_datasource(
datasource_type: 'str',
oaa_type: 'str'
) → IdentityMappingDestinationDatasourceSubmissionadd_property_matcher(
source_property: 'str',
destination_property: 'str',
custom_source_property: 'str' = '',
custom_destination_property: 'str' = ''
) → IdentityMappingPropertyMatchersSubmissionto_dict() → dict__init__(
source_property: 'str',
destination_property: 'str',
custom_source_property: 'str' = '',
custom_destination_property: 'str' = ''
) → Noneto_dict() → dict__init__(datasource_type: 'str', oaa_type: 'str') → Noneto_dict() → dictApplying additional metadata to OAA entities
In addition to built-in fields such as last_login_at, OAA supports custom-named properties for users, resources, groups, and other entities in a payload. Custom properties are validated against a set of custom property definitions as part of the JSON payload.
To use custom properties:
Include a definition of all properties as part of the payload push. The definition sets the type for the property.
Set the custom properties for each object.
Built-in properties (such as last_login
created_atis_activeIf a built-in property doesn’t exist for the provider you are modeling, you can define custom properties in the OAA payload. This can enable sophisticated queries on many possible fields (such as encryption_enabled, password_last_used_at). Custom properties have a declared data type and are indexed and filterable, like any built-in property.
For example, you could use the custom string property "state" for an app that can be either "active," "suspended," or "disabled." If there's only one state, you could instead use a boolean ("active": "false").
Custom Properties are defined as part of the custom_property_definition section and require a type. Typing the data allows Veza to provide a better index and search experience. For example, the TIMESTAMP type enables date-relative filters such as "in the last 30 days."
Allowed types are NUMBER, STRING, STRING_LIST, TIMESTAMP, and BOOLEAN.
A type is required and permanent.
Dates must be in RFC3339 format, which can include a timezone offset or use UTC (2021-01-01T22:47:31-07:00, 2021-01-01T22:47:31Z).
The maximum length of a string is 4096 characters.
In the Veza UI, underscores in property names are replaced by spaces, and first letters are capitalized (is_licensed > Is Licensed).
If a custom property name collides with an existing built-in property, Veza will add the "Custom" prefix (ID > Custom Id).
In the Query Builder API, custom properties are prefixed with custom_ in responses and must be prefixed with custom_ when used in filter statements.
Once pushed, properties and types can't be altered. You can re-submit the payload with additional custom property definitions to add new properties.
Property values on entities can be modified by pushing a complete payload with new custom_properties or using incremental update operations.
The provider must be deleted and pushed again to remove properties from a definition or change their types.
The original custom property definition is not required in future submissions but should be saved for later reference.
Here are some example custom property definitions for the custom application and custom identity provider templates.
The Python SDK also supports creating and setting custom properties.
A custom property definition sets possible properties, their types, and the application or resource type they can apply to. The following entities can have custom properties:
Custom Application
application_properties
Scoped by application_type
Custom User
local_user_properties
Custom Group
local_group_properties
The following example shows a custom property definition for GitLab:
Properties are set on users and resources in custom_properties:
Custom IdP Domain
domain_properties
Custom IdP User
user_properties
Custom IdP Group
group_properties
app = CustomApplication(name="Demo", application_type="Demo")
# Define a new local user string property `email`
app.property_definitions.define_local_user_property("email", OAAPropertyType.STRING)
local_user = app.add_local_user(name="name", unique_id="user_id")
# set the property by name
local_user.set_property("email", "user@example.com") "custom_property_definition": {
"applications": [
{
"application_type": "GitLab",
"application_properties": {},
"local_user_properties": {
"id": "NUMBER",
"bot": "BOOLEAN",
"is_licensed": "BOOLEAN",
"state": "STRING"
},
"local_group_properties": {},
"local_role_properties": {},
"role_assignment_properties": {
"assigned_at": "TIMESTAMP",
"expires_at": "TIMESTAMP"
},
"local_access_creds_properties": {
"scope": "STRING",
"rotation_period_days": "NUMBER"
},
"resources": [
{
"resource_type": "project",
"properties": {
"id": "NUMBER",
"visibility": "STRING"
}
}
]
}
]
}{
"name": "support-bot",
"identities": ["support@cookie.ai"],
"groups": null,
"is_active": true,
"created_at": "2022-01-25T18:55:19.146Z",
"last_login_at": null,
"deactivated_at": null,
"password_last_changed_at": null,
"tags": [],
"custom_properties": {
"id": 7,
"is_licensed": false,
"state": "active",
"bot": true
}
}{
"custom_property_definition": {
"domain_properties": null,
"group_properties": {
"group_lead": "STRING"
},
"user_properties": {
"birthday": "TIMESTAMP",
"description": "STRING",
"last_login": "TIMESTAMP",
"is_licensed": "BOOLEAN",
"region": "STRING"
}
},
"name": "My IdP",
"id": "custom_idp",
"domains": [
{
"name": "domain.biz"
}
],
"users": [
{
"name": "Colby Smith",
"custom_properties": {
"is_licensed": false,
"region": "US-West"
}
}
]
}This document provides a high-level overview and examples for getting started with a new OAA connector to integrate Veza with SaaS applications, infrastructure systems, custom-built applications, and other systems. These examples use Python and the oaaclient SDK.
When developing a connector, the source systems and customer needs can require changes to code flow for different deployment scenarios. The overall goals, best practices, and flow will apply for most integrations:
The sample code was written with the following goals in mind:
Connector should be easy to run from automation platforms and the command line.
Parameters are passed through environment variables as well as command line flags. This makes the code easier to package into containers or serverless stacks and control through outside configuration. Connectors by nature require secrets such as the Veza API key. Managing these through variables affords additional options for secrets management.
Custom Role
local_role_properties
Role Assignment
role_assignment_properties
Properties on the role assignment itself, not the role
Access Credential
local_access_creds_properties
Custom Resource
resources
Scoped by resource_type
Connectors do not require state:
Connectors do not require any persistent data between runs.
There is no special invocation for the first run or subsequent runs.
The connector handles all of the logic for provider and data source creation internally, as needed, or by discovering existing ones.
Data Source name should be unique to the discovered environment. This can be achieved by including a hostname or instance ID in the data source name: discoverable by the code and consistent between runs. This ensures that two instances of the same connector do not interfere with each other if discovering separate instances of the application. When such a property cannot be determined, a command line parameter is an option.
Connector code is importable:
The flexibility to import connector code into another piece of Python code enables a setup wrapper to handle job management tasks such as:
Secrets management
Output logging
Other configurations required by the environment
A separate run function implements connector end-to-end logic. This can be imported and invoked by providing the necessary parameters. The main function that runs when invoked from the command line should only process command line inputs and environment variables for setup.
The exact flow of the connector can change to meet specific requirements, but the general steps are as follows:
Process and validate configuration parameters. Ensure you have supplied all necessary values such as host names, user names, and API keys.
Call the main run function with all the required and optional parameters.
Initialize the oaaclient connection to the Veza tenant. Initializing the client verifies that the Veza URL and API key are valid before starting any application discovery.
Create an instance of the oaaclient.templates.CustomApplication to populate with the application information.
Connect to the system and perform discovery of required entities:
The discovery order for users, groups, roles, and so on can be changed based on relationships and interface.
Populate the CustomApplication instance with the identity, roles and permissions, resources, and authorization information.
Check if Provider and Data Source exist on Veza. Create them if they do not exist.
Push the application to the Data Source. The SDK creates the JSON payload from the CustomApplication instance.
Process any returned warnings or errors.
Exit.
Update the Provider Name, App Type, and Application Name based on the source system. These values will typically be set to the product name. The data source name must be unique - check that an appropriate distinguishing value such as hostname is included in the data source name. For more information on naming, see Providers, Data Sources, Names and Types
Define any custom properties needed in the __init__ method. Properties must be defined on the CustomApplication entities before setting them.
Implement the discovery steps for the discover() function to collect Users, Groups, Roles, and any resources for the application. As the entities are discovered, add them to the CustomApplication object using the appropriate .
Run the connector to validate the output in Veza.
Automate the connector to run on a regular schedule.
The code below can serve as a template and the comments explain the reasoning beyond the patterns.
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import json
import logging
import os
import sys
import requests
from requests.exceptions import HTTPError, RequestException
from oaaclient.client import OAAClient, OAAClientError
from oaaclient.templates import CustomApplication, OAAPermission, OAAPropertyType, LocalUser
import oaaclient.utils as oaautils
"""
Logging in connectors is very important. Establishing a local logging function here
allows the connector log even if its imported into another block of code
"""
logging.basicConfig(
format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
log = logging.getLogger(__name__)
"""
The main logic for connecting to the destination application.
Authorization data collection and OAA template population should be structured into a class.
The class can store the authentication tokens making connections through an API or SDK easier.
The class should also instantiate the OAA CustomApplication or CustomIdP class
to manage populating all the identity, resource and authorization data.
"""
class OAAConnector():
APP_TYPE="SampleApp"
def __init__(self, auth_token: str) -> None:
self.auth_token = auth_token
# Set the application name and type. The type will generally be the vendor or product.
# The App Name can be the same, or contain additional context like the instance name.
app_name = "My App - West"
self.app = CustomApplication(app_name, application_type=self.APP_TYPE)
# declaring custom properties as part of the `__init__` keeps them together
self.app.property_definitions.define_local_user_property("email", OAAPropertyType.STRING)
self.app.property_definitions.define_local_user_property("has_mfa", OAAPropertyType.BOOLEAN)
"""
A `discover` method that starts the discovery cycle.
The discovery cycle should be invoked separately from the init.
More complex connectors may have additional setup steps between init and discovery
"""
def discover(self) -> None:
"""Discovery method"""
log.info(
"Start App discovery") # Start and stop log messages provide progress as discovery proceeds
self._discover_users()
self._discover_roles()
log.info("Finished App discovery")
return
"""
Smaller functions to perform portions of the discovery like users, groups, roles
should be private `_` functions to imply that they should not be run alone,
unless care is taken to ensure no dependencies.
For example, discovery of roles may assume that users are already discovered.
"""
def _discover_users(self) -> None:
log.info("Start user discovery")
# perform user discovery, for example process each user returned from an API call
for user in self._api_get("/Users"):
local_user = self.app.add_local_user(id=user["id"], name=user["name"])
local_user.is_active = user["active"]
local_user.set_property("has_mfa", user["mfa_enabled"])
log.info("Finished user discovery")
return
def _discover_roles(self) -> None:
log.info("Start role discovery")
# perform user discovery
log.info("Finished role discovery")
return
"""
Any required methods to interface with the application should be defined
as part of the class. Not all connectors need these methods, as they may use
other SDKs to interface with the application.
"""
def _api_get(self, path: str) -> dict:
# implement logic to make API call, process results, handle errors, retries ect.
# Could be done with a vendor SDK, SQL, or any method supported by the application
return {}
"""
A run function that is separate from `main` makes it easy to import the connector
into another piece of Python code. This may be useful to call the connector from
code that retrieves secrets or manages the job in other ways.
All necessary parameters should be taken in through the `run` function
"""
def run(veza_url: str, veza_api_key: str, app_key: str, **config_args) -> None:
# Process any configuration arguments
if config_args.get("debug"):
log.setLevel(logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.INFO)
log.info("Enabling debug logging")
else:
log.setLevel(logging.INFO)
save_json = config_args.get("save_json", False)
if not isinstance(save_json, bool):
raise TypeError("save_json argument must be boolean")
# Connect to the Veza instance before discovery to validate that the credentials are valid
try:
conn = OAAClient(url = veza_url, api_key = veza_api_key)
except OAAClientError as error:
log.error(f"Unable to connect to Veza {veza_url}")
log.error(error.message)
# run function should raise any exception so that they can be handled by the parent code, never exit
raise error
# Initialize the connector class and run discovery
try:
app = OAAConnector(auth_token=app_key)
app.discover()
except RequestException as e:
# process possible exceptions from the app discovery
log.error("Error during discovery")
log.error(f"{e} - {e.response.status_code} {e.response.text}")
raise e
# After discovery is complete, set up the Provider and Data Source to push the data to
# Provider name should be consistent with the vendor and application
provider_name = "My App"
provider = conn.get_provider(provider_name)
if provider:
log.info("found existing provider")
else:
log.info(f"creating provider {provider_name}")
provider = conn.create_provider(provider_name, "application", base64_icon=APP_SVG_B64)
log.info(f"provider: {provider['name']} ({provider['id']})")
# Data Source name should be unique to the instance of the app that is discovered but consistent.
# For example the hostname of the application or deployment name. Do not use something that will change.
data_source_name = f"App - {app.unique_identifier}"
try:
log.info("uploading application data")
response = conn.push_application(provider_name,
data_source_name = data_source_name,
application_object = app.app,
save_json = save_json
)
# An OAA Push can succeed with warnings, you can log out the warnings
if response.get("warnings", None):
log.warning("Push succeeded with warnings:")
for e in response["warnings"]:
log.warning(e)
log.info("success")
except OAAClientError as error:
# if there is an issue with the OAA payload the error details should contain useful information to help resolve the problem
log.error(f"{error.error}: {error.message} ({error.status_code})")
if hasattr(error, "details"):
for detail in error.details:
log.error(detail)
raise error
return
"""
Setting an application icon helps visually identify the app in the Veza UI.
A Base64 encoding of an SVG or PNG in the app code is an option.
You can also import an icon from a file with `oaaclient.utils.encode_icon_file`.
"""
APP_SVG_B64 = """
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pg0KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFRE
IFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4NCjxzdmcgd2lkdGg9IjQwMCIgaGVpZ2h0
PSI0MDAiIHZpZXdCb3g9IjAgMCAyMDAgMjAwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPg0KICA8cGF0aCBmaWxsPSJyZWQiIHN0cm9r
ZT0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIyLjUiIGQ9Ik0xNjggMTY4SDMyVjMyaDEzNnoiLz4NCjwvc3ZnPg0K
"""
"""
The main entry point should only deal with processing parameters and invoking
the run function. No OAA or application discovery should happen during the main
function. All required parameters should be configurable through the OS
environment. It should be possible to run the connector from the command line
with no arguments.
"""
def main():
"""
process command line and OS environment variables, then call `run`
"""
parser = argparse.ArgumentParser(description = "OAA Connector")
# using the `default=os.getenv()` pattern makes it easier to get parameters from command line or OS environment
parser.add_argument("--veza-url", default=os.getenv("VEZA_URL"), help="the URL of the Veza instance")
parser.add_argument("--debug", action="store_true", help="Set the log level to debug")
parser.add_argument("--save-json", action="store_true", help="Save OAA JSON payload to file")
args = parser.parse_args()
# Secrets should only be passed in through ENV
veza_api_key = os.getenv("VEZA_API_KEY")
veza_url = args.veza_url
save_json = args.save_json
if not veza_api_key:
oaautils.log_arg_error(log, None, "VEZA_API_KEY")
if not veza_url:
oaautils.log_arg_error(log, "--veza-url", "VEZA_URL")
# ensure required variables are provided
if None in [veza_api_key, veza_url]:
log.error(f"missing one or more required parameters")
sys.exit(1)
try:
run( veza_url=veza_url, veza_api_key=veza_api_key, save_json=save_json, debug=args.debug)
except (OAAClientError, RequestException):
log.error("Exiting with error")
sys.exit(1)
if __name__ == "__main__":
# replace the log with the root logger if running as main
log = logging.getLogger()
logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
main()Usage examples for the oaaclient Python SDK
The examples on this page can be used as a starting point for building new connectors for custom applications. You should also refer to the current list of for real-world examples, and to check if an integration already exists for your use case.
To run the code, you will need to export environment variables for the Veza URL, user and API keys, for example:
Veza API key for authentication. Generate keys in Administration > API Keys.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
OK
Unique identifier for the provider instance.
External identifier for the provider, typically set by the integration that created it.
Display name of the provider.
The OAA template type used to create this provider (e.g., "application", "idp").
List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").
Current provider state.
Application type classifications for this provider.
Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.
Identity provider type classifications (if this provider represents an IdP).
File system type classifications (if this provider represents a file system).
HRIS system type classifications (if this provider represents an HR system).
Principal (identity) type classifications for this provider.
Whether provisioning (write-back) operations are enabled for this provider.
JSON string containing the provider's connection configuration parameters.
Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.
Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.
Identifier of the team that owns this provider instance.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2025
{
"name": "text",
"custom_template": "text",
"provisioning": true,
"push_type": 1,
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"custom_templates": [
"text"
],
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text"
}
],
"external_lifecycle_management_type": 1,
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}{
"value": {
"id": "text",
"external_id": "text",
"name": "text",
"custom_template": "text",
"custom_templates": [
"text"
],
"state": 1,
"application_types": [
"text"
],
"idp_types": [
"text"
],
"file_system_types": [
"text"
],
"hris_types": [
"text"
],
"principal_types": [
"text"
],
"secret_store_types": [
"text"
],
"host_types": [
"text"
],
"schema_definition_json": "text",
"provisioning": true,
"push_type": 1,
"rbac_id": "text",
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"lifecycle_management_state": 1,
"team_id": "text",
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
],
"external_lifecycle_management_type": 1,
"cmdb_types": [
"text"
],
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}
}Veza API key for authentication. Generate keys in Administration > API Keys.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
OK
Unique identifier for the provider instance.
External identifier for the provider, typically set by the integration that created it.
Display name of the provider.
The OAA template type used to create this provider (e.g., "application", "idp").
List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").
Current provider state.
Application type classifications for this provider.
Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.
Identity provider type classifications (if this provider represents an IdP).
File system type classifications (if this provider represents a file system).
HRIS system type classifications (if this provider represents an HR system).
Principal (identity) type classifications for this provider.
Whether provisioning (write-back) operations are enabled for this provider.
JSON string containing the provider's connection configuration parameters.
Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.
Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.
Identifier of the team that owns this provider instance.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2025
{
"name": "text",
"custom_template": "text",
"provisioning": true,
"push_type": 1,
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"custom_templates": [
"text"
],
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text"
}
],
"external_lifecycle_management_type": 1,
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}{
"value": {
"id": "text",
"external_id": "text",
"name": "text",
"custom_template": "text",
"custom_templates": [
"text"
],
"state": 1,
"application_types": [
"text"
],
"idp_types": [
"text"
],
"file_system_types": [
"text"
],
"hris_types": [
"text"
],
"principal_types": [
"text"
],
"secret_store_types": [
"text"
],
"host_types": [
"text"
],
"schema_definition_json": "text",
"provisioning": true,
"push_type": 1,
"rbac_id": "text",
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"lifecycle_management_state": 1,
"team_id": "text",
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
],
"external_lifecycle_management_type": 1,
"cmdb_types": [
"text"
],
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}
}Retrieve all custom (OAA) providers configured in the tenant. Custom providers represent integrations built using the Open Authorization API (OAA), including both Veza-managed connectors and customer-built integrations. Use the filter parameter to narrow results by name, state, or custom_template (e.g., filter=name eq "My App"). Set page_size to control results per page (default varies), and use page_token from the response to retrieve subsequent pages.
Veza API key for authentication. Generate keys in Administration > API Keys.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
OK
Paginated list of custom (OAA) providers.
Unique identifier for the provider instance.
External identifier for the provider, typically set by the integration that created it.
Display name of the provider.
The OAA template type used to create this provider (e.g., "application", "idp").
List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").
Current provider state.
Application type classifications for this provider.
Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.
Identity provider type classifications (if this provider represents an IdP).
File system type classifications (if this provider represents a file system).
HRIS system type classifications (if this provider represents an HR system).
Principal (identity) type classifications for this provider.
Whether provisioning (write-back) operations are enabled for this provider.
JSON string containing the provider's connection configuration parameters.
Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.
Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.
Identifier of the team that owns this provider instance.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
Token to retrieve the next page of results. Empty when no more pages exist.
If true, additional pages of results are available.
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"values": [
{
"id": "text",
"external_id": "text",
"name": "text",
"custom_template": "text",
"custom_templates": [
"text"
],
"state": 1,
"application_types": [
"text"
],
"idp_types": [
"text"
],
"file_system_types": [
"text"
],
"hris_types": [
"text"
],
"principal_types": [
"text"
],
"secret_store_types": [
"text"
],
"host_types": [
"text"
],
"schema_definition_json": "text",
"provisioning": true,
"push_type": 1,
"rbac_id": "text",
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"lifecycle_management_state": 1,
"team_id": "text",
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
],
"external_lifecycle_management_type": 1,
"cmdb_types": [
"text"
],
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}
],
"next_page_token": "text",
"has_more": true
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Unique identifier for the provider instance.
External identifier for the provider, typically set by the integration that created it.
Display name of the provider.
The OAA template type used to create this provider (e.g., "application", "idp").
List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").
Current provider state.
Application type classifications for this provider.
Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.
Identity provider type classifications (if this provider represents an IdP).
File system type classifications (if this provider represents a file system).
HRIS system type classifications (if this provider represents an HR system).
Principal (identity) type classifications for this provider.
Whether provisioning (write-back) operations are enabled for this provider.
JSON string containing the provider's connection configuration parameters.
Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.
Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.
Identifier of the team that owns this provider instance.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom/{id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"value": {
"id": "text",
"external_id": "text",
"name": "text",
"custom_template": "text",
"custom_templates": [
"text"
],
"state": 1,
"application_types": [
"text"
],
"idp_types": [
"text"
],
"file_system_types": [
"text"
],
"hris_types": [
"text"
],
"principal_types": [
"text"
],
"secret_store_types": [
"text"
],
"host_types": [
"text"
],
"schema_definition_json": "text",
"provisioning": true,
"push_type": 1,
"rbac_id": "text",
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"lifecycle_management_state": 1,
"team_id": "text",
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
],
"external_lifecycle_management_type": 1,
"cmdb_types": [
"text"
],
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}
}Veza API key for authentication. Generate keys in Administration > API Keys.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
OK
Unique identifier for the provider instance.
External identifier for the provider, typically set by the integration that created it.
Display name of the provider.
The OAA template type used to create this provider (e.g., "application", "idp").
List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").
Current provider state.
Application type classifications for this provider.
Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.
Identity provider type classifications (if this provider represents an IdP).
File system type classifications (if this provider represents a file system).
HRIS system type classifications (if this provider represents an HR system).
Principal (identity) type classifications for this provider.
Whether provisioning (write-back) operations are enabled for this provider.
JSON string containing the provider's connection configuration parameters.
Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.
Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.
Identifier of the team that owns this provider instance.
Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.
Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.
Default vault type applied to vaults that do not map a vault_type column.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
For external OAA, how to manage lifecycle management requests
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
PATCH /api/v1/providers/custom/{provider.id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1929
{
"id": "text",
"configuration_json": "text",
"data_plane_id": "text",
"provisioning": true,
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text"
}
],
"external_lifecycle_management_type": 1,
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}{
"value": {
"id": "text",
"external_id": "text",
"name": "text",
"custom_template": "text",
"custom_templates": [
"text"
],
"state": 1,
"application_types": [
"text"
],
"idp_types": [
"text"
],
"file_system_types": [
"text"
],
"hris_types": [
"text"
],
"principal_types": [
"text"
],
"secret_store_types": [
"text"
],
"host_types": [
"text"
],
"schema_definition_json": "text",
"provisioning": true,
"push_type": 1,
"rbac_id": "text",
"internal_app_name": "text",
"configuration_json": "text",
"data_plane_id": "text",
"lifecycle_management_state": 1,
"team_id": "text",
"csv_mapping_configuration": {
"template_type": "text",
"column_mappings": [
{
"column_name": "text",
"destination_type": "text",
"destination_property": "text",
"custom_property": {
"name": "text",
"type": 1,
"lcm_unique_identifier": true
},
"as_list": true,
"template": "text",
"property_type": 1,
"is_required": true
}
],
"application": {
"application_name": "text",
"application_type": "text",
"identity": [
"text"
],
"resource_type": "text",
"okta_app_id": "text"
},
"advanced": {
"list_delimiter": "text"
},
"idp": {
"idp_type": "text",
"domain": "text"
},
"hris": {
"hris_name": "text",
"hris_type": "text",
"hris_url": "text",
"hris_identity_mapping": {
"mappings": [
{
"destination_datasource_type": "text",
"destination_datasource_oaa_app_type": "text",
"type": 1,
"mode": 1,
"transformations": [
1
],
"custom_value": "text",
"property_matchers": [
{
"source_property": 1,
"destination_property": 1,
"custom_source_property": "text",
"custom_destination_property": "text"
}
],
"id_matchers": [
{
"source_id": "text",
"destination_id": "text"
}
],
"destination_datasources": [
{
"type": "text",
"oaa_app_type": "text"
}
],
"property_match_operator": 1
}
],
"use_email": true
},
"hris_provisioning_source": true
},
"cmdb": {
"cmdb_instance_name": "text",
"cmdb_instance_type": "text",
"csc_global_config": {
"owner_id_column_name": "text",
"asset_id_column_name": "text",
"asset_type_column_name": "text",
"owner_node_type": "text",
"owner_id_property": "text",
"asset_connections": [
{
"asset_type_value": "text",
"asset_node_type": "text",
"asset_property_name": "text"
}
]
}
},
"secret_store": {
"secret_store_name": "text",
"secret_store_type": "text",
"vault_type": "text"
}
},
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
],
"external_lifecycle_management_type": 1,
"cmdb_types": [
"text"
],
"notification_preferences": {
"enabled": true,
"subscribed_events": [
1
],
"notify_integration_owner": true,
"additional_recipients": [
"text"
],
"delivery_methods": [
{
"type": 1,
"id": "text"
}
]
}
}
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
DELETE /api/v1/providers/custom/{id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Veza API key for authentication. Generate keys in Administration > API Keys.
The maximum number of results to be returned. Fewer results may be returned even when more pages exist.
The token specifying the specific page of results to retrieve.
OK
Status is the status of current ingestion. See PreviousStatus for the status of the previous ingestion.
PreviousStatus is a SUCCESS, ERROR or one of the specific error statuses unless the initial ingestion is in progress in which case it is one of EXTRACTION_PENDING, EXTRACTION_IN_PROGRESS, PARSE_PENDING or PARSE_IN_PROGRESS.
The type of the serialized message.
SyncedAt timestamp is deprecated in favor of SyncStart, SyncEnd, SyncStartSuccess, SyncEndSuccess
ParsedAt records ingestion time of the latest ingestion attempt.
ParsedAtSuccess records ingestion time of the latest successful ingestion. See SyncStartSuccess and SyncEndSuccess for data extraction timestamps.
PushedAt is set when a custom datasource payload is pushed.
SyncStart records extraction start time of the latest extraction attempt.
SyncEnd records extraction end time of the latest extraction attempt.
SyncStartSuccess records extraction start time of the latest successful ingestion.
SyncEndSuccess records extraction end time of the latest successful ingestion.
RBAC ID for the provider as it controls access control for the datasource.
ParseStart records parse start time of the latest parse attempt.
ParseStartSuccess records parse start time of the latest successful parse.
ParseStartNonMetadata records parse start time of the latest non-metadata parse attempt.
ParseStartSuccessNonMetadata records parse start time of the latest successful non-metadata parse.
ParseEndNonMetadata records parse end time of the latest non-metadata parse attempt.
Retries is the number of parse retries for the current ingestion.
SkippedParses is the number of skipped parses for the current ingestion.
ParseEnd records parse end time of the latest parse attempt.
ParseEndSuccess records parse end time of the latest successful parse.
ParseEndSuccessNonMetadata records parse end time of the latest successful non-metadata parse.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
The pagination token to retrieve the next page of results.
If true, more results are available.
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom/{id}/datasources HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"values": [
{
"id": "text",
"name": "text",
"datasource_type": 1,
"agent_type": 1,
"status": 1,
"previous_status": 1,
"provider_id": "text",
"path": "text",
"external_id": "text",
"state": 1,
"effective_state": 1,
"datasource_config": {
"@type": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "text",
"updated_at": "text",
"pushed_at": "2026-01-01T00:00:00.000Z",
"sync_start": "2026-01-01T00:00:00.000Z",
"sync_end": "2026-01-01T00:00:00.000Z",
"sync_start_success": "2026-01-01T00:00:00.000Z",
"sync_end_success": "2026-01-01T00:00:00.000Z",
"error": {
"reason": 1,
"message": "text",
"resolution": "text",
"original_message": "text",
"step": 1
},
"agent_category": 1,
"provider_type": 1,
"rbac_id": "text",
"parse_start": "text",
"parse_start_success": "2026-01-01T00:00:00.000Z",
"parse_start_non_metadata": "2026-01-01T00:00:00.000Z",
"parse_start_success_non_metadata": "2026-01-01T00:00:00.000Z",
"parse_end_non_metadata": "2026-01-01T00:00:00.000Z",
"retries": 1,
"skipped_parses": 1,
"parse_end": "text",
"parse_end_success": "2026-01-01T00:00:00.000Z",
"parse_end_success_non_metadata": "2026-01-01T00:00:00.000Z",
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
]
}
],
"next_page_token": "text",
"has_more": true
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}/datasources HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52
{
"id": "text",
"name": "text",
"custom_template": "text"
}{
"value": {
"id": "text",
"name": "text"
}
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Status is the status of current ingestion. See PreviousStatus for the status of the previous ingestion.
PreviousStatus is a SUCCESS, ERROR or one of the specific error statuses unless the initial ingestion is in progress in which case it is one of EXTRACTION_PENDING, EXTRACTION_IN_PROGRESS, PARSE_PENDING or PARSE_IN_PROGRESS.
The type of the serialized message.
SyncedAt timestamp is deprecated in favor of SyncStart, SyncEnd, SyncStartSuccess, SyncEndSuccess
ParsedAt records ingestion time of the latest ingestion attempt.
ParsedAtSuccess records ingestion time of the latest successful ingestion. See SyncStartSuccess and SyncEndSuccess for data extraction timestamps.
PushedAt is set when a custom datasource payload is pushed.
SyncStart records extraction start time of the latest extraction attempt.
SyncEnd records extraction end time of the latest extraction attempt.
SyncStartSuccess records extraction start time of the latest successful ingestion.
SyncEndSuccess records extraction end time of the latest successful ingestion.
RBAC ID for the provider as it controls access control for the datasource.
ParseStart records parse start time of the latest parse attempt.
ParseStartSuccess records parse start time of the latest successful parse.
ParseStartNonMetadata records parse start time of the latest non-metadata parse attempt.
ParseStartSuccessNonMetadata records parse start time of the latest successful non-metadata parse.
ParseEndNonMetadata records parse end time of the latest non-metadata parse attempt.
Retries is the number of parse retries for the current ingestion.
SkippedParses is the number of skipped parses for the current ingestion.
ParseEnd records parse end time of the latest parse attempt.
ParseEndSuccess records parse end time of the latest successful parse.
ParseEndSuccessNonMetadata records parse end time of the latest successful non-metadata parse.
Must be unique within an insight point
Provider type: "azure_key_vault", "aws_secrets_manager", etc.
Owning insight point ID, or "internal" for control plane vaults
Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom/{id}/datasources/{data_source_id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"value": {
"id": "text",
"name": "text",
"datasource_type": 1,
"agent_type": 1,
"status": 1,
"previous_status": 1,
"provider_id": "text",
"path": "text",
"external_id": "text",
"state": 1,
"effective_state": 1,
"datasource_config": {
"@type": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "text",
"updated_at": "text",
"pushed_at": "2026-01-01T00:00:00.000Z",
"sync_start": "2026-01-01T00:00:00.000Z",
"sync_end": "2026-01-01T00:00:00.000Z",
"sync_start_success": "2026-01-01T00:00:00.000Z",
"sync_end_success": "2026-01-01T00:00:00.000Z",
"error": {
"reason": 1,
"message": "text",
"resolution": "text",
"original_message": "text",
"step": 1
},
"agent_category": 1,
"provider_type": 1,
"rbac_id": "text",
"parse_start": "text",
"parse_start_success": "2026-01-01T00:00:00.000Z",
"parse_start_non_metadata": "2026-01-01T00:00:00.000Z",
"parse_start_success_non_metadata": "2026-01-01T00:00:00.000Z",
"parse_end_non_metadata": "2026-01-01T00:00:00.000Z",
"retries": 1,
"skipped_parses": 1,
"parse_end": "text",
"parse_end_success": "2026-01-01T00:00:00.000Z",
"parse_end_success_non_metadata": "2026-01-01T00:00:00.000Z",
"secret_references": [
{
"id": "text",
"secret_id": "text",
"secret_mapping": {
"type": 1,
"mapping": "text"
},
"vault_id": "text",
"vault": {
"id": "text",
"name": "text",
"vault_provider": "text",
"insight_point_id": "text",
"deleted": true
}
}
]
}
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
DELETE /api/v1/providers/custom/{id}/datasources/{data_source_id} HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"id": "text",
"data_source_id": "text",
"json_data": "text",
"compression_type": 1,
"priority_push": true
}{
"warnings": [
{
"message": "text"
}
]
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 125
{
"id": "text",
"data_source_id": "text",
"csv_data": "text",
"name": "text",
"type": "text",
"compression_type": 1,
"priority_push": true
}{
"warnings": [
{
"message": "text"
}
]
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"id": "text",
"data_source_id": "text",
"json_data": "text",
"compression_type": 1,
"priority_push": true
}{
"warnings": [
{
"message": "text"
}
]
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 125
{
"id": "text",
"data_source_id": "text",
"csv_data": "text",
"name": "text",
"type": "text",
"compression_type": 1,
"priority_push": true
}{
"warnings": [
{
"message": "text"
}
]
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
POST /api/v1/providers/custom/{id}:icon HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34
{
"id": "text",
"icon_base64": "text"
}{}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom/{id}:icon HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"mime_type": "text",
"icon_base64": "text"
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
GET /api/v1/providers/custom:icon HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"mime_type": "text",
"icon_base64": "text",
"provider_id": "text"
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
DELETE /api/v1/providers/custom/{id}:icon HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}The most common OAA use case is modeling local identities, data sources, and permissions within an application containing sensitive information such as a database, ticket desk, or SCM platform. This sample app uses the CustomApplication class to create an OAA payload for a typical application that includes users, groups, roles and resources.
Customers that implement a custom Identity Provider (or one that doesn't have a native Veza integration) can use the OAA Custom IdP template to describe federated users and groups. This sample app generates a custom payload containing users, groups, and identity metadata, using the CustomIdPProvider class.
The example also demonstrates OAA support for AWS role entitlements, for scenarios where users can assume AWS roles in ways that can't be discovered by Veza's native AWS integration.
Sample app for importing Custom Identity Provider users from a CSV file.
This example can be used as a simple starting point for an OAA data source importer. Demonstrates use of CustomIdPProvider to create IdP users and assign properties using an input file with with the column headings:
identity,name,full_name,is_active,is_guest,manager_id
export OAA_TOKEN="xxxxxxx"
export VEZA_URL="https://myveza.vezacloud.com"
./sample-app.pyOAA 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:
Trigger Lifecycle Management events when there is a change in the integrated HRIS data source.
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.
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.
Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or employee_number 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
employee_number
If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the employee_number is used. Veza issues a warning if no matching entity is found.
Veza compares only that one resolved value, and the comparison ignores case but is otherwise exact. An employee_number therefore correlates only when the IdP login, principal name, or email address is itself that number: Veza does not compare it to an Employee ID attribute on the IdP user. For the attributes Veza compares for each provider, see . To correlate on an attribute outside that set, add an identity_mapping_configuration to the HRIS system, or configure a mapping on the identity provider integration. See .
The account/tenant/etc. that contains the HR information.
Used to represent any person who has been employed by a company.
Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.
Choosing your development environment and deploying an OAA connector
The Open Authorization API enables developers to push metadata to the Veza Access Graph using a standard JSON schema. To automate this process, you will need a way to periodically query the data source you want to integrate, populate the schema, and publish the populated template payload to your Veza instance using API calls.
You can interact with the Veza API from your client or language of choice. OAA connectors can (and have) been developed in a variety of languages. The only requirements are the ability to:
query the source application (or , or another method) to collect identity, resource, and authorization metadata
assemble a dict or similar data structure and convert to JSON
make REST API calls to publish the payload
Veza provides a Python SDK oaaclient. This package provides functions for generating and submitting the JSON payload. The Veza developed community connectors use this toolkit, along with all integrations built by active customer developers.
You can run OAAClient as a manual CLI tool for trial purposes, but should automate any long-running OAA implementation. A DevOps or SecOps team is typically responsible for establishing continuous integration of a Veza connector.
Customers are responsible for running their own connectors. The frequency your app must run will depend on use case, ranging from daily to hourly. Veza typically refreshes metadata for built-in integrations on an hourly basis. However, you can decide to publish OAA payloads on any schedule.
At a minimum, a deployed OAA connector should be able to:
Parse the data source and push an updated payload on a schedule
Securely handle secrets such as API keys
Teams should follow their preferred processes and use familiar or existing platforms. Some options include:
AWS Lambda function
Docker/k8s-based container
cron task
GitHub action
Veza expects the default push to contain a full payload. This will overwrite all information in the updated data source.
During development, it is usually most efficient to design your parser for a full discovery. It will be easiest to design the connector to assemble and push the full payload, and use the same code to publish updates.
OAA does support incremental update as an optional behavior–if your custom data source or identity provider provides a way to get individual changes over time, you could design your connector to parse only new or changed entities, and push updates individually (perhaps in response to detected changes). However, this approach will be more complicated. A full parse-and-push will be more efficient, unless there's a method to query the provider for differences since the last push.
To use incremental updates:
Set the is_incremental flag in the payload to true
Add an add, modify or delete operation to all entities
idp_providers
String list
N
N
List of destination IdP provider types to connect this system to (e.g. okta, azure_ad).
Identity Mapping Configuration
identity_mapping_configuration
Object
N
N
Configuration for mapping employees to identities in external data sources.
Company
company
String
N
N
The company (or subsidiary) the employee works for.
First Name
first_name
String
N
N
The employee's first name.
Last Name
last_name
String
N
N
The employee's last name.
Preferred Name
preferred_name
String
N
N
The employee's preferred first name.
Display Full 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
canonical_name
String
N
N
The employee's canonical name.
Username
username
String
N
N
The employee's username that appears in the integration UI.
email
String
N
Y
The employee's work email.
IDP ID
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
personal_email
String
N
N
The employee's personal email.
Home Location
home_location
String
N
N
The employee's home location.
Work Location
work_location
String
N
N
The employee's work location.
Cost Center
cost_center
EntityRef
N
N
Reference to the group representing the cost center the employee is in (e.g. {"id": "cost-center-001"}).
Department
department
EntityRef
N
N
Reference to the group representing the department the employee is in (e.g. {"id": "engineering"}).
Managers
managers
EntityRef list
N
N
References to the employee's managers (e.g. [{"id": "987654"}]).
Groups
groups
EntityRef list
N
N
References to the groups this employee is in (e.g. [{"id": "all_employees"}]).
Employment Status
employment_status
String
N
N
The employment status of the employee. Possible values include - ACTIVE, PENDING, INACTIVE.
Is Active
is_active
Boolean
N
N
If the employee is active or not.
Start Date
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
termination_date
Timestamp
N
N
The employee's termination date.
Job Title
job_title
String
N
N
The title of the employee.
Employment Types
employment_types
String list
N
N
The employee's type of employment. Possible values include - FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.
Primary Time Zone
primary_time_zone
String
N
N
The time zone which the employee primarily lives.
parent
EntityRef
N
N
Reference to the parent group (e.g. {"id": "parent-group-id"}).
URL
url
String
N
N
The url for this HRIS system.
Employee Number
employee_number
String
N
Y
Group Type
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.
IDP Providers
The employee's number that appears in the third-party integration.
Parent
{
"name": "HRIS Example",
"hris_type": "HR Platform",
"custom_property_definition": {
"system_properties": {},
"employee_properties": {
"job_level": "STRING"
},
"group_properties": {}
},
"system": {
"id": "7D8A21AE-6650-4357-842B-3FCEC8F29195",
"name": "HRIS Example",
"url": "https://hris.example.com",
},
"employees": [
{
"id": "123456",
"name": "jdoe",
"employee_number": "E123456",
"first_name": "John",
"last_name": "Doe",
"canonical_name": "Doe, John",
"email": "jdoe@example.com",
"home_location": "Anytown, CA",
"work_location": "San Francisco, CA",
"employment_status": "HIRED",
"start_date": "2022-05-22T00:00:00Z",
"job_title": "Software Developer",
"employment_types": [
"FULL_TIME"
],
"custom_properties": {
"job_level": "L3"
},
"is_active": true,
"groups": [
{
"id": "all_employees"
}
],
"managers": [
{
"id": "987654"
}
],
"department": {
"id": "engineering"
}
},
{
"id": "987654",
"name": "jane.doe",
"employee_number": "E987654",
"first_name": "Jane",
"last_name": "Doe",
"canonical_name": "Doe, Jane",
"email": "jane.doe@example.com",
"home_location": "Anytown, CA",
"work_location": "San Francisco, CA",
"employment_status": "HIRED",
"start_date": "2021-03-13T00:00:00Z",
"job_title": "Software Developer",
"employment_types": [
"FULL_TIME"
],
"custom_properties": {
"job_level": "M2"
},
"is_active": true,
"groups": [
{
"id": "all_employees"
}
],
"department": {
"id": "engineering"
}
}
],
"groups": [
{
"id": "all_employees",
"name": "All Employees",
"group_type": "Employee Group"
},
{
"id": "engineering",
"name": "Engineering",
"group_type": "Department"
}
]
}{
"name": "BambooHR",
"hris_type": "BambooHR",
"custom_property_definition": {
"employee_properties": {
"division": "STRING",
"office_extension": "STRING"
},
"group_properties": {
"headquarters_location": "STRING"
}
},
"system": {
"name": "BambooHR",
"id": "BambooHR",
"url": "https://vezai.bamboohr.com",
"idp_providers": ["okta"]
},
"employees": [
{
"name": "Charlotte Abbott",
"id": "1",
"custom_properties": {
"division": "North America",
"office_extension": "1234"
},
"employee_number": "1",
"email": "cabbott@efficientoffice.com",
"work_location": "Lindon, Utah",
"job_title": "Sr. HR Administrator"
},
{
"name": "Cheryl Barnet",
"id": "10",
"custom_properties": {
"division": "North America",
"office_extension": "5678"
},
"employee_number": "10",
"email": "cbarnet@efficientoffice.com",
"work_location": "Lindon, Utah",
"job_title": "VP of Customer Success"
}
],
"groups": [
{
"name": "North America-Human Resources",
"id": "North America-Human Resources",
"group_type": "Department",
"custom_properties": {
"headquarters_location": "Lindon, Utah"
}
}
]
}#!env python3
"""Example of using `oaaclient` to import users from a CSV file.
Reads user properties from the input file, populates an OAA payload,
and creates a new OAA identity provider containing the imported users.
Expected CSV headers are `identity,name,full_name,is_active,is_guest,manager_id`
Can be updated to match custom column headings or apply custom properties.
Example:
```
export VEZA_URL=<Veza URL>
export VEZA_API_KEY=<Veza API key>
./idp-importer-csv.py --provider MyIdpProvider --datasource MyDatasource ./my-users.csv
```
Copyright 2022 Veza Technologies Inc.
Use of this source code is governed by the MIT
license that can be found in the LICENSE file or at
https://opensource.org/licenses/MIT.
"""
from oaaclient.client import OAAClient, OAAClientError
from oaaclient.templates import CustomIdPProvider
import click
import csv
import logging
import os
import sys
logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
log = logging.getLogger()
def load_users(idp: CustomIdPProvider, source: str) -> None:
"""Populate the idp with user from the source csv file"""
log.info(f"Loading users from {source}")
with open(source) as f:
for r in csv.DictReader(f):
# get the identity, name, full_name and email
try:
identity = r["identity"]
name = r["name"]
full_name = r["full_name"]
email = r["email"]
except KeyError as e:
log.error(f"Incorrect CSV column headers, missing column {e}")
sys.exit(1)
# create a new IDP user
new_user = idp.add_user(name=name, full_name=full_name, email=email, identity=identity)
# set the user to active and guest or not, look for strings like true/false or yes/no
if r.get("active"):
active_string = r["active"].lower()
if active_string in ["true", "yes"]:
new_user.is_active = True
elif active_string in ["false", "no"]:
new_user.is_active = False
if r.get("is_guest"):
guest_string = r["is_guest"].lower()
if guest_string in ["true", "yes"]:
new_user.is_guest = True
elif guest_string in ["false", "no"]:
new_user.is_guest = False
# if the manager id column is filled in, set the new users manager
if r.get("manager_id"):
new_user.manager_id = r.get("manager_id")
return
@click.command()
@click.option("--provider", required=True)
@click.option("--datasource", required=True)
@click.option("--save-json", is_flag=True)
@click.argument("file", required=True)
def main(provider, datasource, save_json, file):
# load the Veza URL and API key from the environment
veza_url = os.getenv("VEZA_URL")
veza_api_key = os.getenv("VEZA_API_KEY")
if not (veza_url or veza_api_key):
log.error("Must set VEZA_URL and VEZA_API_KEY")
sys.exit(1)
try:
log.info("Testing Veza credentials")
veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
except OAAClientError as e:
log.error("Unable to connect to Veza API")
log.error(e)
sys.exit(1)
# create a new provider if the provider doesn't already exist
if not veza_con.get_provider(provider):
log.info(f"Creating new provider {provider}")
veza_con.create_provider(provider, "identity_provider")
# Configure the Custom IdP
idp = CustomIdPProvider("Custom IdP", idp_type="custom_idp", domain="example.com", description=None)
# load the user from
load_users(idp, file)
try:
# push the IdP to Veza, log and errors or warnings
log.info("Sending to Veza")
response = veza_con.push_application(provider, datasource, idp, save_json=save_json)
if response.get("warnings", None):
log.warning("Push succeeded with warnings")
for w in response['warnings']:
log.warning(w)
log.info("Success")
except OAAClientError as e:
log.error(f"Error during push {e.message} {e.status_code}")
if e.details:
log.error(e.details)
sys.exit(1)
return
if __name__ == "__main__":
main()
#!env python3
"""
Copyright 2022 Veza Technologies Inc.
Use of this source code is governed by the MIT
license that can be found in the LICENSE file or at
https://opensource.org/licenses/MIT.
Example of using the `CustomApplication` class to model a typical application where users and groups are assigned
permissions to the application or resources.
If you want to run the code you will need to export environment variables for the Veza URL, user and API keys.
```
export OAA_TOKEN="xxxxxxx"
export VEZA_URL="https://myveza.vezacloud.com"
./sample-app.py
```
"""
from oaaclient.client import OAAClient, OAAClientError
from oaaclient.templates import CustomApplication, OAAPermission
import os
import sys
def main():
# OAA requires an API token, which you can generate from your Veza user profile
# Export the API token, and Veza URL as environment variables
# Making them available to your connector in this way keeps credentials out of the source code
veza_api_key = os.getenv('VEZA_API_KEY')
veza_url = os.getenv('VEZA_URL')
if None in (veza_url, veza_api_key):
print("Unable to local all environment variables")
sys.exit(1)
# Instantiates a client connection. The client will confirm the credentials and Veza URL are valid
# Checking this early helps prevents connection failures in the final stage
veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
# Create an instance of the OAA CustomApplication class, modeling the application name and type
# `name` will be displayed in the Veza UI
# `application_type` should be a short key reflecting the source application authorization is being modeled for
# You can use the same type for multiple applications
custom_app = CustomApplication(name="Sample App", application_type="sample")
# In the OAA payload, each permission native to the custom app is mapped to the Veza effective permission (data/nondata C/R/U/D).
# Permissions must be defined before they can be referenced, as they are discovered or ahead of time.
# For each custom application permission, bind them to the Veza permissions using the `OAAPermission` enum:
custom_app.add_custom_permission("admin", [OAAPermission.DataRead, OAAPermission.DataWrite])
custom_app.add_custom_permission("operator", [OAAPermission.DataRead])
# Create resources and sub-resource to model the entities in the application
# To Veza, an application can be a single entity or can contain resources and sub-resources
# Utilizing resources enables tracking of authorizations to specific components of the system being modeled
# Setting a `resource_type` can help group entities of the same type for reporting/queries
entity1 = custom_app.add_resource(name="Entity1", resource_type="thing",
entity2 = custom_app.add_resource(name="Entity2", resource_type="thing",
other = custom_app.add_resource(name="Other", resource_type="other",
# Sub-resources can be added to any resource (including other sub-resources)
child1 = entity1.add_sub_resource(name="Child 1", resource_type="child",
child1.add_sub_resource(name="Grandchild 1", resource_type="grandchild", description=
# Any users and groups local to the application can be defined.
# IdP users can be mapped directly without defining them in the OAA application (see below)
custom_app.add_local_user("bob")
# A local user can be associated with an IdP user by adding an identity to the user:
custom_app.local_users["bob"].add_identity("bob@example.com")
# Identities, groups and roles can be assigned to local users at creation or after (groups and roles must exist):
jane = custom_app.add_local_user("jane", identities="jane@example.com")
# when adding a user the new user is returned and can updated if needed, there are multiple built in properties that can be set for a user
jane.is_active = False
jane.created_at = "2022-01-26T20:48:12.460Z"
# Define a local group and add a user to it
custom_app.add_local_group("admins")
custom_app.local_users["jane"].add_group("admins")
# adding local users and groups requires that the name not already exist
if "yan" not in custom_app.local_users:
custom_app.add_local_user("yan")
# For each Identity (user, group, IdP) assign permissions to the application or resource.
# The identities (users, groups) permissions and resources must already be defined
# To add a permission directly to the application use `apply_to_application=True`
custom_app.local_users["bob"].add_permission(permission="operator", apply_to_application=True
custom_app.local_groups["admins"].add_permission(permission="admin", apply_to_application=True
# You can describe specific permissions to individual resources or sub-resources:
custom_app.local_users["yan"].add_permission(permission="operator", resources=[
# Authorization can also be created directly for an IdP identity
custom_app.add_idp_identity("user_identity@example.com")
# resources can also be referenced by name from the application model
custom_app.idp_identities["user_identity@example.com"].add_permission(permission="admin", resources=[
# Once all authorizations have been mapped, the final step is to publish the app to Veza
# Connect to the API to Push to Veza, define the provider and create if necessary:
provider_name = "Sample"
provider = veza_con.get_provider(provider_name)
if provider:
print("-- Found existing provider")
else:
print(f"++ Creating Provider {provider_name}")
provider = veza_con.create_provider(provider_name, "application")
print(f"-- Provider: {provider['name']} ({provider['id'
# Push the metadata payload:
try:
response = veza_con.push_application(provider_name,
data_source_name=f"{custom_app.name} ({custom_app.application_type})",
application_object=custom_app,
save_json=False
)
if response.get("warnings", None):
# Veza may return warnings on a successful uploads. These are informational warnings that did not stop the processing
# of the OAA data but may be important. Specifically identities that cannot be resolved will be returned here.
print("-- Push succeeded with warnings:")
for e in response["warnings"]:
print(f" - {e}")
except OAAClientError as e:
print(f"-- Error: {e.error}: {e.message} ({e.
if hasattr(e, "details"):
for d in e.details:
print(f" -- {d}", file=sys.stderr)
return
if __name__ == '__main__':
main()
#!env python3
"""
Copyright 2022 Veza Technologies Inc.
Use of this source code is governed by the MIT
license that can be found in the LICENSE file or at
https://opensource.org/licenses/MIT.
Example of using the `CustomIdPProvider` class to model an identity provider as a source of users.
If you want to run the code you will need to export environment variables for the Veza URL, user and API keys.
```
export VEZA_API_KEY="xxxxxxx"
export VEZA_URL="https://myveza.vezacloud.com"
./sample-idp.py
```
Since the example includes fake AWS ARNs that Veza will not have discovered the expected output will
contain warning like "Cannot find IAM role by names ..."
"""
from oaaclient.client import OAAClient, OAAClientError
from oaaclient.templates import CustomIdPProvider, OAAPropertyType
import os
import sys
def main():
# OAA requires a Veza API key, which you can generate from Administration > API Keys
# Export the API key, and Veza URL as environment variables
# Making them available to your connector in this way keeps credentials out of the source code
veza_api_key = os.getenv("VEZA_API_KEY")
veza_url = os.getenv("VEZA_URL")
if not veza_api_key or not veza_url:
print("Unable to load VEZA_API_KEY and VEZA_URL from OS")
sys.exit(1)
# Instantiates a client connection. The client will confirm the credentials and Veza URL are valid
# Checking this early helps prevents connection failures in the final stage
veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
# create a CustomIdPProvider to represent your IdP. This can be named generically or specific to the environment if you have
# multiple namespaces to model. idp_type will typically be the technology/vendor for the provider.
idp = CustomIdPProvider("My IdP", domain="example.com", idp_type="
# add users to the idp, properties for users can be set during creation or updated after
idp.add_user("mrichardson", full_name="Michelle Richardson", email="mrichardson@example.com
evargas_user = idp.add_user("evargas")
evargas_user.full_name = "Elizabeth Vargas"
evargas_user.email = "evargas@example.com"
# users and groups can have optional identity property. The identity serves as the unique reference identifier across
# Veza. If omitted CustomIdPProvider will automatically populate the identity with the name
idp.add_user("willis", email="willis@example.com", identity="cwilliams
# OAA can support custom properties for users to track additional metadata unique to the environment
# to use custom properties the property must first be defined and given a type, then can be set for the individual entity
idp.property_definitions.define_user_property("region", OAAPropertyType.STRING)
idp.property_definitions.define_user_property("is_contractor", OAAPropertyType.BOOLEAN)
idp.users['willis'].set_property("region", "NorthAmerica")
idp.users['willis'].set_property("is_contractor", True)
# Create Groups
idp.add_group("developers")
idp.add_group("sec-ops")
idp.add_group("everyone", full_name="All Company Employees")
# users can be added to groups using the add_group function, users can be added to multiple groups in a single call
for username in idp.users:
idp.users[username].add_groups(["everyone"])
evargas_user.add_groups(["developers", "sec-ops"])
idp.users["mrichardson"].add_groups(["developers"])
# Veza CustomIdP supports tracking the AWS Roles a user can assume. For users who can assume roles Veza can calculate
# their effective permissions to AWS resources based on the role(s)
# roles are added by ARN
idp.users["mrichardson"].add_assumed_role_arns(["arn:aws:iam::123456789012:role/role001", "arn:aws:iam::123456789012:role/role002"])
# After adding users and groups, the IdP information is pushed to Veza using the OAA API
provider_name = "Sample-IdP"
provider = veza_con.get_provider(provider_name)
if provider:
print("-- Found existing provider")
else:
print(f"++ Creating Provider {provider_name}")
provider = veza_con.create_provider(provider_name, "identity_provider")
print(f"-- Provider: {provider['name']} ({provider['id'
# Push the metadata payload:
try:
response = veza_con.push_application(provider_name,
data_source_name=f"{idp.name} ({idp.idp_type})",
application_object=idp,
save_json=True
)
if response.get("warnings", None):
# Veza may return warnings on a successful uploads. These are informational warnings that did not stop the processing
# of the OAA data but may be important, for example: AWS role ARNs assigned to users that Veza has not discovered
print("-- Push succeeded with warnings:")
for e in response["warnings"]:
print(f" - {e}")
except OAAClientError as e:
print(f"-- Error: {e.error}: {e.message} ({e.
if hasattr(e, "details"):
for d in e.details:
print(f" -- {d}", file=sys.stderr)
if __name__ == '__main__':
main()
Building blocks for your custom OAA integration
The oaaclient package provides data models, methods and a command-line interface for using the Open Authorization API. You can use it to populate OAA templates including Application, IdP, HRIS, Host, Principal, Secret Store, and Entity Enrichment, pushing OAA data to Veza and even as a general Veza API client.
The oaaclient SDK includes the following components:
oaaclient.client: Veza API communication (data provider management, payload push, etc.). Requires an API key for authentication.
oaaclient.templates: Classes for modeling and generating an OAA payload.
oaaclient.utils: Additional utility functions (icon encoding, etc.).
For example usage, please see and the directory.
Sample Workflow
Create the Veza API connection and a new custom application:
Once the CustomApplication class is instantiated, you can use the public methods to populate the new app with local users, groups, resources, and permissions metadata:
Once all identities, permissions and resources are added to the CustomApplication object, the client connection handles the final push to Veza:
See the directory for complete examples.
The OAAClient class handles API connections to Veza. If there are errors connecting or the API returns errors OAAClient will raise an OAAClientError exception. If the payload doesn't conform to the template requirements the OAAClientError.details will contain a list of any issues encountered.
Since any given source application or service will have different methods for retrieving entities, authorization, and other required metadata, each OAA connector will be slightly different. You should consult the API documentation for your application when considering how you will source the information, and refer to existing Veza-supported OAA connectors for real-world examples.
Connector source code and oaaclient are thoroughly annotated, for reference when building your own integrations.
For additional information about developing a custom OAA integration, please see section of the User Guide.
from oaaclient.client import OAAClient
from oaaclient.templates import CustomApplication, OAAPermission
# creates a connection class to communicate with Veza
veza_con = OAAClient(url=veza_url, token=veza_api_key)
# creates a new Custom Application model
custom_app = CustomApplication(name="Sample App", application_type="sample")# define a permission
custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
# create a local user
jsmith = custom_app.add_local_user(unique_id="jsmith", name="Jane Smith", identities=["jane@example.com"])
# create a resource
resource1 = custom_app.add_resource(name="Resource 1", resource_type="Thing")
# assign a user to a resource
jsmith.add_permission(permission="owner", resources=[resource1])veza_con.push_application(provider, data_source_name, application_object=custom_app) try:
response = veza_con.push_application(provider_name=provider_name,
data_source_name=data_source_name,
application_object=custom_app,
)
if response.get("warnings"):
print("Push succeeded with warnings:")
for w in response["warnings"]:
print(w)
except OAAClientError as e:
print(f"Error: {e.error}: {e.message} ({e.status_code})", file=sys.stderr)
if hasattr(e, "details"):
for d in e.details:
print(d, file=sys.stderr)Template for modeling a lightweight identity source with users, groups, and tenants
Use this template to model a source of identities (users, groups, and tenants) using the Open Authorization API. Principals represent identity sources that connect to other OAA template types on the same provider, enabling Veza to map users and groups to the applications and resources they access.
The Custom Principal template differs from the Custom Identity Provider in scope: a Principal is a lightweight identity source meant to feed users and groups into Custom Application or other templates on the same provider. Custom IdP models a full identity provider with domains and federated identity features.
The template has three primary entities:
Tenant - the top-level container for the principal instance. Each submission has exactly one tenant.
Users - the individual identities in the principal system. Users can belong to groups and have custom properties like is_active, email, and timestamps.
Groups - collections of users. Groups support hierarchical nesting through parent group references.
A can define additional properties for tenants, users, and groups.
To use the principal template, set custom_templates to a list that includes principal when creating the provider. Because a principal is almost always used alongside an application, include both templates:
Then create a data source for the principal on that provider, specifying the principal template:
Veza's Atlassian Cloud connector uses the Custom Principal template to model the organization-level identity directory in Atlassian Cloud. The principal feeds users and groups into the Jira Cloud and Confluence Cloud application connectors on the same provider, linking identities to the resources they access.
This approach separates identity management (who exists, what products they can access) from application-level authorization (what permissions they have in Jira projects or Confluence spaces). The principal captures the organization directory, while separate Custom Application submissions model Jira and Confluence.
Key patterns from this integration:
user_type distinguishes managed users (in the organization's domain) from external collaborators, enabling access reviews to flag external access.
product_access as a STRING_LIST tracks which Atlassian products each user can access (Jira, Confluence, Bitbucket), providing visibility into license usage.
access_billable flags whether the user counts toward the organization's Atlassian license seat count.
Each principal submission contains exactly one tenant, representing the top-level container for the identity source.
Users represent individual identities in the principal system. Each user can be linked to external identities and assigned to groups.
Groups represent collections of users. Groups can have external identities and support hierarchical nesting through parent group references.
Custom properties allow you to attach additional metadata to principal entities. Define properties in the custom_property_definition object, then set values on individual entities.
Property values must match their declared type. Supported types are described in .
After the initial metadata push (which must contain the full payload), you can modify, add, or remove the tenant, users, and groups without resubmitting other entities. An is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.
To create the OAA provider and push data:
Create the provider with both the principal and application template types:
Create a data source on the provider, specifying the principal template:
Push the payload to the data source:
The push endpoint requires the payload as a JSON-encoded string in the json_data
Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.
Groups map to product access rather than organizational structure — groups like jira-software-users and confluence-users reflect Atlassian's product-based access model.
The principal connects to application templates on the same provider. Users and groups defined here appear as identities in Jira Cloud and Confluence Cloud Custom Application submissions, linking organization membership to application-level permissions.
object
The object for this principal
users
array
Array of objects
groups
array
Array of objects
incremental_change
boolean
When true, enables (optional)
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
user_unique_id
string
Optional unique identifier. Defaults to email if set, otherwise id
display_name
string
Display name shown in Veza (optional)
is_active
boolean
Whether the user account is active
created_date
string
Date the user was created, in RFC 3339 format (e.g., 2024-01-15T09:00:00.000Z)
deactivated_date
string
Date the user was deactivated, in RFC 3339 format (optional)
last_login
string
Date of the user's last login, in RFC 3339 format (optional)
identities
array
List of identity strings (e.g., email addresses) used for linking to external identity providers
groups
array
List of group references as {"id": "group_id"} objects
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
string
Type descriptor for the group (e.g., Security, Department, Team)
parent_group
object
Reference to a parent group as {"id": "parent_group_id"} for hierarchical nesting (optional)
identities
array
List of identity strings for linking to external identity providers
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
enum
For , the operation to apply (optional)
jq -Rs .payload.jsoncurl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Principal Data Source","custom_template":"principal"}'name
string
Name of the principal provider instance
principal_type
string
Type descriptor for the principal provider (e.g., corporate_directory). Applied as a searchable property
custom_property_definition
object
Defines custom properties for tenants, users, and groups. See Custom Properties
"tenant": {
"name": "Example Corp",
"id": "tenant-001",
"tenant_unique_id": "tenant-001",
"tags": [],
"custom_properties": {}
}name
string
Display name for the tenant
id
string
Unique identifier for the tenant
tenant_unique_id
string
Optional unique identifier, typically a URL or external ID. Defaults to id if not provided
"users": [
{
"name": "Alice Johnson",
"id": "alice01",
"email": "alice@example.com",
"user_unique_id": "alice01",
"display_name": "Alice Johnson",
"is_active": true,
"created_date": "2024-01-15T09:00:00.000Z",
"last_login": "2025-02-20T14:30:00.000Z",
"identities": ["alice@example.com"],
"groups": [{"id": "grp-engineering"}],
"tags": [],
"custom_properties": {}
}
]name
string
Display name for the user
id
string
Unique identifier for the user. Defaults to name if not provided
email
string
Email address for the user (optional)
"groups": [
{
"name": "Engineering",
"id": "grp-engineering",
"group_unique_id": "grp-engineering",
"group_type": "Department",
"identities": ["engineering@example.com"],
"tags": [],
"custom_properties": {}
},
{
"name": "Platform Team",
"id": "grp-platform",
"group_type": "Team",
"parent_group": {
"id": "grp-engineering"
}
}
]name
string
Display name for the group
id
string
Unique identifier for the group. Defaults to name if not provided
group_unique_id
string
Optional unique identifier for the group. Defaults to id if not provided
"custom_property_definition": {
"tenant_properties": {
"region": "STRING"
},
"user_properties": {
"department": "STRING",
"mfa_enabled": "BOOLEAN"
},
"group_properties": {
"is_security_group": "BOOLEAN"
}
}tenant_properties
Custom properties for the tenant entity
user_properties
Custom properties for user entities
group_properties
Custom properties for group entities
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Principal Data Source","custom_template":"principal"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"tenant
tags
group_type
Classes for calling Veza APIs and managing OAA providers and data sources.
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
OAACLIENT_VERSION
PROVIDER_ICON_MAX_SIZE
report_builder_entrypointreport_builder_entrypoint() → NoneEntry point for oaaclient-report-builder command
Reads a JSON file and passes it to the oaaclient.utils.build_report method
Error raised by OAAClient.
Raised for issues connecting to the OAA API and when the API returns an error.
Args:
error (str): short string for error message
message (str): detailed error message
status_code (int, optional): status code for HTTP related errors. Defaults to None.
Error returned from API Call
Error with API Connection
Class for OAA API Connection and Management.
Utilities for OAA-related operations with Veza API calls. Manages custom providers and data sources, and can push OAA payloads from JSON or template objects.
Connection url and API key can be automatically loaded from OS environment values if set. To utilize environment variables initialize OAAClient without providing a URL or API key value and set the VEZA_URL and VEZA_API_KEY OS environment variables.
Args:
url (str, optional): URL for Veza instance.
api_key (str, optional): Veza API key.
username (str, optional): Not used (legacy). Defaults to None.
Attributes:
url (str): URL of the Veza instance to connect to
api_key (str): Veza API key
enable_compression (bool): Enable or disable compression of the OAA payload during push, defaults to enabled (True)
Raises:
OAAClientError: For errors connecting to API and if API returns errors
Add a Query to a Report
Adds a Query to an existing Report by ID
Args:
report_id (str): Report UUID to add Query to
query_id (str): Query UUID to add
Returns:
dict: API Response
Perform REST API DELETE operation.
Args:
api_path (str): API Path API path relative to Veza URL
Raises:
OAAResponseError: API returned an error
OAAConnectionError: Connection error during HTTP operation
Returns:
dict: API response from call
Perform a Veza API GET operation.
Makes the GET API call to the given path and processes the API response. Returns the value or values result returned from the API.
For API endpoints that return a list like /api/v1/providers/custom function will return a list of entities or an empty list if the API returns no results.
For API endpoints that are a specific ID such as /api/v1/providers/custom/<uuid> function will return the dictionary result of the JSON returned by the API.
Args:
api_path (str): API path relative to Veza URL (example /api/v1/providers).
Raises:
OAAResponseError: API returned an error
OAAConnectionError: Connection error during HTTP operation
Returns:
list|dict: Returns list or dict based on API destination
Perform REST API PATCH operation.
Args:
api_path (str): API Path API path relative to Veza URL
Raises:
OAAResponseError: API returned an error
OAAConnectionError: Connection error during HTTP operation
Returns:
dict: API response from call
Perform a Veza API POST operation.
Call POST on the supplied Veza instance API path, submitting a data payload.
Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.
Args:
api_path (str): API path relative to Veza URL example /api/v1/providers
data (dict): dictionary object included as JSON in body of POST operation
params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.
Raises:
OAAResponseError: API returned an error
OAAConnectionError: Connection error during HTTP operation
Returns:
dict: API response as dictionary
Perform Veza API PUT operation.
Call PUT on the supplied Veza instance API path, including the data payload.
Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.
Args:
api_path (str): API path relative to Veza URL example /api/v1/providers
data (dict): dictionary object included as JSON in body of PUT operation
params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.
Raises:
OAAResponseError: API returned an error
OAAConnectionError: Connection error during HTTP operation
Returns:
dict: API response as dictionary
Create a new Data Source for the given Provider ID.
Args:
name (str): Name for new Data Source
provider_id (str): Unique identifier for the Provider
options: (dict, optional): Additional arguments to be included with data source create call to Veza. Defaults to None.
Raises:
ValueError: Data source name contains invalid characters
Returns:
dict: dictionary of new Data Source
Deprecated Legacy function for backward-compatibility.
Create a new Provider.
Creates a new Provider with the given name. An error will be raised for naming conflicts.
Args:
name (str): new Provider name
custom_template (str): the OAA template to use for the Provider ("application" or "identity_provider")
base64_icon (str, optional): Base64 encoded string of icon to set for Provider. Defaults to "".
Raises:
ValueError: Provider name contains invalid characters
Returns:
dict: dictionary representing the created Provider
Create a new Assessment Query
For details on how to define an Assessment Query see the Veza docs.
Args:
query (dict): Query definition
Returns:
dict: API response including ID of created Query
Create a new Report
For details on how to define a new Report see the Veza docs.
Args:
report (dict): Report definition
Returns:
dict: API response including ID of created Report
Push OAA Payload
Uploads the OAA payload to the datasource :push operation
Args:
provider_id (str): Provider ID
datasource_id (str): Datasource ID
payload (str): OAA payload as string
options
Raises:
ValueError: Invalid optionas format
OAAClientError: Errors returned by Veza API
Returns:
dict: API response
Push OAA Payload in parts
Push the data source payload in parts using the :push-parts operation. Necessary for large payloads.
Function will automatically start a multipart upload, split the payload into parts to upload and return the output from the complete upload operation which is the same output as from a normal OAA data source :push operation. Returned result will include any OAA validation warnings or errors.
Args:
provider_id (str): Provider ID
datasource_id (str): Data source ID
json_data (str): OAA Payload JSON as string
Raises:
ValueError: Input errors
OAAClientError: Errors returned by the Veza API
Returns:
dict: API response of upload complete operation
Delete an existing Data Source by ID.
Removes a Data Source and all entity data.
Args:
data_source_id (str): ID of Data Source to delete
provider_id (str): ID of Data Source Provider
Returns:
dict: API response
Delete an existing provider by ID.
Deleting a provider removes all datasources and historical data. Fully deleting the provider is a background operation that will complete after API response is returned.
Args:
provider_id (str): ID of provider to delete
Returns:
dict: API response
Delete an Assessment Query by ID
Args:
id (str): UUID of Query to delete
force (bool): Force deletion of query that may be part of a report. Defaults to False
Returns:
dict: API response from delete
Delete Report by ID
Args:
id (str): UUID of Report to delete
Returns:
dict: API response
Get Provider's Data Source by name.
Find a Data Source from a specific provider based on the name of the Data Source
Args:
name (str): Data Source name
provider_id (str): Provider unique ID
Returns:
dict: Data Source as dict or None
Get Data Sources for Provider by ID.
Get the list of existing Data Sources, filtered by Provider UUID.
Args:
provider_id (str): ID of Provider
Returns:
list[dict]: List of Data Sources as dictionaries
Get Provider by name.
Args:
name (str): name of Provider
Returns:
dict: dictionary representing Provider or None
Get Provider by UUID identifier.
Args:
provider_id (str): Unique global identifier for provider
Returns:
dict: dictionary representation of Provider or None
Return list of Providers.
Returns:
list[dict]: Returns a list of existing Providers as dictionaries
Get all saved Assessment Queries
Veza can filter out queries that include inactive entity types (e.g. Okta Users on a system without Okta configured). To only retrieve queries that include active entity types set include_inactive_queries to False.
Args:
include_inactive_queries (bool): Set False to exclude inactive queries from result. Defaults to True.
Returns:
list: List of assessment Queries as dictionaries
Get Assessment Query by ID
Args:
id (str): UUID identifier for Query
Returns:
dict: Query definition
Get Report by ID
Veza can filter out queries from reports that only contain entity types that are not configured (e.g. Okta Users on a system without Okta configured). To only return queries configured on the report that match entity types configured on the system set include_inactive_queries to False
Args:
id (str): UUID of Report to get
include_inactive_queries (bool): Set True to include inactive queries. Default True.
Returns:
dict: Report definition
Get all Reports
Gets Reports created on the system. To get all reports include_inactive_reports and include_inactive_queries must be set to True.
Args:
include_inactive_reports (bool, Optional): Set to True to include reports that contain no active providers, defaults to True.
include_inactive_queries (bool, Optional): Set to True to include reports that contain only inactive queries, defaults to True.
Returns:
list[dict]: List of Reports as dictionary objects
Push an OAA Application Object (such as CustomApplication).
Extracts the OAA JSON payload from the supplied OAA class (e.g. CustomApplication, CustomIdPProvider, EntityEnrichment etc) and push to the supplied Data Source.
The Provider with provider_name must be a valid existing Provider or create_provider must be set to True. A new data source will be created automatically by default if it does not already exist.
For logging, and debugging, the optional save_json flag writes the payload to a local file (before push). Output file name is formatted with a timestamp: {data source name}-{%Y%m%d-%H%M%S}.json
Args:
provider_name (str): Name of an existing Provider.
data_source_name (str): Name for Data Source (will be created if it doesn't exist).
application_object (Class): OAA object to extract the payload from
Raises:
OAAClientError: If any API call returns an error (including errors processing the OAA payload).
Returns:
dict: API response from push, including any warnings that are returned.
Push an OAA payload dictionary to Veza.
Publishes the supplied metadata dictionary representing an OAA payload to the specified provider and data source. The function will create a new data source if it does not already exist, but requires the Provider be created ahead of time.
Args:
provider_name (str): Name of existing Provider
data_source_name (str): Name for Data Source, will be created if doesn't exist.
metadata (dict): Dictionary of OAA payload to push.
Raises:
OAAClientError: If any API call returns an error including errors processing the OAA payload.
Returns:
dict: API response to the push request (including any warnings).
Update an existing custom provider icon from base64 encoded string.
To load an icon from file, use utils.encode_icon_file to get the base64 encoding of the file first
Args:
provider_id (str): unique ID of existing provider
base64_icon (str): base64 encoded string of new icon
Raises:
ValueError: If icon size exceeds maximum allowed size
Update HRIS provider to be a system of record for Lifecycle Management (LCM).
Args:
provider_id (str): unique ID of existing provider
provisioning (bool): set to True to enable LCM, False to disable
Update an existing report
Args:
report_id (str): UUID of Report to updated
report (dict): Updated Report definition
Returns:
dict: API response
Updates the User-Agent string passed with all API calls
Generates a User-Agent with the oaaclient version, Python version and platform information.
The optional extra string will be appended if provided.
Args:
extra (str, optional): Additional information to append to User-Agent string. Defaults to "".
Super class for urllib3.util.retry
Super class to allow modifying the default max backoff time from 120 seconds to our own value
Args:
Retry (type): description
Classes for constructing an OAA JSON payload for the Host template
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
HostGranteeTypeWhether a HostGrant's principal is a user or a group.
HostIdentityTypeWhether a HostUser stands for a person or not.
HostProviderClass for modeling host machine authorization using the OAA Host template.
A Host provider supports two collection models, distinguished by shape rather than a mode flag. A central collector with visibility of the whole fleet calls add_environment() once and add_host() for every host in the fleet. An agent running on one host has no view of the fleet, so it calls add_host(environment_id=...) for its own host alone and does not call add_environment().
What distinguishes the two is where the environment comes from, not how many hosts are submitted. A submission that carries an environment of its own and also sets environment_id on a host, or that does neither, is rejected by the server as ambiguous.
Args:
host_type (str): Type descriptor for the fleet, typically the platform or vendor name
Attributes:
host_type (str): Type for the fleet
environment (HostEnvironment): The fleet's environment, set by add_environment(). None for a per-host agent submission.
hosts (dict[HostNode]): Dictionary of HostNode instances
Add the fleet's environment.
Only used by a central collector that has visibility of the whole fleet. A per-host agent submission names its environment with add_host(environment_id=...) instead and must not call this method.
Args:
unique_id (str): Unique ID for the environment. Required.
name (str): Display name for the environment. Required.
description (str, optional): Description for the environment. Defaults to None.
Raises:
OAATemplateException: If an environment has already been added to this submission.
Returns: HostEnvironment
Add a new Host.
Hosts can be referenced after creation using the .hosts dictionary attribute, keyed case insensitively by unique_id.
Args:
name (str): Display name for host. Required.
unique_id (str): Unique identifier for host for reference by ID. Required.
environment_id (str, optional): ID of the Environment this host belongs to. Required when this submission carries no environment of its own (a per-host agent submission); must be absent when add_environment() has been called on this provider. Defaults to None.
Raises:
OAATemplateException: name or unique_id is empty, or host is already defined.
Returns: HostNode
Add a new privilege definition.
Privileges are defined once on the fleet and referenced by name wherever they are granted via HostNode.add_grant().
Args:
name (str): Name grants refer to
privilege_type (list[OAAPermission]): Canonical access types this privilege confers
description (str, optional): Description for privilege. Defaults to None.
Raises:
OAATemplateException: name is empty, or privilege with name already exists.
Returns: HostPrivilegeDefinition
Get the OAA payload.
Returns the complete OAA template payload for the host fleet as serializable dictionary
Returns:
dict: OAA payload as dictionary
Environment for a Host fleet.
Represents the fleet-wide information for a Host submission. Created by HostProvider.add_environment().
Args:
unique_id (str): Unique ID for the environment. Required.
name (str): Display name for the environment. Required.
description (str, optional): Description for the environment. Defaults to None.
Raises:
ValueError: unique_id or name is empty.
OAATemplateException: An identity_provider_types value is not a known IdP kind.
Output function for payload.
A single host machine.
Contains the host's own users, groups, credentials, resources and grants. Created by HostProvider.add_host().
Args:
name (str): Display name for host. Required.
unique_id (str): Unique identifier for host. Required.
environment_id (str, optional): ID of the Environment this host belongs to. Required for a per-host agent submission, which carries no environment of its own; must be absent when the submission carries an environment. Defaults to None.
Attributes:
platform (str): Host platform, e.g. "linux". None until set.
version (str): Host platform version, e.g. "Ubuntu 22.04.4 LTS". None until set.
ip_address (str): Host IP address. None until set.
Raises:
ValueError: name or unique_id is empty.
Add a new credential to this host.
A credential is a way of authenticating as an account, such as an SSH key. It carries no privileges of its own; it identifies which account its holder becomes.
Args:
name (str): Display name for credential. Required.
unique_id (str): Unique identifier for credential. Required.
credential_type (str, optional): Type for credential. Defaults to None.
Raises:
OAATemplateException: name or unique_id is empty, or credential already defined.
Returns: HostCredential
Grant privileges to a principal on this host.
Records which privileges a user or group holds, on the host itself, on resources inside it, or both.
Calling this again for the same principal_id and grantee_type adds to the existing grant where the call applies to the same things, and creates a second grant where it does not. A principal holding sudo on one command and login on the host holds two differently scoped sets of privileges, and they stay apart; a second call naming the same command adds to the first. The same id used for both a user and a group grant likewise produces two separate grants.
Args:
principal_id (str): ID of the user or group holding the privileges. Must be declared among this host's users or groups when is_local is True.
grantee_type (HostGranteeType): Whether principal_id names a user or a group.
is_local (bool, optional): Whether the principal is declared on this host. False for a directory-backed principal, whose identity provider's connector draws the edge from it. Defaults to True.
Raises:
OAATemplateException: principal_id is empty, grantee_type is not a HostGranteeType, a privileges entry is not a name or an object carrying one, or a resources entry is empty or not the expected type.
Add a new group to this host.
Args:
name (str): Display name for group. Required.
unique_id (str): Unique identifier for group. Required.
group_type (str, optional): Type for group. Defaults to None.
Raises:
OAATemplateException: name or unique_id is empty, or group already defined.
Returns: HostGroup
Add a new resource to this host.
A resource is something inside the host that a privilege can apply to, such as a service or a command, rather than the host as a whole.
A unique_id is unique within a resource_type rather than across the host, so a service and a container may both be called postgres.
Args:
name (str): Display name for resource. Required.
unique_id (str): Unique identifier for resource within the resource_type. Required.
resource_type (str): The kind of thing this is, e.g. "service" or "command". Must not contain a "." or ":" character. Required.
Raises:
OAATemplateException: name, unique_id or resource_type is empty, a resource of the same type and unique_id is already defined, or resource_type contains a "." or ":" character.
Returns: HostResource
Add a new user account to this host.
A user belongs to exactly one host: root on two hosts is two accounts, each added separately.
Args:
name (str): Display name for user. Required.
unique_id (str): Unique identifier for user. Required.
identities (list[str], optional): The identities in an identity provider this account belongs to. Required when is_local is False. Defaults to None.
Raises:
OAATemplateException: name or unique_id is empty, user already defined, or identity_type is not a HostIdentityType.
Returns: HostUser
Set a custom property value for the host.
Property name must be defined for the fleet before calling set_property. See HostPropertyDefinitions.define_host_property for more information.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined.
Output function for payload.
A user account on a Host.
A user belongs to exactly one host: root on two hosts is two accounts, each with its own last_login_at and is_active. Created by HostNode.add_user().
Args:
name (str): Display name for user. Required.
unique_id (str): Unique identifier for user. Required.
identities (list[str], optional): The identities in an identity provider this account belongs to. Defaults to None.
Raises:
ValueError: name or unique_id is empty.
OAATemplateException: identity_type is not a HostIdentityType.
Add this user to a group.
Group must also be defined on the host with HostNode.add_group().
Args:
group_id (str): ID of the group to add user to.
Raises:
OAATemplateException: group_id is empty.
Set a custom property value for the user.
Property name must be defined for the fleet's users before calling set_property.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined.
Output function for payload.
A group on a Host.
Created by HostNode.add_group().
Args:
name (str): Display name for group. Required.
unique_id (str): Unique identifier for group. Required.
group_type (str, optional): Type for group. Defaults to None.
Raises:
ValueError: name or unique_id is empty.
Add a member group.
A member may be another group on the same host, or a directory-backed group with no local definition.
Args:
group_id (str): ID of the member group.
is_local (bool, optional): Whether the member group is declared on this host. Defaults to True.
Raises:
OAATemplateException: group_id is empty.
Set a custom property value for the group.
Property name must be defined for the fleet's groups before calling set_property.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined.
Output function for payload.
A credential that authenticates as an account on a Host.
A credential is a way of authenticating as an account, such as an SSH key. It carries no privileges of its own; it identifies which account its holder becomes. Created by HostNode.add_credential().
Credentials have no custom properties.
Args:
name (str): Display name for credential. Required.
unique_id (str): Unique identifier for credential. Required.
credential_type (str, optional): Type for credential. Defaults to None.
Raises:
ValueError: name or unique_id is empty.
Add a holder to this credential.
Holders are the identities known to hold the credential, so several people holding keys to one shared account can be distinguished. A holder is often not an account on this host at all.
Args:
identity_id (str): ID of the identity that holds the credential.
is_local (bool, optional): Whether the holder is an account declared on this host. Defaults to True.
Raises:
OAATemplateException: identity_id is empty.
Output function for payload.
Something inside a host that a privilege can apply to.
A resource is something inside a host that a privilege can apply to, such as a service or a command, rather than the host as a whole. Referred to from a grant as resource_type.id via resource_key. Created by HostNode.add_resource().
Args:
name (str): Display name for resource. Required.
unique_id (str): Unique identifier for resource within the resource_type. Required.
resource_type (str): The kind of thing this is, e.g. "service" or "command". Must not contain a "." or ":" character. Required.
Attributes:
resource_key (str): The resource_type.id identifier a grant uses to refer to this resource.
Raises:
ValueError: name, unique_id or resource_type is empty.
OAATemplateException: resource_type contains a "." or ":" character.
The resource_type.id identifier a grant uses to refer to this resource.
Set a custom property value for the resource.
Property name must be defined for the fleet's resources before calling set_property.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined.
Output function for payload.
A privilege defined once on the fleet and referenced by name wherever it is granted.
Names are supplied by the connector rather than fixed by Veza. Created by HostProvider.add_privilege().
Args:
name (str): Name grants refer to
privilege_type (list[OAAPermission]): Canonical access types this privilege confers
description (str, optional): Description for privilege. Defaults to None.
Raises:
ValueError: name is empty.
OAATemplateException: A privilege_type entry is not an OAAPermission.
Output function for payload.
Model for defining custom properties for a Host fleet's hosts, users, groups and resources.
Property definitions define the names for additional entity properties and the expected type. Credentials have no custom properties.
Attributes:
host_properties (dict): property definitions for hosts
user_properties (dict): property definitions for users
group_properties (dict): property definitions for groups
Check property name for valid characters
Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.
Args:
name (str): name of property to validate
Raises:
OAATemplateException: Name is not a string
OAATemplateException: Name contains invalid characters or does not start with a letter
details (list, optional): list of additional details for error. Defaults to None.token (str, optional): Legacy parameter name for API key. Defaults to None.
options: (dict, optional): Additional arguments to be included with provider create call to Veza. Defaults to None.
optionssave_json (bool, optional): Save the JSON payload to a local file before push. Defaults to False.create_provider (bool, optional): Create a new Provider if Provider does not already exists. Defaults to False.
options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.
save_json (bool, optional): Save the OAA JSON payload to a local file before push. Defaults to False.options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.
privileges (dict[HostPrivilegeDefinition]): Dictionary of privilege definitions, referenced by name from grants
property_definitions (HostPropertyDefinitions): Custom property names and types for the fleet
identity_provider_types (list[str], optional): Which kinds of identity provider may be searched when resolving the identities this submission refers to. Values must be one of IdPProviderType. Absent or empty means all of them. Defaults to None.identity_provider_types (list[str], optional): Which kinds of identity provider may be searched when resolving identities this submission refers to. Values must be one of IdPProviderType. Defaults to None.property_definitions (HostPropertyDefinitions, optional): Property definitions structure for the fleet. Defaults to None.
users (dict[HostUser]): Dictionary of HostUser instancesgroups (dict[HostGroup]): Dictionary of HostGroup instances
credentials (dict[HostCredential]): Dictionary of HostCredential instances
resources (dict[HostResource]): Dictionary of HostResource instances, keyed by resource_type.id
identity_to_privileges (dict): Dictionary of grants, one per principal per set of things the privileges apply to
assumes_user (str, optional): ID of the account on this host this credential authenticates as. Defaults to None.created_at (str, optional): RFC3339 timestamp. Defaults to None.
last_used_at (str, optional): RFC3339 timestamp. Defaults to None.
is_active (bool, optional): Defaults to None.
can_expire (bool, optional): Defaults to None.
expires_at (str, optional): RFC3339 timestamp. Defaults to None.
privileges (list, optional): Privilege names granted, each of which must have been defined on the provider with HostProvider.add_privilege(). An entry may be a bare name (str), or a dict carrying a name key where something needs to be said about how the privilege is held, such as {"name": "sudo", "no_password": True}. Defaults to None.
apply_to_host (bool, optional): Whether these privileges apply to the host itself. Defaults to None, in which case they apply to the host when no resources are given, and to the resources alone when some are.
resources (list, optional): Resources inside the host these privileges also apply to. Accepts HostResource instances or "resource_type.id" strings. Defaults to None.
is_local (bool, optional): True for a group defined on the host itself. False for a directory group granted access without a local definition. Defaults to True.identities (list[str], optional): The identities in an identity provider this group corresponds to. Required when is_local is False. Defaults to None.
is_local (bool, optional): True for an account configured on the host itself. False for a network user granted access without a local account. Defaults to True.
identity_type (HostIdentityType, optional): Whether this account stands for a person. Absent means human. Defaults to None.
is_active (bool, optional): Defaults to None.
last_login_at (str, optional): RFC3339 timestamp of the account's last login to this host. Defaults to None.
is_local (bool, optional): Defaults to True.identity_type (HostIdentityType, optional): Defaults to None.
is_active (bool, optional): Defaults to None.
last_login_at (str, optional): RFC3339 timestamp. Defaults to None.
property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's users. Defaults to None.
is_local (bool, optional): Defaults to True.identities (list[str], optional): The identities in an identity provider this group corresponds to. Defaults to None.
property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's groups. Defaults to None.
assumes_user (str, optional): ID of the account on this host this credential authenticates as. Defaults to None.created_at (str, optional): RFC3339 timestamp. Defaults to None.
last_used_at (str, optional): RFC3339 timestamp. Defaults to None.
is_active (bool, optional): Defaults to None.
can_expire (bool, optional): Defaults to None.
expires_at (str, optional): RFC3339 timestamp. Defaults to None.
property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's resources. Defaults to None.resource_properties (dict): property definitions for resourcesmain()__init__(
error: 'str',
message: 'str',
status_code: 'int' = None,
details: 'list' = None
) → None__init__(*args, **kwargs)__init__(
error: 'str',
message: 'str',
status_code: 'int' = None,
details: 'list' = None
) → None__init__(
url: 'str' = None,
api_key: 'str' = None,
username: 'str' = None,
token: 'str' = None
)add_query_report(report_id: 'str', query_id: 'str') → dictapi_delete(api_path: 'str', params: 'dict' = None) → dictapi_get(api_path: 'str', params: 'dict' = None) → list | dictapi_patch(api_path: 'str', data: 'dict', params: 'dict' = None) → dictapi_post(api_path: 'str', data: 'dict', params: 'dict' = None) → list | dictapi_put(api_path: 'str', data: 'dict', params: 'dict' = None) → list | dictcreate_data_source(
name: 'str',
provider_id: 'str',
options: 'dict | None' = None
) → dictcreate_datasource(name, provider_id)create_provider(
name: 'str',
custom_template: 'str',
base64_icon: 'str' = '',
options: 'dict | None' = None
) → dictcreate_query(query: 'dict') → dictcreate_report(report: 'dict') → dictdatasource_push(
provider_id: 'str',
data_source_id: 'str',
json_data: 'str',
options: 'dict | None' = None
) → dictdatasource_push_parts(
provider_id: 'str',
data_source_id: 'str',
json_data: 'str',
options: 'dict | None' = None,
**configs
) → dictdelete_data_source(data_source_id: 'str', provider_id: 'str') → dictdelete_provider(provider_id: 'str') → dictdelete_query(id: 'str', force: 'bool' = False) → dictdelete_report(id: 'str') → dictget_data_source(name: 'str', provider_id: 'str') → dictget_data_sources(provider_id: 'str') → list[dict]get_provider(name: 'str') → dictget_provider_by_id(provider_id: 'str') → dictget_provider_list() → list[dict]get_queries(include_inactive_queries: 'bool' = True) → list[dict]get_query_by_id(id: 'str') → dictget_report_by_id(id: 'str', include_inactive_queries: 'bool' = True) → dictget_reports(
include_inactive_reports: 'bool' = True,
include_inactive_queries: 'bool' = True
) → list[dict]push_application(
provider_name: 'str',
data_source_name: 'str',
application_object: 'CustomApplication | CustomIdPProvider | EntityEnrichment',
save_json: 'bool' = False,
create_provider: 'bool' = False,
options: 'dict | None' = None
) → dictpush_metadata(
provider_name: 'str',
data_source_name: 'str',
metadata: 'dict',
save_json: 'bool' = False,
options: 'dict | None' = None
) → dictupdate_provider_icon(provider_id: 'str', base64_icon: 'str') → Noneupdate_provisioning_status(provider_id: 'str', provisioning: 'bool') → Noneupdate_report(report_id: 'str', report: 'dict') → dictupdate_user_agent(extra: 'str' = '') → None__init__(backoff_max=30, **kwargs) → None__init__(host_type: 'str') → Noneadd_environment(
unique_id: 'str',
name: 'str',
description: 'str' = None,
identity_provider_types: 'List[str]' = None
) → HostEnvironmentadd_host(name: 'str', unique_id: 'str', environment_id: 'str' = None) → HostNodeadd_privilege(
name: 'str',
privilege_type: 'List[OAAPermission]',
description: 'str' = None
) → HostPrivilegeDefinitionget_payload() → dict__init__(
unique_id: 'str',
name: 'str',
description: 'str' = None,
identity_provider_types: 'List[str]' = None
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
environment_id: 'str' = None,
property_definitions: 'HostPropertyDefinitions' = None
) → Noneadd_credential(
name: 'str',
unique_id: 'str',
credential_type: 'str' = None,
assumes_user: 'str' = None,
created_at: 'str' = None,
last_used_at: 'str' = None,
is_active: 'bool' = None,
can_expire: 'bool' = None,
expires_at: 'str' = None
) → HostCredentialadd_grant(
principal_id: 'str',
grantee_type: 'HostGranteeType',
is_local: 'bool' = True,
privileges: 'list' = None,
apply_to_host: 'bool' = None,
resources: 'list' = None
) → Noneadd_group(
name: 'str',
unique_id: 'str',
group_type: 'str' = None,
is_local: 'bool' = True,
identities: 'List[str]' = None
) → HostGroupadd_resource(name: 'str', unique_id: 'str', resource_type: 'str') → HostResourceadd_user(
name: 'str',
unique_id: 'str',
identities: 'List[str]' = None,
is_local: 'bool' = True,
identity_type: 'HostIdentityType' = None,
is_active: 'bool' = None,
last_login_at: 'str' = None
) → HostUserset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
identities: 'List[str]' = None,
is_local: 'bool' = True,
identity_type: 'HostIdentityType' = None,
is_active: 'bool' = None,
last_login_at: 'str' = None,
property_definitions=None
) → Noneadd_group(group_id: 'str') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
group_type: 'str' = None,
is_local: 'bool' = True,
identities: 'List[str]' = None,
property_definitions=None
) → Noneadd_member_group(group_id: 'str', is_local: 'bool' = True) → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
credential_type: 'str' = None,
assumes_user: 'str' = None,
created_at: 'str' = None,
last_used_at: 'str' = None,
is_active: 'bool' = None,
can_expire: 'bool' = None,
expires_at: 'str' = None
) → Noneadd_holder(identity_id: 'str', is_local: 'bool' = True) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str',
resource_type: 'str',
property_definitions=None
) → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
privilege_type: 'List[OAAPermission]',
description: 'str' = None
) → Noneto_dict() → dict__init__() → Nonedefine_group_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_host_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_resource_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_user_property(name: 'str', property_type: 'OAAPropertyType') → Noneto_dict() → dictvalidate_name(name: 'str') → NoneClasses for constructing an OAA JSON payload for Custom IDP
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
IdPEntityTypeIdP entity types.
CustomIdPProviderCustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template.
CustomIdPProvider class consists of IdP domain information, user, group and external associations for identities like AWS Roles.
Classes uses dictionaries to track most components, dictionaries are all keyed by string of the entity name
Args:
name (str): Name of IdP
idp_type (str): Type descriptor for IdP, can be unique or share across multiple IdP e.g. ldap, IPA
domain (str): IdP domain name
Attributes:
name (str): Name of custom IdP
idp_type (str): Type for IdP
description (str): Description for IdP
domain
summary
Args:
id (str): description
name (str): description
Raises:
Returns:
CustomIdPApp: description
Add group to IdP.
Arguments:
name (str): primary ID for group
full_name (str): optional display name for group
identity (str): optional unique identifier for group, if None name is used as identity
Add user to IdP
if no identity is set name will be used as identity
Arguments:
name (str): primary ID for user
full_name (str): optional full name for display
email (str): optional email for user
Returns: CustomIdPUser
Return formatted payload as dictionary for JSON conversion and upload
Create and set the identity mapping configuration.
Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.
Returns:
IdentityMappingConfigurationSubmission: The identity mapping configuration.
Domain model for Custom IdP provider.
Args:
name (str): domain name
Attributes:
name (str): domain name
Add a new tag to IdP Domain.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for domain.
Property name must be defined for domain before calling set_property(). See example below and IdPPropertyDefinitions.define_domain_property for more information.
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_domain_property(name="my_property", property_type=OAAPropertyType.STRING) >>> idp.domain.set_property(property_name="my_property", property_value="domain property value")
Output function for payload.
Types of identities for permission mapping.
User model for CustomIdPProvider.
Args:
name (str): username for identity
email (str): primary email for user
full_name (str): Display name for user
Attributes:
name (str): username for identity
email (str): primary email for user
full_name (str): display name for user
Create App assignment for user
Args:
id (str): ID of App assignment, must be unique for user
name (str): Name of assignment
app_id (str): App ID, must exist in list of Apps for IDP
Raises:
OAATemplateException: Duplicate assignment ID
OAATemplateException: Unknown assignment property name
Add AWS Roles to list of roles user can assume by ARN.
Args:
arns (list): list of role ARNs as strings that the user is allowed to assume
Add user to group(s) by group name
Args:
group_identities (list): list of strings for group identities to add user to
Add a new tag to IdP User.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for user.
Property name must be defined for users before calling set_property(). See example below and IdPPropertyDefinitions.define_user_property for more information.
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = idp.add_user(name="User 1") >>> user1.set_property("my_property", "user1 value")
Set an source external identity for user.
source_identity will connect CustomIdP user to a Veza graph IdP user.
provider_type limits scope for finding matching IdP identities
search all providers with IdPProviderType.ANY.
Args:
identity (str): Unique Identity of the source identity
provider_type (IdPProviderType): Type for provider to match source identity from
Function to prepare user entity for payload
Group model for CustomIdPProvider.
Args:
name (str): name of group
full_name (str): optional full name for group
identity (str): optional identifier for group if name is not reference identifier
Parameters:
name (str): name of group
full_name (str): optional full name for group
identity (str): optional identifier for group, if None name is used as identity
Create App assignment for group
Args:
id (str): ID of App assignment, must be unique for group
name (str): Name of assignment
app_id (str): App ID, must exist in list of Apps for IDP
Raises:
OAATemplateException: Duplicate assignment ID
OAATemplateException: Unknown assignment property name
Add AWS Roles to list of roles group members can assume by ARN.
Args:
arns (list): list of role ARNs as strings that the group members are allowed to assume
Add group to group(s) by group name
Adds current group to another parent group by the group identifier
Args:
group_identities (list): list of strings for group identities to add group to
Add a new tag to IdP Group.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for group.
Property name must be defined for groups before calling set_property(). See example below and IdPPropertyDefinitions.define_group_property for more information.
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_group_property(name="my_property", property_type=OAAPropertyType.STRING) >>> group1 = idp.add_group(name="Group 1") >>> group1.set_property("my_property", "group1 value")
Set an source external identity for group.
source_identity will connect CustomIDP group to a Veza graph IdP group.
provider_type limits scope for finding matching IdP group identities
search all providers with IdPProviderType.ANY.
Args:
identity (str): Unique Identity of the source group
provider_type (IdPProviderType): Type for provider to match source identity from
Function to prepare user entity for payload.
App model for CustomIdPProvider
Args:
id (str): ID for App, must be unique
name (str): Name for App
property_definitions (IdPPropertyDefinitions, optional): Custom property definitions, required to set custom properties. Defaults to None.
Attributes:
id (str): ID for App, must be unique
name (str): Name for App
description (str): Description property for App
Add AWS Roles to list of roles App can assume by ARN. Any Users or Groups assigned to the App are represented as being able to assume the roles.
Args:
arns (list): list of role ARNs as strings that the user is allowed to assume
Add a new tag to IdP User.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set custom property value for app.
Property name must be defined for app before calling set_property(). See example below and IdPPropertyDefinitions.define_app_property for more information.
Args:
property_name (str): Name of property
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_app_property(name="my_property", property_type=OAAPropertyType.STRING) >>> app1 = idp.add_app(id="app1", ="App 1") >>> app1.set_property("my_property", "app1 value")
Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain).
Property definitions define the names for additional entity properties and the expected type.
Attributes:
domain_properties (dict): property definitions for IdP Domain
user_properties (dict): property definitions for IdP users
group_properties (dict): property definitions for IdP groups
Define an app assignment custom property
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define an app custom property
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define a domain custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define a group custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Define a user custom property.
Args:
name (str): name of property
property_type (OAAPropertyType): type for property
Returns custom IdP property definitions.
Validate that a property name has been defined for a given IdP entity.
Raises exception if property name has not been previously defined for entity
Args:
property_name (str): name of property to validate
entity_type (str): type of entity custom property is for (domain, users, groups)
Raises:
OAATemplateException: If property name is not defined
description (str, optional): Description for IdP. Defaults to None.users (dict[CustomIdPUser]): Dictionary of CustomIdPUser class instances
groups (dict[CustomIdPGroup]): Dictionary of CustomIdPGroup class instances
property_definitions (IdPPropertyDefinitions): Custom Property definitions for IdP instance
identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().
identityidentityidentitydepartment (str): department name for user
is_active (bool): if user is active, defaults to None
is_guest (bool): if user is a guest type user, defaults to None
manager_id (str, optional): CustomIdPUser.identity of manager, defaults to None
identity_type (IdPUserIdentityType, optional): Identity type for user (HUMAN, NONHUMAN), defaults to HUMAN if not set.
assignment_propertiesis_security_group (bool): Property for group, defaults to None (unset)assignment_properties__init__(
name: 'str',
idp_type: 'str',
domain: 'str',
description: 'str' = None
) → Noneadd_app(id: 'str', name: 'str') → CustomIdPAppadd_group(
name: 'str',
full_name: 'str' = None,
identity: 'str' = None
) → CustomIdPGroupadd_user(
name: 'str',
full_name: 'str' = None,
email: 'str' = None,
identity: 'str' = None
) → CustomIdPUserget_payload() → dictset_identity_mapping_configuration() → IdentityMappingConfigurationSubmission__init__(
name: 'str',
property_definitions: 'IdPPropertyDefinitions' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
email: 'str' = None,
full_name: 'str' = None,
identity: 'str' = None,
property_definitions: 'IdPPropertyDefinitions' = None
) → Noneadd_app_assignment(
id: 'str',
name: 'str',
app_id: 'str',
assignment_properties: 'Optional[dict]' = None
) → Noneadd_assumed_role_arns(arns: 'List[str]') → Noneadd_groups(group_identities: 'List[str]') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneset_source_identity(identity: 'str', provider_type: 'IdPProviderType') → Noneto_dict() → dict__init__(
name: 'str',
full_name: 'str' = None,
identity: 'str' = None,
property_definitions: 'IdPPropertyDefinitions' = None
) → Noneadd_app_assignment(
id: 'str',
name: 'str',
app_id: 'str',
assignment_properties: 'Optional[dict]' = None
) → Noneadd_assumed_role_arns(arns: 'List[str]') → Noneadd_groups(group_identities: 'List[str]') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneset_source_identity(identity: 'str', provider_type: 'IdPProviderType') → Noneto_dict() → None__init__(
id: 'str',
name: 'str',
property_definitions: 'IdPPropertyDefinitions' = None
) → Noneadd_assumed_role_arns(arns: 'List[str]') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__() → Nonedefine_app_assignment_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_app_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_domain_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_group_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_user_property(name: 'str', property_type: 'OAAPropertyType') → Noneto_dict() → dictvalidate_property_name(property_name: 'str', entity_type: 'str') → NoneMethods for working with Custom Data Providers and Sources
This document provides a basic overview of the API requests for creating and updating an OAA data source. These steps and API calls can be adapted for your client or programming language of choice. You can also use the oaaclient Python module to handle Veza authentication, register the data source, and push the populated template.
While registering sources and pushing authorization metadata with Open Authorization API is relatively straightforward, it is important to understand how Veza organizes custom providers and data sources as endpoints:
You will first register a new custom application provider with a POST request to /api/providers/custom (specifying the app name and template).
The determines the type of entities the provider supports (application, identity_provider, or hris).
Each custom provider can have one or more data sources (such as different instances or domains), generated using .
The populated template can describe additional resources and sub-resources, such as individual databases, repositories, or views.
You can for each custom data source.
All custom data sources are shown on the Configuration > Apps & Data Sources menu, and can be retrieved using .
You should typically name the provider based on the generic application provider (such as GitHub) and the data source after the top-level instance (such as GitHub - Organization). See the for more information about parsing and identifying entities using metadata from the source application.
Your requests will need to include a Veza API Key. For OAA APIs, using a is recommended. Provide it as the bearer auth token in the header of each request, for example:
Follow best practices for managing API keys: Do not save credentials in connector code. Consider using a secrets manager to securely store API keys and make them available at run time.
To add a custom application, you will need to:
Create a new custom provider and data source.
push the entity and authorization data in a JSON payload.
Use to register a new top-level custom provider. The custom_template determines what kind of entities you can push to the provider.
Custom Application provider
This is a common configuration with broad support for modeling applications with local identities, resources, and authorization:
Custom Application with SCIM lifecycle management
If your application exposes SCIM 2.0 endpoints, it can support automated provisioning and deprovisioning through :
Custom Application with REST lifecycle management
For applications that expose custom REST APIs (but not SCIM) for user provisioning. Veza sends REST requests to the application's endpoints through the Insight Point, which must have network access to the target application:
Custom Identity Provider
This template is for modeling custom or unsupported identity providers as a source of users and groups:
Identities and groups in the custom provider can be mapped to local accounts in other systems, and assigned as entity owners. Custom IdPs can also be used as a source of identity for Provisioning Policies.
HRIS Provider
This template is intended to model HR information systems. Set provisioning to true to use the HRIS as a system of record for Provisioning Policies:
Provider creation response
All provider creation requests return the Provider ID, which you will need to create and manage data sources:
Provider creation fields
Using the Python SDK
The oaaclient SDK provides create_provider() with an options parameter for advanced fields:
Each provider needs at least one data source. Create one with
The response will include the data source ID:
Datasources should be unique to the data collected by an OAA integration instance. For example, if an application has a "prod" and "dev" instance, creating a datasource for each will enable independent updates to each environment.
Name the data source uniquely based on the application instance to discover. Try to include the hostname or organization name in the data source. For example, don't use "GitHub" use "GitHub - Acme Inc" or "Portal - prod.corp.com"
Note that a provider id is required in both the request path and body.
Once the data source and provider are active, publish the payload with . The request body must include the Provider ID and Data Source ID.
json_data must contain the populated OAA template as a single JSON string (escaping any unsafe characters such as ").
Specifying the Provider ID and Data Source ID, perform the same used for the initial push.
To update an existing data source, use the operations and operations to get the provider and data source IDs.
curl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY"Template
custom_template value
Use case
application
Applications and services with users, groups, roles, resources, and permissions
identity_provider
Identity sources with users, groups, domains, and app assignments
hris
HR systems with employees, managers, and organizational groups
curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"GitHub","custom_template":"application"}'curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Internal Portal",
"custom_template": "application",
"external_lifecycle_management_type": "SCIM"
}'curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Legacy Access System",
"custom_template": "application",
"external_lifecycle_management_type": "SEND_REST_PAYLOAD"
}'curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Corporate LDAP","custom_template":"identity_provider"}'curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Workday",
"custom_template": "hris",
"provisioning": true
}'{
"value": {
"id": "a6ef8d8d-d17b-4491-a67a-635ad70f1ba9",
"name": "GitHub",
"custom_template": "application",
"state": "ENABLED",
"application_types": [],
"resource_types": [],
"idp_types": [],
"schema_definition_json": "e30="
}
}name
string
Yes
Provider name. Use the generic application name (e.g., "GitHub", not "GitHub - Acme").
custom_template
string
Yes
Template type: application, identity_provider, or hris.
from oaaclient.client import OAAClient
client = OAAClient(url=veza_url, token=veza_api_key)
# Basic application provider
provider = client.create_provider(name="GitHub", custom_template="application")
# Application with SCIM lifecycle management
provider = client.create_provider(
name="Internal Portal", custom_template="application",
options={"external_lifecycle_management_type": "SCIM"}
)
# HRIS as system of record
provider = client.create_provider(
name="Acme HR", custom_template="hris",
options={"provisioning": True}
)curl -X POST "https://${VEZA_URL}/api/v1/providers/custom/${PROVIDER_ID}/datasources" \
-H 'accept: application/json' \
-H 'authorization: Bearer '${API_KEY} \
-d '{"id": "<PROVIDER ID>", "name":"DemoApp - Documentation Datasource"}'{
"value": {
"id": "1bd31da0-64ee-4dfe-82c9-cb9f0f2fc369",
"name": "DemoApp - Documentation Datasource"
}
}{
"id": "532f6fe3-189f-4576-afdf-8913088961e4",
"compression_type": "none",
"data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
"json_data": "{\"name\":\"CustomApp\",\"application_type\"...}"
}curl -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:push" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEY \
--compressed --data-binary @body.jsoncurl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEYcurl -X GET "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEYcurl -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:push" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEY \
--compressed --data-binary @payload.jsonexternal_lifecycle_management_type
string
No
Enable lifecycle management: SCIM (standard SCIM 2.0 protocol) or SEND_REST_PAYLOAD (custom REST calls via Insight Point). Only for application template.
provisioning
boolean
No
Set to true to use as system of record for Lifecycle Management. Primarily for hris template.
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 .
okta
One Login
one_login
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 operations (optional).
identity_mapping_configuration
Configuration for mapping identities between IdP User and other User types from external data sources
list
Any tags to create and apply to the domain.
operation
enum
For , 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
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 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 reviews. Entity details for the user will be updated on push to include the manager as a searchable property.
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 , 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 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 instead)
operation
enum
For , 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
array
Resources to assign this group as manager of (optional).
app_assignments
array
App assignments for this group (optional). See .
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 to create and apply to the group.
operation
enum
For , the operation to use (optional).
Each element of the payload can have property_values, validated against the custom_property_definition.
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
string
With PROPERTY or CUSTOM_PROPERTY, the destination property name to match on. With TEMPLATE, the template expression to evaluate
{
"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 custom properties 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 incremental updates, 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
idp_description
tags
assumed_role_arns
custom_properties
mode
custom_destination_property
Template for modeling secret storage systems with vaults, entries, and permissions
Use this template to model secret and credential management systems using the Open Authorization API. The Secret Store template captures the authorization relationships for custom or self-hosted credential management systems that are not covered by a native Veza integration.
The template models a hierarchical structure:
Secret Store - the top-level entity representing the secret management system instance
Permissions - define actions that identities can perform (e.g., Read, Write, Decrypt)
Vaults - logical containers for secrets within the store
Entries - individual secrets or credentials within a vault
Identities - optional identity mappings linking the entry to external identities
Identity-to-Permission Bindings - map identities to permissions on specific vaults
A can define additional properties for the secret store, permissions, vaults, and entries.
To use the secret store template, set the template type to secret_store when creating a new data provider:
Organizations with custom or self-hosted privileged access management (PAM) systems can use the Secret Store template to model their credential vaults, entries, and access permissions. This example shows how to map a typical PAM structure to the Secret Store template.
This example demonstrates key patterns for working with the template:
Vaults group credentials by scope. Permissions are granted at the vault level. Grouping credentials by team or system (databases, cloud keys) is the natural unit of access control.
allow_identity_assume indicates whether this permission grants the ability to retrieve and use a credential's actual value.
rotation_policy and requires_approval** are custom properties that capture PAM-specific policies useful for access reviews and compliance reporting.
The secret store object is the top-level container for permissions, vaults, and identity mappings.
Permissions define the actions that identities can perform on the secret store and its vaults. Permissions are referenced by name in identity-to-permission bindings.
Vaults are logical containers for secrets within the store. Each vault has a type and can contain multiple entries.
Entries represent individual secrets or credentials within a vault. Entries optionally include that link the credential to external identities in the authorization graph.
To match leaked secrets found by GitHub Secret Scanning to an entry, tag the entry with the credential's identifier. See .
When finds a leaked credential, Veza connects the leaked secret to the Secret Store entries that hold the same credential, with a Matches Credential relationship. An entry matches when it has a tag for the leaked credential's type whose value is the credential's identifier. Tag names and values aren't case-sensitive. Without the tag, an entry matches only through its key_ids. Tags are the main way to connect entries. Use key_ids when the credential's identifier is already its own field, such as a column of a CSV export, so you don't need to add it as a tag. In a , key_ids is the Key IDs attribute, and tags come from the column mapped to Tags.
Veza checks for matches in this order, and stops at the first step that finds any:
Each tag name for the credential type, in the order listed. For LDAP_BIND, bind_cn is checked before bind_identity, so if any entry has a matching bind_cn tag, entries with only a matching bind_identity tag aren't connected. Use the same tag name on all your entries.
Entries whose key_ids include the leaked credential's identifier
Veza connects the leaked secret to every entry found in that step. Only entries whose credential GitHub Secret Scanning finds leaked are connected, so most entries in a vault have no Matches Credential relationship. Veza correlates again after each GitHub scan and each new Secret Store upload.
When secret_store_type is thales_ciphertrust or akeyless and an entry has no key_ids, Veza builds key_ids from these tags or custom properties of the entry. Names aren't case-sensitive, and - matches _. If an entry has key_ids, Veza uses those values as they are and builds none.
Key IDs are the identifiers Veza compares with leaked credentials. Only values in key_ids equal to an identifier that GitHub Secret Scanning currently reports can match: an AWS access key ID, an Azure storage account name, an LDAP account name, or a SQL Server login. Key IDs built for CipherTrust keys, which are key URLs, ARNs, and aliases, don't match any of these.
Identity mappings on vault entries link a credential to external identities in the authorization graph. When the payload is parsed, Veza creates graph edges between the vault entry and the referenced identities. See for more information.
Identity-to-permission mappings define which identities have which permissions on which vaults. Each mapping links an identity to one or more permission assignments.
Each permission assignment binds a set of permissions to a set of vaults for the parent identity.
Custom properties allow you to attach additional metadata to secret store entities. Define properties in the custom_property_definition object, then set values on individual entities.
Property values must match their declared type. Supported types are described in .
After the initial metadata push (which must contain the full payload), you can modify, add, or remove the secret store, permissions, vaults, entries, and identity assignments without resubmitting other entities. An is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.
To create the OAA provider and push data:
Create the provider with the secret_store template type:
Create a data source on the provider:
Push the payload to the data source:
The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json
Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MySecretStore","custom_template":"secret_store"}'secret_store_type
string
Type descriptor for the secret store (e.g., hashicorp_vault). Applied as a searchable property. thales_ciphertrust and akeyless also turn on
custom_property_definition
object
Defines custom properties for the store, permissions, vaults, and entries. See
secret_store
object
The object containing all entities
"secret_store": {
"name": "Production Vault",
"id": "prod-vault-001",
"description": "Production environment secrets",
"tags": [],
"custom_properties": {},
"permissions": [],
"secret_store_vaults": [],
"identity_to_permissions": []
}name
string
Display name for the secret store
id
string
Unique identifier. Defaults to name if not provided
description
string
Description shown in Veza entity details (optional)
"permissions": [
{
"name": "Read",
"id": "perm-read",
"resource": "secrets/*",
"allow_identity_assume": false
}
]name
string
Display name for the permission
id
string
Unique identifier. Defaults to name if not provided
resource
string
Resource path or pattern this permission applies to (optional)
"secret_store_vaults": [
{
"name": "API Keys",
"id": "vault-api-keys",
"vault_type": "kv",
"description": "API key storage",
"tags": [],
"custom_properties": {},
"entries": []
}
]name
string
Display name for the vault
id
string
Unique identifier. Defaults to name if not provided
vault_type
string
Type descriptor for the vault (e.g., kv, transit, pki). Required
"entries": [
{
"name": "Stripe API Key",
"id": "entry-stripe",
"description": "Stripe payment processing key",
"custom_properties": {
"rotation_enabled": true
},
"identities": [
{
"type": "OktaUser",
"external_id": "alice@example.com"
}
]
}
]name
string
Display name for the entry
id
string
Unique identifier. Defaults to name if not provided
description
string
Description shown in Veza entity details (optional)
AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY
aws_key_id
The AWS access key ID. A leaked secret access key matches only when its access key ID is found within a few lines of it
AZURE_STORAGE_ACCOUNT_KEY
azure_storage_account_name
The Azure storage account name
LDAP_BIND
bind_cn or bind_identity
The account name only, such as svc-reports, not the full distinguished name. Names with spaces can't be matched
secret_store_type
Tag or custom property
Key ID
thales_ciphertrust
kid
The Azure Key Vault key URL, both as is and without its version
thales_ciphertrust
arn
The AWS KMS key ARN
thales_ciphertrust
keyid or key_id
The AWS KMS key ID
thales_ciphertrust
alias
"identities": [
{
"type": "OktaUser",
"external_id": "alice@example.com"
}
]type
string
The type of external identity (e.g., OktaUser, AzureADUser, AWSIAMUser)
external_id
string
The external identifier for the identity (e.g., email address, ARN)
"identity_to_permissions": [
{
"identity": "admin-user",
"identity_type": "local_user",
"permission_assignments": [
{
"vault": ["vault-api-keys", "vault-db-creds"],
"permissions": ["Read", "Write"]
}
]
}
]identity
string
The identity ID or name
identity_type
string
The type of identity (e.g., local_user)
permission_assignments
array
Array of objects
vault
array
List of vault IDs or names that this assignment applies to
permissions
array
List of permission names granted to the identity on these vaults
"custom_property_definition": {
"secret_store_properties": {
"environment": "STRING"
},
"permission_properties": {},
"vault_properties": {
"encryption_type": "STRING"
},
"entry_properties": {
"rotation_enabled": "BOOLEAN"
}
}secret_store_properties
Custom properties for the secret store entity
permission_properties
Custom properties for permission entities
vault_properties
Custom properties for vault entities
entry_properties
Custom properties for vault entry entities
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MySecretStore","custom_template":"secret_store"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"my_secret_store_source"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"identity_mapping_configuration
object
Optional configuration for mapping local identities to users from external data sources
incremental_change
boolean
When true, enables (optional)
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
string
Operation type for (optional)
permissions
array
Array of objects
secret_store_vaults
array
Array of objects
identity_to_permissions
array
Array of mappings
allow_identity_assume
boolean
Whether this permission allows identity assumption (optional)
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
operation
string
Operation type for (optional)
description
string
Description shown in Veza entity details (optional)
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
string
Operation type for (optional)
entries
array
Array of objects
tags
array
Specify tags with a key and optional value
custom_properties
dictionary
validated against the custom_property_definition
operation
string
Operation type for (optional)
identities
array
Array of objects (optional)
expires_at
timestamp
When the credential expires, in RFC 3339 format (optional)
credential_type
string
The kind of credential the entry holds, using the GitHub Secret Scanning credential types, such as AWS_ACCESS_KEY. Informational only (optional)
key_ids
array
Identifiers of the credential, which can match leaked secrets with the same identifier (optional)
key_id_kinds
array
A label for each value in key_ids. Must have the same number of values as key_ids (optional)
MSSQL_SQL_LOGIN
sql_login
The SQL Server login
The AWS KMS alias, without the alias/ prefix
akeyless
bind_identity
The LDAP account name
akeyless
bind_dn
The LDAP bind distinguished name
akeyless
bind_identity and ldap_host
DOMAIN\account, where DOMAIN is the first label of ldap_host
akeyless
sql_login
The SQL Server login
akeyless
sql_login and mssql_host
host/login, or host:port/login when mssql_port is set
{
"secret_store_type": "hashicorp_vault",
"custom_property_definition": {
"secret_store_properties": {
"environment": "STRING"
},
"permission_properties": {},
"vault_properties": {
"encryption_type": "STRING"
},
"entry_properties": {
"rotation_enabled": "BOOLEAN"
}
},
"secret_store": {
"name": "Production Vault",
"id": "prod-vault-001",
"description": "Production environment secrets",
"tags": [
{
"key": "department",
"value": "engineering"
}
],
"custom_properties": {
"environment": "production"
},
"permissions": [
{
"name": "Read",
"id": "perm-read",
"resource": "secrets/*",
"allow_identity_assume": false
},
{
"name": "Write",
"id": "perm-write",
"resource": "secrets/*",
"allow_identity_assume": true
}
],
"secret_store_vaults": [
{
"name": "API Keys",
"id": "vault-api-keys",
"vault_type": "kv",
"description": "API key storage",
"tags": [
{
"key": "category",
"value": "api-credentials"
}
],
"custom_properties": {
"encryption_type": "AES-256"
},
"entries": [
{
"name": "Stripe API Key",
"id": "entry-stripe",
"description": "Stripe payment processing key",
"custom_properties": {
"rotation_enabled": true
},
"identities": [
{
"type": "OktaUser",
"external_id": "alice@example.com"
}
]
}
]
},
{
"name": "Database Credentials",
"id": "vault-db-creds",
"vault_type": "kv",
"description": "Database connection credentials",
"custom_properties": {
"encryption_type": "AES-256"
},
"entries": [
{
"name": "PostgreSQL Admin",
"id": "entry-postgres",
"description": "PostgreSQL admin credentials",
"custom_properties": {
"rotation_enabled": true
}
}
]
}
],
"identity_to_permissions": [
{
"identity": "admin-user",
"identity_type": "local_user",
"permission_assignments": [
{
"vault": [
"vault-api-keys",
"vault-db-creds"
],
"permissions": [
"Read",
"Write"
]
}
]
},
{
"identity": "developer-user",
"identity_type": "local_user",
"permission_assignments": [
{
"vault": [
"vault-api-keys"
],
"permissions": [
"Read"
]
}
]
}
]
}
}{
"secret_store_type": "custom_pam",
"custom_property_definition": {
"vault_properties": {
"rotation_policy": "STRING",
"requires_approval": "BOOLEAN"
},
"entry_properties": {
"credential_type": "STRING"
}
},
"secret_store": {
"name": "ACME Internal PAM",
"id": "pam.acme-internal.example.com",
"description": "Production internal credential management system",
"tags": [
{
"key": "environment",
"value": "production"
}
],
"permissions": [
{
"name": "View",
"id": "perm-view",
"allow_identity_assume": false
},
{
"name": "Checkout",
"id": "perm-checkout",
"allow_identity_assume": true
},
{
"name": "Rotate",
"id": "perm-rotate",
"allow_identity_assume": false
},
{
"name": "Manage",
"id": "perm-manage",
"allow_identity_assume": false
}
],
"secret_store_vaults": [
{
"name": "Production Databases",
"id": "vault-prod-databases",
"vault_type": "database",
"description": "Privileged database credentials for production systems",
"custom_properties": {
"rotation_policy": "30-day",
"requires_approval": true
},
"entries": [
{
"name": "postgres-prod-admin",
"id": "cred-pg-admin-001",
"description": "PostgreSQL production superuser",
"custom_properties": {
"credential_type": "service_account"
},
"identities": [
{
"type": "AzureADUser",
"external_id": "dba-admin@acme.com"
}
]
},
{
"name": "mysql-prod-readonly",
"id": "cred-mysql-ro-001",
"description": "MySQL production read-only service account",
"custom_properties": {
"credential_type": "service_account"
}
}
]
},
{
"name": "Cloud Platform Keys",
"id": "vault-cloud-keys",
"vault_type": "cloud_credentials",
"description": "Cloud provider access keys",
"custom_properties": {
"rotation_policy": "90-day",
"requires_approval": false
},
"entries": [
{
"name": "cloud-prod-admin",
"id": "cred-cloud-admin-001",
"description": "Production cloud IAM admin access key",
"custom_properties": {
"credential_type": "access_key"
},
"identities": [
{
"type": "AzureADUser",
"external_id": "platform-eng@acme.com"
}
]
}
]
}
],
"identity_to_permissions": [
{
"identity": "dba-admin@acme.com",
"identity_type": "AzureADUser",
"permission_assignments": [
{
"vault": ["vault-prod-databases"],
"permissions": ["View", "Checkout"]
}
]
},
{
"identity": "platform-eng@acme.com",
"identity_type": "AzureADUser",
"permission_assignments": [
{
"vault": ["vault-cloud-keys"],
"permissions": ["View", "Checkout", "Rotate"]
},
{
"vault": ["vault-prod-databases"],
"permissions": ["View"]
}
]
}
]
}
}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 such as Okta or Azure AD.
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.
Local Access Credentials - defines API keys, tokens, certificates, or other non-human authentication methods used by applications or services.
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.
Additionally, a may describe user-configured key:pair values that can be applied to entities in the payload.
To use the generic app template, set the template type to application when creating a new data provider:
If your custom application exposes SCIM 2.0 compliant endpoints, you can enable automated provisioning and deprovisioning through Veza Lifecycle Management and Access Requests by setting the external_lifecycle_management_type parameter to SCIM:
This enables Veza to automate user provisioning, deprovisioning, and group membership management for your custom application. For detailed configuration and supported operations, see .
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.
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:
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_tagoperation.
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.
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.
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 Access 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
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), set the value that identifies them in that provider in identities. Veza compares each value against a fixed set of attributes per provider, listed in .
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.
*Each value must equal one of the attributes Veza compares on the identity provider. See .
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.
Access credentials represent API keys, tokens, certificates, or other non-human authentication methods used by applications or services.
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
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.
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, local_group, or local_access_creds name, or the identifier of an IdP user, group, or role (email address or group name).
identity_type must be one of: idp
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.
The identity_to_permissions array defines how identities are authorized to applications and resources. Each entry maps an identity to its application permissions and/or role assignments. See the section above for field details.
identity_type may have a default value when not set.AzureADEnterpriseApplicationTrinoUser
MetadataWriteNonData
DataCreate
DataDelete
MetadataCreate
MetadataDelete
Uncategorized
local_userlocal_grouplocal_rolelocal_access_credscurl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
--compressed --data-binary '{"name":"DemoApp","custom_template":"application"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{
"name": "MyCustomApp",
"custom_template": "application",
"external_lifecycle_management_type": "SCIM"
}' "custom_property_definition": {
"applications": [
{
"application_type": "sample",
"application_properties": {},
"local_user_properties": {
"license_type": "STRING",
"license_expires": "TIMESTAMP"
},
"local_group_properties": {},
"local_role_properties": {},
"role_assignment_properties": {},
"access_cred_properties": {},
"resources": []
}
]
} "local_users": [
{
"id": "001010",
"name": "bob",
"identities": [
"bob@example.com"
],
"groups": null,
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z",
"last_login_at": null,
"deactivated_at": null,
"password_last_changed_at": null,
"tags": [],
"custom_properties": {
"license_type": "pro",
"license_expires": "2023-01-01T00:00:00.000Z"
}
}
]{
"applications": [
{
"name": "Custom App",
"application_type": "Source Control",
"description": "Has a resource for each repository",
"custom_properties": {},
"tags": [],
"owners": [],
"local_users": [],
"local_groups": [],
"local_roles": [],
"resources": []
}
]
}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
"resources": [
{
"name": "Entity1",
"id": "Unique ID",
"resource_type": "thing",
"description": "Some entity in the application",
"sub_resources": [
{
"name": "Child 1",
"resource_type": "child",
"description": "My information about resource",
"sub_resources": [],
"custom_properties": {},
"tags": [],
"owners": []
}
],
"custom_properties": {},
"tags": [],
"owners": []
},
{
"name": "Entity2",
"id": "Another Unique ID",
"resource_type": "thing",
"description": "Another entity in the application",
"sub_resources": [],
"custom_properties": {},
"tags": [],
"owners": [],
}
]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.
{
"name": "cog1",
"resource_type": "cog",
"connections": [
{
"id": "service_account@some-project.iam.gserviceaccount.com",
"node_type": "GoogleCloudServiceAccount"
}
]
}"local_users": [
{
"id": "egray",
"name": "Evan Gray",
"email": "egray@example.com",
"identities": ["egray@example.com"],
"groups": ["contractors"],
"is_active": true,
"created_at": "2020-12-19T16:39:57-08:00",
"last_login_at": "2021-11-19T14:19:30-08:00",
"password_last_changed_at": null,
"deactivated_at": null,
"custom_properties": {},
"tags": [],
"owners": []
}
]name
string
Name of the local user, shown in the Veza UI.
id
string
Optional identifier to use for mapping users to groups, roles, and permissions.
email
string
User email address (optional). Separate from identities, this is a display/metadata field on the user entity.
"local_groups": [
{
"name": "US Contractors",
"id": "us-contractors",
"identities": ["user1@company.com"],
"groups": [
"all-contractors",
"all-workers"
],
"tags": [],
"owners": []
}
]name
string
Name of the local group. Primary ID for mapping group to permissions.
id
string
Optional identifier to use for permissions mapping.
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.*
"local_roles": [
{
"name": "administrator",
"id": "0001",
"permissions": ["create","destroy"]
},
{
"name": "operator",
"id": "0002",
"permissions": ["pull", "read"],
"tags": [],
"owners": []
}
]name
string
Name of the local role. Primary ID for mapping role to permissions.
id
string
Optional identifier to use for permissions mapping.
permissions
array
Permissions associated with the role. Must exist in permissions.
"local_access_creds": [
{
"name": "Production API Key",
"id": "prod-key-001",
"created_at": "2023-01-15T08:00:00.000Z",
"expires_at": "2024-01-15T08:00:00.000Z",
"last_used_at": "2023-12-01T14:30:00.000Z",
"can_expire": true,
"is_active": true,
"custom_properties": {},
"tags": [],
"owners": []
}
]name
string
Name of the access credential
id
string
Unique identifier for the credential
created_at
RFC3339 string
When the credential was created (optional)
"permissions": [
{
"name": "Admin",
"permission_type": [
"DataRead",
"DataWrite",
"MetadataRead",
"MetadataWrite"
]
},
{
"name": "Operator",
"permission_type": [
"MetadataRead",
"DataRead"
]
},
{
"name": "Inactive",
"permission_type": [
"NonData"
]
}
]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.
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_to_permissions": [
{
"identity": "Evan Gray",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Veza AI",
"resources": ["terraform-dev", "prod"],
"permission": "pull"
},
{
"application": "Veza AI",
"resources": ["terraform-dev", "prod"],
"permission": "push"
}
]
}
]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).
{
"identity": "idpuser@org.co",
"identity_type": "idp",
"application_permissions":
[
{
"application": "source control",
"resources": ["util-tools", "terraform"],
"apply_to_application": false,
"permission": "write"
},
{
"application": "source control",
"resources": [],
"apply_to_application": true,
"permission": "read"
}
]
}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.
{
"identity": "john_smith",
"identity_type": "local_user",
"role_assignments":[
{
"application": "custom application",
"role": "administrator",
"apply_to_application": true,
"resources": []
},
{
"application": "custom application",
"role": "ops",
"apply_to_application": false,
"resources": ["oaa-vm-1"]
}
]
}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.
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
}
]
},
{
"identity": "0000000002",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
},
{
"application": "Sample App",
"role": "admin",
"apply_to_application": true,
"resources": []
}
]
}
]
custom_properties
dictionary
contain property_values validated against the custom_property_definition
tags
array
Specify tags with a key and optional value (optional)
owners
array
See
local_users
array
Contains zero or more local users (see ).
local_groups
array
Contains zero or more (collections of users).
local_roles
array
Defines permissions for any within the application.
local_access_creds
array
Contains any for the application.
local_agents
array
Contains any AI agent entities for the application.
local_models
array
Contains any AI model entities for the application.
resources
array
Contains any and sub-resources.
okta_app_id
string
(Optional, early access) The Okta Application ID for this application. When set, Veza enriches local users with sso_last_login_at timestamps from Okta SSO activity. Requires Veza Support to enable Okta SSO last login enrichment for your tenant. See .
description
string
Shown in Veza entity details, max 255 characters.
custom_properties
dictionary
See .
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)
owners
array
See
identities
identities array
Correlates the user to a federated identity. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Each value must equal one of the attributes Veza compares on the identity provider, such as an Okta login or an Entra ID principal name. See .
groups
groups array
List of any memberships as strings. Must exist in local groups.
access_creds
array
List of local_access_creds IDs associated with this user (optional).
is_active
boolean
If activity state is available from the provider, use this field to make the value available as a searchable property (optional).
user_type
string
Distinguishes between human and service_account user types (optional). Useful for identifying non-human accounts in access reviews.
principal_id
string
The ID for this user in a linked principal template, used for automatic connection. If not supplied, the user id is used (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)
access_creds
array
List of access credential id values associated with this user (optional). Links the user to their API keys, tokens, or other credentials defined in local_access_creds.
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See
groups
array
List of local groups this group is a member of (for applications that support adding groups to other groups).
access_creds
array
List of local_access_creds IDs associated with this group (optional).
created_at
RFC3339 string
Group creation date (optional).
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See .
roles
array
List of sub-role names for nested role hierarchies (optional). An identity assigned to this role inherits all permissions from its sub-roles.
custom_properties
dictionary
See .
tags
array
Specify tags with a key and optional value (optional).
owners
array
See .
expires_at
RFC3339 string
When the credential expires (optional)
last_used_at
RFC3339 string
Last time the credential was used (optional)
can_expire
boolean
Whether the credential can expire
is_active
boolean
Whether the credential is currently active
custom_properties
dictionary
See
tags
array
See
owners
array
See
resource_types
array
Optional list of resource type strings. When specified, separate permission nodes are created per resource type. See below.
role_assignments
array
Any roles assigned to the identity, and the resources they apply to (role/resource must exist in applications).
permission
string
Maps to a permission name from the second section. Must exist in permissions
resources
array
List of resources and sub-resources where the role applies. Must exist in applications
assignment_properties
dictionary
Custom properties on the role assignment itself (optional). Must be defined in role_assignment_properties within custom_property_definition. Useful for tracking assignment-specific metadata such as assignment date or expiration.
{
"custom_property_definition": {
"applications": [
{
"application_type": "sample",
"application_properties": {},
"local_user_properties": {},
"local_group_properties": {},
"local_role_properties": {},
"resources": []
}
]
},
"applications": [
{
"name": "Sample App",
"application_type": "sample",
"description": "This is a sample app",
"local_users": [
{
"id": "0000000001",
"name": "bob",
"identities": [
"bob@example.com"
],
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z"
},
{
"id": "0000000002",
"name": "jane",
"identities": [
"jane@example.com"
],
"groups": [
"admins"
],
"created_at": "2021-08-13T06:28:13.250Z"
}
],
"local_groups": [
{
"id": "admins",
"name": "Administrators"
}
],
"local_roles": [],
"tags": [],
"custom_properties": {},
"resources": [
{
"id": "0001",
"name": "Entity1",
"resource_type": "thing",
"description": "Some entity in the application",
"sub_resources": [
{
"name": "Child 1",
"resource_type": "child",
"description": "My information about resource"
}
]
},
{
"id": "0002",
"name": "Entity2",
"resource_type": "thing",
"description": "Another entity in the application"
}
]
}
],
"permissions": [
{
"name": "admin",
"permission_type": [
"DataRead",
"DataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "operator",
"permission_type": [
"DataRead",
"MetadataRead"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "manager",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
}
],
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"application_permissions": [
{
"application": "Sample App",
"permission": "operator",
"apply_to_application": true
},
{
"application": "Sample App",
"resources": [
"0001"
],
"permission": "manager"
}
]
},
{
"identity": "admins",
"identity_type": "local_group",
"application_permissions": [
{
"application": "Sample App",
"permission": "admin",
"apply_to_application": true
}
]
}
]
}{
"applications": [
{
"name": "Sample App",
"application_type": "sample",
"description": "This is a sample app",
"local_users": [
{
"name": "bob",
"identities": [
"bob@example.com"
],
"is_active": true,
"created_at": "2022-01-26T20:48:12.460Z",
"id": "0000000001"
},
{
"name": "jane",
"identities": [
"jane@example.com"
],
"created_at": "2021-08-13T06:28:13.250Z",
"id": "0000000002"
}
],
"local_groups": [],
"local_roles": [
{
"id": "admin",
"name": "Administrator",
"permissions": [
"manage_users"
],
"tags": [],
"custom_properties": {}
},
{
"id": "user",
"name": "User",
"permissions": [
"view_tickets",
"close_tickets"
],
"tags": [],
"custom_properties": {}
}
],
"tags": [],
"custom_properties": {},
"resources": []
}
],
"permissions": [
{
"name": "manage_users",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "view_tickets",
"permission_type": [
"DataRead"
],
"apply_to_sub_resources": false,
"resource_types": []
},
{
"name": "close_tickets",
"permission_type": [
"MetadataWrite"
],
"apply_to_sub_resources": false,
"resource_types": []
}
],
"identity_to_permissions": [
{
"identity": "0000000001",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
}
]
},
{
"identity": "0000000002",
"identity_type": "local_user",
"role_assignments": [
{
"application": "Sample App",
"role": "user",
"apply_to_application": true,
"resources": []
},
{
"application": "Sample App",
"role": "admin",
"apply_to_application": true,
"resources": []
}
]
}
]
}Classes for constructing an OAA JSON payload for Custom Application
Copyright 2026 Veza Technologies Inc.
Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.
Global Variables
PROPERTY_NAME_REGEX
OAAPermissionCanonical permissions used by Veza Authorization Framework.
Used to describe the raw data or metadata permissions granted by CustomPermission
OAAIdentityTypeTypes of identities for permission mapping.
Base class for CustomApplication.
Class for modeling application authorization using the OAA Application template.
CustomApplication class consists of identities, resources and permissions and produces the OAA JSON payload for the custom application template.
Class uses dictionaries to track most entities that can be referenced after creation. Dictionaries keys are case insensitive of the entity identifier (name or id). This applies to local_users, local_groups, local_roles, idp_identities, resources and custom_permissions.
Args:
name (str): Name of custom application
application_type (str): Searchable property, can be unique or shared across multiple applications
description (str, optional): Description for application. Defaults to None.
Attributes:
application_type (str): Searchable application type
custom_permissions (dict[OAAPermission]): Dictionary of class instances
description (str): Description for application
Legacy method for backwards compatibility.
Deprecated: Access should be added through identity (local_role, local_group, idp)
Create an Access Credential
Access creds can be used to represent alternative access methods such as API keys or application integrations.
Access creds can be assigned roles and permissions similar to local users. Access credentials can exist independently for use cases such as administratively created integrations or can be assigned to a local user for use cases like personal access tokens.
Args:
unique_id (str): unique identifier for access cred
name (str): name for access cred
Raises:
OAATemplateException: Access credential with unique ID already exists
Returns:
AccessCred: New access cred
Create a new local agent for the application.
Agents represent AI agent entities. They can be assigned to groups, have access credentials, reference models, and be authorized via permissions or roles similar to local users.
Args:
name (str): Display name for agent
unique_id (str, optional): Unique identifier for agent for reference by ID
ai_platform (str, optional): AI platform the agent runs on. Defaults to "".
Raises:
OAATemplateException: Agent with identifier already exists
Returns: LocalAgent
Create a new custom permission.
Creates a new CustomPermission object for the application that can be used to authorize identities to the application, resources/sub-resource or as part of a role.
Args:
name (str): Name of the permission
permissions (list[OAAPermission]): Canonical permissions the custom permission represents
apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.
Returns: CustomPermission
Create an IdP principal identity.
IdP users and groups can be authorized directly to applications and resources by associating custom application permissions and roles with an IdP identity's name or email.
Args:
name (str): IdP unique identifier for user or group.
Returns: IdPIdentity
Create a new local group.
Groups can be associated to resources via permissions or roles. All users in the local group are granted the group's authorization.
Local groups will be identified by name by default, if unique_id is provided it will be used as the identifier instead
Local groups can be referenced after creation using .local_groups dictionary attribute. Dictionary is case insensitive keyed by unique_id or name if not using unique_id.
Args:
name (str): Display name for group
identities (list): List of IdP identities to associate group with.
unique_id (str, optional): Unique identifier for group for reference by ID
Returns: LocalGroup
Create a new local role.
A local role represents a collection of permissions.
Identities (local user, group, idp user) can be assigned a role to the application or resource, granting the role's permissions.
Local roles will be identified by name by default, if unique_id is provided it will be used as the identifier instead.
Local roles can be referenced after creation if needed through
Args:
name (str): Display name for role
permissions (list): List of Custom Permission names to include in role. CustomPermission must be created separately.
unique_id (str, optional): Unique identifier for role for reference by ID
Returns: LocalRole
Create a new local user for application.
Local users can be assigned to groups and associated with resources via permissions or roles. Groups and identities can be provided at creation or added later. See Identity and LocalUser class for operations.
Local users will be identified by name by default, if unique_id is provided it will be used as the identifier instead.
Local users can be referenced after creation using the .local_users dictionary attribute. Dictionary is case insensitivekeyed by unique_id or name if not using unique_id.
Use unique_id when name is not guaranteed to be unique. All permission, group and role assignments will be referenced by unique_id.
Args:
name (str): Display name for user
identities (list): List of identities as strings (usually email) for local user. Used to map local user to discovered IdP identities.
groups (list[LocalGroup]): List of group names (as string) to add user to
Returns: LocalUser
Create a new local model for the application.
Models represent AI model entities. They can be referenced by agents.
Args:
name (str): Display name for model
unique_id (str, optional): Unique identifier for model for reference by ID
ai_platform (str, optional): AI platform the model runs on. Defaults to "".
Raises:
OAATemplateException: Model with identifier already exists
Returns: LocalModel
Add Entity Owner
Add an entity owner to the application.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Create a new resource under the application.
Resource type is used to group and filter application resources. It should be consistent for all common resources of an application.
Returns new resource object.
Resource is identified by name by default unless unique_id is provided. name must be unique if not using unique_id.
Resources can be referenced after creation using the .resources dictionary attribute. Dictionary is keyed by unique_id or name if not using unique_id. Use unique_id when name is not guaranteed to be unique.
Args:
name (str): Name of resources
resource_type (str): Type for resource
description (str, optional): Description of resources. Defaults to None.
Returns: CustomResource
Add a tag to the Application
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Return the 'applications' section of the payload as serializable dictionary.
Add a custom permission to the application.
Deprecated: See CustomApplication.add_custom_permission()
Args:
custom_permission (CustomPermission): CustomPermission class
Raises:
Exception: Duplicate Keys
Returns:
CustomPermission: The defined custom Permission
Collect authorizations for all identities into a single list.
Get the OAA payload.
Returns the complete OAA template payload for application as serializable dictionary
Returns:
dict: OAA payload as dictionary
Return the 'permissions' section of the payload as serializable dictionary.
Set a custom property value for the application.
Property name must be defined for CustomApplication before calling set_property. See example below and ApplicationPropertyDefinitions.define_application_property for more information on defining properties.
Args:
property_name (str): Name of property to set value for, property names must be defined as part of the application property_definitions
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined
Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_application_property(name="my_property", property_type=OAAPropertyType.STRING) >>> app.set_property("my_property", "property value")
Class for resources and sub-resources.
Should be used for representing components of the application to which authorization is granted. Each resource has a name and a type. The type can be used for grouping and filtering.
Arguments:
name (str): display name for resource, must be unique to parent application or resource unless using unique_id
resource_type (str): type for resource
description (str): description for resource
Attributes:
name (str): display name for resource, must be unique to parent application or resource
unique_id (str): resource's unique identifier if provided.
resource_type (str): type for resource
No longer supported, access should be added through identity (local_user, local_group, idp)
Add Entity Owner
Add an entity owner to the resource.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add an external connection to the resource.
Used to add a relationship to another entity discovered by Veza such as a service account or AWS IAM role.
Args:
id (str): Unique identifier for connection entity
node_type (str): Veza type for connecting node
Create a new sub-resource under current resource
Args:
name (str): display name for resource
resource_type (str): type for resource
description (str, optional): String description. Defaults to None.
Returns: CustomResource
Add a new tag to resource.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set the value for a custom property on a resource or sub-resource.
Property name must be defined for resource type before calling set_property(). See example below and ApplicationPropertyDefinitions.define_resource_property for more information on defining properties.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property_name is not defined
Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_resource_property(resource_type="cog", name="my_property", property_type=OAAPropertyType.STRING) >>> cog1 = app.add_resource(name="cog1", resource_type="cog") >>> cog1.set_property("my_property", "this value")
Return the dictionary representation of resource.
Base class for deriving all identity types (should not be used directly).
Args:
name (str): name of identity
identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)
unique_id (str, optional): ID of entity for reference by ID
Attributes:
name (str): name of identity
identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)
application_permissions (list[CustomPermission]): List of permissions identity has directly to custom application
Add Entity Owner
Add an entity owner for user or group.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set a custom defined property to a specific value on an identity.
Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example:
app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")
Types of local user account, human or service account.
LocalUser identity, derived from Identity base class.
Used to model an application user. Can be associated with an external IdP user, or represent a local account.
Args:
name (str): name of identity
identities (list): list of strings for IdP identity association
groups (list[LocalGroup]): list of group names as strings to add user too
Attributes:
name (str): name of identity
id (str): ID of entity for ID based reference
email (string): Users email address
Add access cred to user (access cred must be created separately)
Args:
access_cred (str): unique identifier of access cred
Add user to local group (group must be created separately).
Args:
group (str): identifier of local group
Add multiple identities to a local user from a list.
Args:
identities (list[str]): list of identities to add to user
Add an identity to user.
Identity should match the email address or another principal identifier for an IdP user (Okta, Azure, etc.). Veza will create a connection from the application local user to IdP identity.
Args:
identity (str): email or identifier for IdP user
Add Entity Owner
Add an entity owner for user or group.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set a custom defined property to a specific value on an identity.
Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example:
app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")
Output user to dictionary for payload.
LocalGroup identity.
Derived from Identity base class. Used to represent groups of local users for application.
Args:
name (str): name of group
identities (list): list of strings for IdP identity association
unique_id (string, optional): Unique identifier for group
Attributes:
name (str): name of identity
identities (list): list of strings for IdP identity association
groups (list[LocalGroup]): list of group names as strings that group is member of for nested groups
Add a nested group to local group (group must be created separately).
Args:
group (str): identifier of local group
Add an identity to group.
The email address or another valid identifier should match that of an IdP principal (Okta, Azure, etc.). Veza will create a connection from the application local group to IdP identity.
Args:
identity (str): primary IdP identifier for group to associate
Add Entity Owner
Add an entity owner for user or group.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set a custom defined property to a specific value on an identity.
Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example:
app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")
Output group to dictionary for payload.
IdP identity derived from Identity base class.
Used to associate IdP identities (users or groups) directly to resource where concept of local users/groups doesn't apply to application.
Args:
name (str): Primary IdP identifier for identity (email, group name, etc)
property_definitions (ApplicationPropertyDefinitions, optional): Property definitions for role assignment validation
Attributes:
name (str): name of identity
identity_type (OAAIdentityType): Veza Identity Type, (idp)
application_permissions (list[CustomPermission]): permissions identity has directly to custom application
Add Entity Owner
Add an entity owner for user or group.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set custom IdP property (no functionality).
IdP identities do not support custom properties since the identity is discovered through the provider (Okta, Azure, etc)
Access Credential derived from Identity base class.
Access Creds can be used to represent non-user based methods that grant access such as API keys or integrations.
AccessCreds can be assigned roles or permissions to an application or resource. An AccessCred can stand-alone or be associated to a local user.
Args:
unique_id (str): Unique identifier for access cred
name (str): Name for access cred, does not need to be unique
Attributes:
unique_id (str): Unique identifier for access cred
name (str): Name for access cred, does not need to be unique
is_active (bool): Indicate if credential is active, defaults to True
Add Entity Owner
Add an entity owner to the access credential.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set a custom defined property to a specific value on an access credential.
Property name must be defined for access credentials before calling set_property(). See example below and ApplicationPropertyDefinitions.define_access_cred_property for more information on defining properties.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Example:
app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_access_cred_property(name="my_property", property_type=OAAPropertyType.STRING) >>> cred1 = app.add_access_cred(unique_id="cred001", name="Cred 001") >>> cred1.set_property("my_property", "value for cred001")
Output Access credential dictionary for payload
Local Agent identity, derived from Identity base class.
Represents an AI agent entity within an application. Agents can be assigned to groups, have access credentials, reference models, and be authorized via permissions or roles.
Args:
name (str): Display name for agent
unique_id (str, optional): Unique identifier for agent for reference by ID
ai_platform (str, optional): AI platform the agent runs on
Attributes:
name (str): Display name
unique_id (str): Unique identifier if provided
ai_platform (str): AI platform
ai_agent_publisher
Add access cred to agent (access cred must be created separately).
Args:
access_cred (str): unique identifier of access cred
Add agent to local group (group must be created separately).
Args:
group (str): identifier of local group
Add a model reference to agent (model must be created separately).
Args:
model (str): identifier of local model
Add Entity Owner
Add an entity owner for user or group.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to an identity.
Permission can apply to either the application or application resource/sub-resources
Args:
permissions ([str]): List of strings representing the permission names
resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.
apply_to_application (bool): Apply permission to application when True, defaults to False
Add a role to an identity.
Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.
Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.
Args:
role (str): Name of role as string
resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.
apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any
Add a new tag to identity.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Get a JSON serializable dictionary of all the identity's permissions and roles.
Formats the identity's permissions and roles for the Custom Application template payload
Returns:
dict: JSON serializable dictionary of all the identity's permissions and roles
Set a custom defined property on an agent.
Property name must be defined for agents before calling set_property().
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Output agent to dictionary for payload.
Represents an AI model entity within an application.
Models can be referenced by agents and have custom properties, tags, and owners.
Args:
name (str): Display name for model
unique_id (str, optional): Unique identifier for model for reference by ID
ai_platform (str, optional): AI platform the model runs on
Attributes:
name (str): Display name
unique_id (str): Unique identifier if provided
ai_platform (str): AI platform
ai_model_publisher
Add Entity Owner
Add an entity owner to the model.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a new tag to model.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Defaults to "".
Set a custom defined property on a model.
Property name must be defined for models before calling set_property().
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property with property_name is not defined.
Output model to dictionary for payload.
Represent a Custom Application Local Role.
Local Roles are a collection of permissions (as CustomPermission). Roles can be used to associate a local user, group or IdP identity to an application, resource or sub-resource.
Permissions can either be assigned at creation and/or added later.
If the CustomPermission definition includes resource types in the resource_types list, the permission will only be assigned to resources/sub-resources that match that type as part of an assignment.
Args:
name (str): name of local role
permissions (list[CustomPermission], optional): List of custom permission names (strings) to associate with the role. Defaults to empty list.
unique_id (string, optional): Unique identifier for role for identification by ID
Attributes:
name (str): name of local role
unique_id (str): Unique identifier for role for identification by ID
permissions (list[CustomPermission]): list of custom permission names (strings) to associate with the role
Add Entity Owner
Add an entity owner to the local role.
Args:
external_id (str): IDP identity of the owner
owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser
is_primary (bool, optional): Is Primary Owner. Defaults to False.
Add a permission to the role.
Args:
permissions (list): List of permission names (strings) to add to role
Add a nested sub-role to the role (nested role must be created separately)
Args:
role (str): identifier of the local role to nest inside this role
Add a new tag to role.
Args:
key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.
value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".
Set the value for custom property on a local role.
Property name must be defined for local roles before calling set_property(). See example below and ApplicationPropertyDefinitions.define_local_role_property for more information on defining properties.
Args:
property_name (str): Name of property to set value for
property_value (Any): Value for property, type should match OAAPropertyType for property definition
ignore_none (bool, optional): Do not set property if value is None. Defaults to False.
Raises:
OAATemplateException: If property name is not defined.
Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_role_property(name="my_property", property_type=OAAPropertyType.STRING) >>> role1 = app.add_local_role(name="role1") >>> role1.set_property(property_name="my_property", property_value="role1s value")
Convert role to dictionary for inclusion in JSON payload.
Returns:
dict: serializable dictionary of role
CustomPermission class for defining CustomApplication permissions.
Custom permissions represent the named permissions for the application in its terms (e.g. "Admin" or "PUSH") and define the Veza canonical mapping (e.g. DataRead, MetadataRead, DataWrite).
A permission can either be applied directly to an application or resource or assigned as part of a role.
Optionally, when permissions are used as part of a role, if the resource_types list is populated the permission will only be applied to resources who's type is in the resource_types list when the role is applied to a resource.
Args:
name (str): Display name for permission
permissions (list): List of OAAPermission enums that represent the canonical permissions
apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.
Attributes:
name (str): Display name for permission
permissions (list[OAAPermission]): List of OAAPermission enums that represent the canonical permissions
apply_to_sub_resources (bool): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource.
Add a resource type to the resource_types list.
Extends the list of resource types permission applies to when used in role assignment.
Args:
resource_type (str): The resource type string value
Returns dictionary representation for payload.
Model for defining custom properties for application and its entities (users, groups, roles, resources).
Property definitions define the names for additional entity properties and the expected type.
Args:
application_type (str): type of custom application property definitions apply to
Attributes:
application_properties (dict): property definitions for application
local_user_properties (dict): property definitions for local users
local_group_properties (dict): property definitions for local groups
Define an access cred property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define an application property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a local agent property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a local group property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a local model property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a local role property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a local user property.
Args:
name (str): name for property
property_type (OAAPropertyType): type for property
Define a property for a resource by type of resource.
Args:
resource_type (str): type of resource property definition is for
name (str): property name
property_type (OAAPropertyType): type for property
Return property definitions as dictionary ready for OAA payload
Check property name for valid characters
Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.
Args:
name (str): name of property to validate
Raises:
OAATemplateException: Name is not a string
OAATemplateException: Name contains invalid characters or does not start with a letter
Validate that a property name has been defined for given resource type.
Args:
property_name (str): name of property to validate
entity_type (str): type of entity custom property is for (application, local_user, local_group, local_role, resource)
resource_type (str): (optional) type for validating resource property names, only applicable to entity_type resource
Raises:
OAATemplateException: If property name has not been previously defined for entity
identity_to_permissions (dict): Mapping of authorizations for identities to resourcesidp_identities (dict[IdPIdentity]): Contains federated identities without a corresponding local account
local_groups (dict[LocalGroup]): Contains application groups (collections of users)
local_roles (dict[LocalRole]): Contains application roles (collections of permissions)
local_users (dict[LocalUser]): Contains users local to the application and their properties
name (str): Name of custom application
properties (dict): key value pairs of property values, property keys must be defined as part of the property_definitions
property_definitions (ApplicationPropertyDefinitions): Custom property names and types for the application
resources (dict[CustomResource]): Contains data resources and subresources within the application
ai_agent_publisher (str, optional): Publisher of the AI agent. Defaults to "".resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.
.local_rolesWhen a permission that has resource_types is added to a role, it will only apply to resources with a matching resource_type
unique_id (str, optional): Unique identifier for user for reference by IDai_model_publisher (str, optional): Publisher of the AI model. Defaults to "".ai_model_family (str, optional): Model family. Defaults to "".
ai_model_series (str, optional): Model series. Defaults to "".
unique_idapplication_name (str): name of parent applicationresource_key (str, optional): for sub-resources the full unique identifier required for identity_to_permissions section. Defaults to name or unique_id if not provided.
property_definitions (ApplicationPropertyDefinitions, optional): Property definitions structure for the resource
unique_id (str, optional): Optional unique identifier for the resource. Defaults to None.
application_name (str): name of parent applicationresource_key (str): for sub-resources represents the sub-resource's parent path
sub_resources (dict): dictionary of sub-resources keyed by name
properties (dict): dictionary of properties set for resource
tags (list[Tag]): list of tags
unique_idnameresource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keysapplication_roles (LocalRole): List of roles identity has directly to custom application
resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys
properties (dict): Dictionary of properties for identity, allowed values will vary by identity type
tags (list[Tag]): List of tags
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
unique_id (string, optional): For reference by IDidentitiesgroups (list[LocalGroup]): list of group names as strings to add user too
identity_type (OAAIdentityType): Veza Identity Type (local_user)
application_permissions (list[CustomPermission]): Permissions identity has directly to custom application
resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys
application_roles (list[LocalRole]): Custom application roles assigned directly to the identity
resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys
properties (dict): Dictionary of properties for identity, allowed values will vary by identity type
tags (list[Tag]): List of tags
is_active (bool): Defaults to None for unset
created_at (str): RFC3339 time stamp for user creation
last_login_at (str): RFC3339 time stamp for last login
deactivated_at (str): RFC3339 for user deactivate time
password_last_changed_at (str): RFC3339 time stamp for last password change
user_type (LocalUserType): Set the local user account type
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
identity_type (OAAIdentityType): Veza Identity Type, local_groupapplication_permissions (list[CustomPermission]): permissions identity has directly to custom application
resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys
application_roles (list[LocalRole]): list of roles identity has directly to custom application
resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys
properties (dict): Dictionary of properties for identity, allowed values will vary by identity type
tags (list[Tag]): List of tags
created_at (str): RFC3339 time stamp for group creation time
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keysapplication_roles (list[LocalRole]): roles identity has directly to custom application
resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys
properties (dict): Dictionary of properties for identity, allowed values will vary by identity type
tags (list[Tag]): List of tags
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
created_at (str): Time access cred was created at as RFC3339 timestampe, defaults to emptyexpires_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty
last_used_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty
can_expire (bool): Boolean to indicate if credential type can exipre, defaults to unset
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
ai_agent_publisher (str, optional): Publisher of the AI agentproperty_definitions (ApplicationPropertyDefinitions, optional): Property definitions for the application
is_active (bool): Whether agent is active, defaults to None for unset
created_at (str): RFC3339 timestamp for agent creation
groups (list): List of group names the agent belongs to
access_creds (list): List of access credential IDs associated with the agent
models (list): List of model names/IDs the agent uses
tags (list[Tag]): List of tags
owners (list[EntityOwner]): List of entity owners
properties (dict): Custom properties
assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.
ai_model_publisher (str, optional): Publisher of the AI modelai_model_family (str, optional): Model family
ai_model_series (str, optional): Model series
property_definitions (ApplicationPropertyDefinitions, optional): Property definitions for the application
ai_model_family (str): AI model family
ai_model_series (str): AI model series
created_at (str): RFC3339 timestamp for model creation
tags (list[Tag]): List of tags
owners (list[EntityOwner]): List of entity owners
properties (dict): Custom properties
roles (list[LocalRole]): list of roles nested inside the roletags (list[Tag]): list of Tags instances
resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.
resource_types (list): List of resource types as strings that the permission relates to.
local_role_properties (dict): property definitions for local rolesresources (dict): property definitions for resources keyed by resource type
__init__(name, application_type, description=None)__init__(name: 'str', application_type: 'str', description: 'str' = None) → Noneadd_access(identity, identity_type, permission, resource=None)add_access_cred(unique_id: 'str', name: 'str') → AccessCredadd_agent(
name: 'str',
unique_id: 'str' = None,
ai_platform: 'str' = '',
ai_agent_publisher: 'str' = ''
) → LocalAgentadd_custom_permission(
name: 'str',
permissions: 'List[OAAPermission]',
apply_to_sub_resources: 'bool' = False,
resource_types: 'List[str]' = None
) → CustomPermissionadd_idp_identity(name: 'str') → IdPIdentityadd_local_group(
name: 'str',
identities: 'List[str]' = None,
unique_id: 'str' = None
) → LocalGroupadd_local_role(
name: 'str',
permissions: 'List[str]' = None,
unique_id: 'str' = None
) → LocalRoleadd_local_user(
name: 'str',
identities: 'List[str]' = None,
groups: 'List[str]' = None,
unique_id: 'str' = None
) → LocalUseradd_model(
name: 'str',
unique_id: 'str' = None,
ai_platform: 'str' = '',
ai_model_publisher: 'str' = '',
ai_model_family: 'str' = '',
ai_model_series: 'str' = ''
) → LocalModeladd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_resource(
name: 'str',
resource_type: 'str',
description: 'str' = None,
unique_id: 'str' = None
) → CustomResourceadd_tag(key: 'str', value: 'str' = '') → Noneapp_dict() → dictdefine_custom_permission(
custom_permission: 'CustomPermission'
) → CustomPermissionget_identity_to_permissions() → listget_payload() → dictpermissions_dict() → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → None__init__(
name: 'str',
resource_type: 'str',
description: 'str',
application_name: 'str',
resource_key: 'str' = None,
property_definitions: 'ApplicationPropertyDefinitions' = None,
unique_id: 'str' = None
) → Noneadd_access(identity, identity_type, permission)add_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_resource_connection(id: 'str', node_type: 'str') → Noneadd_sub_resource(
name: 'str',
resource_type: 'str',
description: 'str' = None,
unique_id: 'str' = None
) → CustomResourceadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
identity_type: 'OAAIdentityType',
unique_id: 'str' = None,
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → None__init__(
name: 'str',
identities: 'List[str]' = None,
groups: 'List[str]' = None,
unique_id: 'str' = None,
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_access_cred(access_cred: 'str') → Noneadd_group(group: 'str') → Noneadd_identities(identities: 'List[str]') → Noneadd_identity(identity: 'str') → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name,
identities=None,
unique_id: 'str' = None,
property_definitions: 'ApplicationPropertyDefinitions' = None
)add_group(group: 'str') → Noneadd_identity(identity: 'str') → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → None__init__(
unique_id: 'str',
name: 'str',
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str' = None,
ai_platform: 'str' = '',
ai_agent_publisher: 'str' = '',
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_access_cred(access_cred: 'str') → Noneadd_group(group: 'str') → Noneadd_model(model: 'str') → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permission(
permission: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'bool' = False
) → Noneadd_role(
role: 'str',
resources: 'List[CustomResource]' = None,
apply_to_application: 'Optional[bool]' = None,
assignment_properties: 'Optional[dict]' = None
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneget_identity_to_permissions(application_name: 'str') → dictset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
unique_id: 'str' = None,
ai_platform: 'str' = '',
ai_model_publisher: 'str' = '',
ai_model_family: 'str' = '',
ai_model_series: 'str' = '',
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
permissions: 'List[str]' = None,
unique_id: 'str' = None,
property_definitions: 'ApplicationPropertyDefinitions' = None
) → Noneadd_owner(
external_id: 'str',
owner_type: 'str',
is_primary: 'bool' = False
) → Noneadd_permissions(permissions: 'List[str]') → Noneadd_role(role: 'str') → Noneadd_tag(key: 'str', value: 'str' = '') → Noneset_property(
property_name: 'str',
property_value: 'any',
ignore_none: 'bool' = False
) → Noneto_dict() → dict__init__(
name: 'str',
permissions: 'List[OAAPermission]',
apply_to_sub_resources: 'bool' = False,
resource_types: 'list' = None
) → Noneadd_resource_type(resource_type: 'str') → Noneto_dict() → dict__init__(application_type: 'str') → Nonedefine_access_cred_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_application_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_local_agent_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_local_group_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_local_model_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_local_role_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_local_user_property(name: 'str', property_type: 'OAAPropertyType') → Nonedefine_resource_property(
resource_type: 'str',
name: 'str',
property_type: 'OAAPropertyType'
) → Nonedefine_role_assignment_property(
name: 'str',
property_type: 'OAAPropertyType'
) → Noneto_dict() → dictvalidate_name(name: 'str') → Nonevalidate_property_name(
property_name: 'str',
entity_type: 'str',
resource_type: 'str' = None
) → boolTemplate for modeling access to host machines with accounts, groups, credentials, and privileges
Use this template to model who can sign in to host machines, such as Linux and Windows servers, and what they can do there, using the Open Authorization API. The Host template captures the accounts and groups on each host, the credentials that authenticate as those accounts, and the privileges that principals hold on the host and on services or commands inside it.
Choose this template over the Custom Application template when the governed system is a machine rather than an application. Accounts, groups, and credentials belong to one host, so root on two hosts is two separate accounts, each with its own last login and active state. Grants can name principals from an identity provider directly, so a directory group allowed to sign in needs no local definition.
The template models the following entities:
Environment - a group of hosts that share configuration, such as the identity providers that supply their principals
Host - a single machine
Users - accounts on the host, and directory users granted access without a local account
Groups - groups on the host, and directory groups granted access without a local definition
Credentials - ways of authenticating as an account on the host, such as an SSH key
Resources
Privilege definitions - the privileges that grants refer to, declared once for the whole submission
A can define additional properties for hosts, users, groups, and resources.
In Veza, a submission produces these entities and relationships. Identity provider users and groups, drawn with dashed lines, are created by the identity provider's own integration, not by this template. See .
To use the Host template, set the template type to host when creating a new data provider:
Host providers can be created only through the API, not in the Veza UI. After the first push, the integration's overview shows the host entities.
This template has two submission modes. The fields in the payload, not a flag, select the mode.
Veza rejects a payload that does any of the following:
Sends environment while any host sets environment_id
Omits environment while any host lacks environment_id
Sends neither environment nor any hosts
An environment is shared across the data sources of a provider. Submit it from exactly one data source. Veza keys the environment to the data source that submits it, so an environment submitted from two data sources appears twice.
In single host mode, each machine that reports for itself needs its own data source, because every push replaces everything that data source contributed before. One more data source submits the environment. A collector that reports for several machines can submit them as hosts in one payload, each with its own environment_id. A data source that supplies only the environment sends environment with no hosts. After both are pushed, Veza joins each host to the environment whose id matches the host's environment_id, so push order does not matter. Until a data source on the same provider submits the environment, the hosts that name it have no link to an environment.
identity_provider_types on the environment applies only to hosts submitted in the same payload. Hosts submitted in single host mode are matched against every supported identity provider type. See .
On a Linux server, most access is configured in local files. Accounts are defined in /etc/passwd and groups in /etc/group. SSH keys in each account's ~/.ssh/authorized_keys let their holders sign in as that account, and rules in sudoers let users and groups raise their privileges, either on the whole machine or for particular commands and services. A collector that reads these files maps accounts to users, groups to groups, keys to credentials, and sign-in and sudo rules to grants. The single host sample is the output of such a collector.
The following samples model three Linux setups: a two-host fleet submitted centrally, one machine submitting for itself, and a bastion host where most access is granted to directory principals.
The following fields are limited to 512 characters:
id and name of environments, hosts, users, groups, credentials, and resources
An environment's description
A host's platform, version, ip_address
Veza parses the payload strictly, so a field this template does not define causes the push to fail. This template has no tags field.
Most objects also accept an operation field. It has no effect, because this template does not support incremental updates.
The environment groups hosts that share configuration. Send it in centralized mode, or from the data source that supplies the environment for single host submissions.
identity_provider_types accepts any, active_directory, azure_ad, custom, google_workspace, okta, and one_login.
A host is a single machine. Its users, groups, credentials, resources, and grants are nested inside it, and every reference between them resolves within that host.
User, group, and credential IDs need only be unique within their host. Resource IDs need only be unique within their host and resource type.
A user is an account on the host, or a directory user granted access to the host without a local account. Group membership is declared on the user.
is_local indicates whether an account exists on the machine. identities names the directory user an entry represents:
Veza infers no link from an account name. A local account named alice is not correlated to alice@example.com unless the entry lists that identity in identities or an matches them. A person can also reach a local account through a whose holders names their directory identity.
last_login_at describes one person's sign-ins to one host, so it is set on the host's user rather than on the identity provider user. To record it for a directory user with no local account, submit a user entry with is_local set to false and the person's identity.
A group is a group on the host, or a directory group granted access without a local definition.
A member can be another group on the same host, or a directory group with no local definition. Group nesting is mainly a Windows concept, where a local group can contain a domain group. UNIX groups do not nest, so a Linux collector usually omits member_groups.
A credential is a way of authenticating as an account on the host, such as an SSH key or a Kerberos principal. It carries no privileges of its own. It identifies which account its holder becomes.
A credential has no field for key material or password hashes. It records that a credential exists, its type, which account it authenticates as, and who holds it.
Credentials do not accept custom properties.
Holders record which people hold keys to a shared account. A holder is often a directory identity with no account on the host.
A holder with is_local set to false is linked to the matching identity provider user. A holder with is_local set to true is recorded on the credential, but Veza creates no relationship for it. Veza rejects a credential that names assumes_user and also lists a holder with is_local set to true.
A resource is something inside a host that a privilege can apply to, rather than the host as a whole. Grants refer to a resource as <resource_type>.<id>, such as service.postgresql.
Because the resource type cannot contain a dot, everything before the first dot in a reference is the type, and the rest is the ID. A systemd unit such as postgresql.service is referenced as service.postgresql.service.
File and folder resources, and resources nested inside other resources, are not supported. To model permissions on shares and folders, use the .
Each privilege is defined once, at the top level of the payload, and referenced by name wherever it is granted. The collector chooses privilege names, so it can represent any privilege, such as the right to sign in, to run sudo, or to restart a service.
privilege_type accepts DataRead, DataWrite, DataCreate, DataDelete, MetadataRead, MetadataWrite, MetadataCreate, MetadataDelete, NonData, and Uncategorized. Veza uses these canonical types to compare access across integrations, such as a privilege called sudo-all on a host and one called
Privilege definitions create no entities of their own. They supply the names and permission types that appear on each grant.
identity_to_privileges is set on each host and lists which principals hold which privileges on the host and on the resources inside it. This template expresses grants only and cannot express a rule that denies access.
A grant applies to the host when apply_to_host is true or when it names no resources. It applies to each resource it names. One grant can therefore cover the host, particular resources, or both.
An entry in privileges can be a bare name, or an object with a name key, such as {"name": "sudo-all", "no_password": true}. Veza accepts other keys in the object but records only name.
A grant with is_local set to false names a principal that belongs to an identity provider, such as an Active Directory group allowed by sshd_config. It does not need a matching entry in the host's users or groups.
A Host submission names identity provider principals in four places:
identities on a user, linking the entry to the identity provider users it represents
identities on a group, and member_groups entries with is_local set to false, linking to identity provider groups
holders
Veza matches these values against the integrations for the identity provider types the environment allows. Matching is case-insensitive. The attributes a value can match depend on the identity provider:
An Active Directory group must be named by its distinguished name. A sudoers rule for %linux-admins is submitted as CN=linux-admins,OU=Groups,DC=example,DC=com, not as linux-admins.
Veza makes these links when the host's data source is pushed. If an identity provider integration is added later, hosts already submitted gain the missing links at their next push. Until then, a grant to a directory principal has no principal attached. A grant with no principal attached can also mean that the named identity does not exist.
Veza resolves the members of an identity provider group only if that provider's integration supplies the group's membership.
Host users and groups can be the destination of an , but a Host provider cannot be a mapping source. An identity mapping links a local user or group to an identity provider user or group when the payload lists none in identities.
A Unique ID property matcher reads identity_unique_id, which Veza sets from the first value in identities on any user or group that lists one. A user or group with no identities has no identity_unique_id. To map one, match on a Property such as name, on a Custom Property, or with a Template.
The following tables cover common ways a person gains access to a Linux or Windows host, and how to express each one. Not expressible means the Host model has no way to represent the case, such as a deny rule or access that no principal holds. Not supported means the template has no field for the case, or Veza rejects it.
Each submission produces the following entity types:
A grant produces one Custom Host Privilege for each target it applies to. A grant that applies to the host and names two resources produces three, each carrying the same privilege names.
Every entity type except Custom Host Privilege has a unique_id property holding the id from the payload. A Custom Host User or Custom Host Group that lists identities also has identity_unique_id, holding the first value. A Custom Host Resource also has host_resource_type, holding the resource_type from the payload, so queries can filter resources by kind. Veza sets all three properties. None of them is a payload field, and a push that includes one fails.
In Query Builder, these entity types connect as follows:
A Custom Host Environment contains its Custom Hosts, and each Custom Host contains its Custom Host Users, Custom Host Groups, and Custom Host Resources.
A Custom Host User, a contained Custom Host Group, or an identity provider group can be a member of a Custom Host Group.
A Custom Host Credential or an identity provider user can assume a Custom Host User, and an identity provider group can assume a Custom Host Group, including principals matched by an .
An identity provider user connects to the Custom Host Credentials it holds.
Custom properties attach additional metadata to host entities. Define properties in the custom_property_definition object, then set values on individual entities.
Property types are STRING, NUMBER, BOOLEAN, TIMESTAMP, and STRING_LIST, and property values must match their declared type. Property names can contain letters, digits, and underscores, and must begin with a letter. Uppercase letters are accepted and stored in lowercase, so two names that differ only in letter case are rejected. Environments, credentials, and privilege definitions do not accept custom properties. See for more detail.
To create the OAA provider and push data:
Create the provider with the host template type:
Create a data source on the provider:
Push the payload to the data source:
The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json
In single host mode, create a data source for each machine that reports for itself, plus exactly one data source that supplies the environment, and push each independently.
Updates follow the same push workflow. Anything missing from a push is removed, so a host belongs to exactly one data source, and two data sources cannot each describe part of the same host. For a centralized payload too large for a single request, use .
To build the payload in Python, use the HostProvider class in the oaaclient SDK, version 1.2.2 or later. See the .
Identity-to-privilege grants - which principals hold which privileges on the host and its resources
array
Array of . Optional, but every privilege a grant names must be defined here
custom_property_definition
object
Optional. Defines custom properties for hosts, users, groups, and resources. See
incremental_change
boolean
Optional. Must be false or omitted. This template does not support incremental updates
environment_idA group's group_type
A credential's credential_type
array
Optional. The identity provider types Veza searches to resolve the identities this submission names. When absent or empty, Veza searches every type
operation
string
Optional. Has no effect
version
string
Optional. Operating system version
ip_address
string
Optional. IP address of the host
environment_id
string
Required in single host mode, and must be absent in centralized mode. The id of the environment this host belongs to
custom_properties
dictionary
Optional. validated against host_properties
users
array
Optional. Array of objects
groups
array
Optional. Array of objects
credentials
array
Optional. Array of objects
resources
array
Optional. Array of objects
identity_to_privileges
array
Optional. Array of . Grants are declared only here
operation
string
Optional. Has no effect
array
The identity provider users this entry represents. Required when is_local is false. Optional when is_local is true, where it links the local account to the person known to use it. Takes a list because more than one person can use one account. See
identity_type
string
Optional. human or nonhuman, case-insensitive. Defaults to human
is_active
boolean
Optional. Whether the account is active. Omitting it records the account as inactive
last_login_at
string
Optional. RFC 3339 timestamp of when this account last signed in to this host
groups
array
Optional. Group references as {"id": "group_id"} objects. Each must name a group declared on the same host
custom_properties
dictionary
Optional. validated against user_properties
operation
string
Optional. Has no effect
boolean
Required. true for a group defined on the host itself. false for a directory group granted access without a local definition
identities
array
The identity provider groups this group corresponds to. Required when is_local is false. Optional when is_local is true, where it links the local group to a directory group
member_groups
array
Optional. Array of references for the groups this group contains
custom_properties
dictionary
Optional. validated against group_properties
operation
string
Optional. Has no effect
assumes_user
object
Optional. The account this credential authenticates as, given as {"id": "user_id"}. Must name a user declared on the same host. A credential with assumes_user cannot list a holder with is_local set to true
holders
array
Optional. Array of references for the identities known to hold the credential
created_at
string
Optional. RFC 3339 timestamp of when the credential was created
last_used_at
string
Optional. RFC 3339 timestamp of when the credential was last used
is_active
boolean
Optional. Whether the credential is active. Omitting it records the credential as inactive
can_expire
boolean
Optional. Whether the credential can expire
expires_at
string
Optional. RFC 3339 timestamp of when the credential expires
operation
string
Optional. Has no effect
dictionary
Optional. validated against resource_properties
operation
string
Optional. Has no effect
readarray
Optional. The privilege names granted. Each must appear in the top-level privileges definitions
apply_to_host
boolean
Optional. Whether the privileges apply to the host itself. A grant that names no resources applies to the host either way
resources
array
Optional. Resources on this host that the privileges apply to, each as <resource_type>.<id>. Each must name a resource declared on the same host
operation
string
Optional. Has no effect
is_localfalseGrants with is_local set to false, linking a directory user or group directly to the privileges it holds
Email address or identity provider ID
Name or email address
one_login
Identity provider ID or email address
Not matched
custom
Identity provider ID or email address
Identity provider ID only
A Kerberos principal permitted to become a local account
~/.k5login
A credential with credential_type set to kerberos_principal, listing the principal's holders in holders
Sign-in permitted to a local group
sshd_config AllowGroups
A grant to that group
Sign-in permitted to a directory group
sshd_config, sssd.conf simple_allow_groups
A grant with is_local set to false
A directory user permitted by name, with no local account
The host's own configuration
A user with is_local set to false and identities
Sign-in permitted through PAM
/etc/security/access.conf
A grant to the named principal
An account that exists but cannot sign in
nologin shell, locked password, expiry
is_active set to false on the user
Access decided by the directory rather than the host
FreeIPA host-based access control, Active Directory userWorkstations
The collector reads the rules from the directory and submits them as grants. The host has no readable copy of the rules
Sign-in denied to a user or group
DenyUsers, DenyGroups, access.conf - entries
Not expressible. The payload carries grants only
An SSH key confined to a single command
command="..." in authorized_keys
Not supported. No field records the restriction
A certificate principal permitted to become an account
AuthorizedPrincipalsFile with an SSH certificate authority
Not supported
A key held by someone who also has an account on this host
authorized_keys
Not supported. Veza rejects a credential that names assumes_user and a holder with is_local set to true. Name the holder by their directory identity instead
Membership in a group that is effectively root
docker, wheel, adm, disk in /etc/group
A grant to that group. Its members receive the privilege through group membership
Sudo rules served from the directory
sudoers: files sss in nsswitch.conf
The collector obtains the rules and submits them as grants
Sudo rules that apply only to some hosts
alice WEBSERVERS=(ALL) ALL
The collector resolves which rules apply to each host
Sudo that requires no password
NOPASSWD:
Not supported. Veza does not distinguish it from sudo that requires a password
Sudo performed as an account other than root
alice ALL=(www-data) ...
Not supported. No field records which account is assumed
Sudo with a program excluded
ALL, !/usr/bin/su
Not expressible. The payload carries grants only
Switching to another account with that account's password
su
Not supported
A program that runs as its owner regardless of who invokes it
setuid and setgid bits
Not expressible. There is no principal to grant it to
A program granted a specific kernel capability
getcap, capability.conf
Not expressible. There is no principal to grant it to
The Remote Desktop Users group
A grant to that group
Remote management access
The Remote Management Users group
A grant to that group
A service or scheduled task configured to run as a particular account
Service or task configuration
Not expressible. The model does not represent software as a principal
NTFS access control lists
Not supported. For shares and folders, see the
A group on a host, or a directory group granted access to it
Host and group
Custom Host Credential
A way of authenticating as an account
Host and credential
Custom Host Resource
A service, command, or other resource inside a host
Host and resource
Custom Host Privilege
One principal's privileges on one target
Principal and target
A Custom Host User, a Custom Host Group, or an identity provider user or group connects to the Custom Host Privileges it holds, and each Custom Host Privilege connects to the Custom Host or Custom Host Resource it applies to.
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyHosts","custom_template":"host"}'Centralized
environment and hosts
environment_id on any host
A system with a view of the whole fleet, such as an inventory system or a fleet scanner, submits the environment and every host in it
Single host
hosts, with environment_id on every host
environment
An agent running on each machine submits only that machine
host_type
string
Required. The kind of host being described, such as linux or windows. Can contain only letters, digits, spaces, underscores, and hyphens. Recorded as a property on every entity the submission produces
environment
object
The environment object. Required in centralized mode, and must be absent in single host mode
hosts
array
Array of host objects. Required in single host mode. A centralized data source that supplies only the environment can omit it
"environment": {
"id": "prod-linux-fleet",
"name": "Production Linux Fleet",
"description": "Production web and database servers",
"identity_provider_types": ["okta"]
}id
string
Required. Identifier for the environment. Single host submissions refer to it in environment_id
name
string
Required. Display name for the environment
description
string
Optional. Description shown in Veza entity details
"hosts": [
{
"id": "web-01",
"name": "web-01.prod.example.com",
"platform": "linux",
"version": "Ubuntu 22.04.4 LTS",
"ip_address": "10.0.1.11",
"custom_properties": {},
"users": [],
"groups": [],
"credentials": [],
"resources": [],
"identity_to_privileges": []
}
]id
string
Required. Identifier for the host, unique within the payload
name
string
Required. Display name for the host, such as its fully qualified domain name
platform
string
Optional. Operating system family, such as linux
"users": [
{
"id": "alice",
"name": "alice",
"is_local": true,
"is_active": true,
"identity_type": "human",
"last_login_at": "2026-09-24T09:14:00Z",
"groups": [{"id": "wheel"}],
"custom_properties": {}
}
]id
string
Required. Identifier for the user, unique within the host
name
string
Required. Display name for the user
is_local
boolean
Required. true for an account configured on the host itself. false for a directory user granted access without a local account, such as an Active Directory or SSSD identity allowed by sshd_config or named in sudoers
is_local
identities
Meaning
true
absent
An account on the host with no link to a person, such as root
true
present
An account on the host that the collector knows belongs to a person, such as alice listing alice@example.com
false
present
A directory user with no account on this host, named in its configuration or seen in a login record
false
absent
"groups": [
{
"id": "wheel",
"name": "wheel",
"group_type": "security",
"is_local": true,
"member_groups": [
{"id": "linux-admins", "is_local": false}
],
"custom_properties": {}
},
{
"id": "linux-admins",
"name": "linux-admins",
"is_local": false,
"identities": ["linux-admins"]
}
]id
string
Required. Identifier for the group, unique within the host
name
string
Required. Display name for the group
group_type
string
Optional. The kind of group, for platforms that have more than one, such as security
id
string
The member group. With is_local set to true, the id of a group declared on the same host. Otherwise the directory group's identity, resolved against the identity provider
is_local
boolean
Optional. Whether the member is a group declared on this host. Defaults to false
operation
string
Optional. Has no effect
"credentials": [
{
"id": "key-root-shared",
"name": "shared root key",
"credential_type": "ssh_key",
"assumes_user": {"id": "root"},
"holders": [
{"id": "alice@example.com", "is_local": false},
{"id": "carol@example.com", "is_local": false}
],
"is_active": true,
"can_expire": false,
"created_at": "2026-01-04T00:00:00Z",
"last_used_at": "2026-09-24T02:00:00Z"
}
]id
string
Required. Identifier for the credential, unique within the host
name
string
Required. Display name for the credential
credential_type
string
Optional. The kind of credential, such as ssh_key or kerberos_principal
id
string
The holder. With is_local set to true, the id of a user declared on the same host. Otherwise the holder's identity, resolved against the identity provider
is_local
boolean
Optional. Whether the holder is a user declared on this host. Defaults to false
"resources": [
{
"id": "postgresql",
"name": "postgresql",
"resource_type": "service",
"custom_properties": {
"listen_port": 5432
}
},
{
"id": "rsync",
"name": "/usr/bin/rsync",
"resource_type": "command"
}
]id
string
Required. Identifier for the resource, unique within the host and resource type. Can contain dots
name
string
Required. Display name for the resource
resource_type
string
Required. The kind of resource, chosen by the collector, such as service or command. Must not contain a dot or a colon
"privileges": [
{
"name": "sudo-all",
"description": "Unrestricted sudo",
"privilege_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
}
]name
string
Required. The name grants refer to
description
string
Optional. Description of the privilege
privilege_type
array
Optional. The canonical permission types this privilege confers. Without it, the privilege confers no canonical permission types
"identity_to_privileges": [
{
"id": "wheel",
"grantee_type": "group",
"is_local": true,
"privileges": ["sudo-all"],
"apply_to_host": true
},
{
"id": "deploy",
"grantee_type": "user",
"is_local": true,
"privileges": ["restart"],
"apply_to_host": true,
"resources": ["service.postgresql", "command.rsync"]
},
{
"id": "linux-admins",
"grantee_type": "group",
"is_local": false,
"privileges": ["ssh-login"],
"apply_to_host": true
}
]id
string
Required. The principal. With is_local set to true, the id of a user or group declared on the same host. Otherwise the identity of a directory principal
grantee_type
string
Required. user or group
is_local
boolean
Optional. Whether the principal is declared on this host. Defaults to false, so set it to true for local users and groups
active_directory
User principal name, account name, distinguished name, or email address
Distinguished name only
azure_ad
User principal name, onPremisesSamAccountName, identity provider ID, or email address
Name, principal name, or identity provider ID
okta
Login, identity provider ID, or email address
Name or identity provider ID
A local account with a local password
/etc/passwd, /etc/shadow
A user with is_local set to true
An SSH key on a personal account
~/.ssh/authorized_keys
A credential whose assumes_user is that user
Several people holding keys to one shared account, such as root
authorized_keys
One credential per key, with everyone who holds that key listed in holders
Unrestricted sudo for a user or a group
sudoers, sudoers.d
A grant with apply_to_host set to true
Sudo limited to particular programs
alice ALL=(ALL) /usr/bin/rsync
A grant on a command resource
Sudo limited to an action on a service
systemctl restart postgresql
A grant on a service resource
Membership in the local Administrators group
Local groups
A grant to that group. Its members receive the privilege through group membership
A local or domain group placed inside a local group
Local groups
member_groups on the containing group
Rights such as Log on as a service, Back up files and directories, or Debug programs
Local security policy
Grants. The collector chooses the privilege names, so any right can be expressed
Control of a service through a policy rule
/etc/polkit-1/rules.d
A grant on a service resource
Permission to schedule work
cron.allow, cron.deny
A grant with apply_to_host set to true
Permissions on a file or directory
getfacl, mode bits
Not supported. For folders, see the File System template
Custom Host Environment
A group of hosts sharing configuration
Environment
Custom Host
A single machine. Privileges can apply to it directly
Host
Custom Host User
An account on a host, or a directory user granted access to it
Host and user
"custom_property_definition": {
"host_properties": {
"datacenter": "STRING",
"last_audited_at": "TIMESTAMP"
},
"user_properties": {
"is_service_account": "BOOLEAN"
},
"group_properties": {
"owner": "STRING",
"tags": "STRING_LIST"
},
"resource_properties": {
"listen_port": "NUMBER"
}
}host_properties
Custom properties for host entities
user_properties
Custom properties for user entities
group_properties
Custom properties for group entities
resource_properties
Custom properties for resource entities
curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"MyHosts","custom_template":"host"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"prod_linux_fleet"}'curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data "{\"json_data\": $(jq -Rs . payload.json)}"privileges
identity_provider_types
identities
Rejected. A user with no account and no one to attribute it to
is_local
custom_properties
privileges
google_workspace
Remote desktop access
Permissions on a Windows file or share
Custom Host Group
Directory principals appear only where the host names them. sshd_config and sssd.conf permit jsmith, linux-admins, and dbas, which have no local definition. Each is submitted with is_local set to false and an identity to resolve, and each holds login.
An omitted is_active means inactive. jsmith sets no is_active, so Veza records it as inactive.
One key can produce several credentials. A key in two accounts' authorized_keys signs in as each of them, so the credential ID combines the account and the key fingerprint. The key with fingerprint SHA256:F9PpGs… is in the authorized_keys of both root and alice, so it is submitted as two credentials.
A key that names no one has no holders. A key whose comment names nobody, such as laptop, is submitted with no holders.
Sudo is expressed as privileges on the host or on commands. wheel holds sudo-all on the host, written as an object whose no_password key Veza accepts but does not record. svc_deploy holds sudo-command on two command resources, one for each command its sudoers rule allows.
Custom properties describe the collection. sources_read on the host lists the files that were read, so a query can distinguish a host whose sudoers could not be read from a host that grants no sudo.
{
"host_type": "linux",
"custom_property_definition": {
"host_properties": {
"sources_read": "STRING_LIST",
"collector_version": "STRING"
},
"user_properties": {
"shell": "STRING",
"password_locked": "BOOLEAN"
},
"group_properties": {},
"resource_properties": {}
},
"privileges": [
{
"name": "login",
"description": "May open an interactive session on the host",
"privilege_type": [
"NonData"
]
},
{
"name": "sudo-all",
"description": "Unrestricted sudo",
"privilege_type": [
"DataRead",
"DataWrite",
"DataCreate",
"DataDelete",
"MetadataRead",
"MetadataWrite",
"MetadataCreate",
"MetadataDelete"
]
},
{
"name": "sudo-command",
"description": "May run particular commands through sudo",
"privilege_type": [
"NonData"
]
}
],
"hosts": [
{
"id": "app-07",
"name": "app-07.prod.example.com",
"platform": "linux",
"version": "Ubuntu 22.04.4 LTS",
"ip_address": "10.0.2.7",
"environment_id": "prod-linux-fleet",
"custom_properties": {
"sources_read": [
"accounts",
"ssh_keys",
"sshd_config",
"sssd_conf",
"sudoers"
],
"collector_version": "0.1.0"
},
"users": [
{
"id": "root",
"name": "root",
"is_local": true,
"identity_type": "nonhuman",
"is_active": true,
"custom_properties": {
"shell": "/bin/bash",
"password_locked": false
},
"groups": [
{
"id": "root"
}
]
},
{
"id": "daemon",
"name": "daemon",
"is_local": true,
"identity_type": "nonhuman",
"is_active": false,
"custom_properties": {
"shell": "/usr/sbin/nologin",
"password_locked": true
},
"groups": [
{
"id": "daemon"
}
]
},
{
"id": "postgres",
"name": "PostgreSQL administrator",
"is_local": true,
"identity_type": "nonhuman",
"is_active": false,
"custom_properties": {
"shell": "/bin/bash",
"password_locked": true
},
"groups": [
{
"id": "postgres"
}
]
},
{
"id": "alice",
"name": "Alice Nakamura",
"is_local": true,
"identity_type": "human",
"is_active": true,
"custom_properties": {
"shell": "/bin/bash",
"password_locked": false
},
"groups": [
{
"id": "alice"
},
{
"id": "sudo"
},
{
"id": "wheel"
}
]
},
{
"id": "carol",
"name": "Carol Diaz",
"is_local": true,
"identity_type": "human",
"is_active": false,
"custom_properties": {
"shell": "/bin/bash",
"password_locked": true
},
"groups": [
{
"id": "carol"
},
{
"id": "wheel"
}
]
},
{
"id": "svc_deploy",
"name": "Deployment service",
"is_local": true,
"identity_type": "nonhuman",
"is_active": false,
"custom_properties": {
"shell": "/usr/sbin/nologin",
"password_locked": true
},
"groups": [
{
"id": "svc_deploy"
}
]
},
{
"id": "jsmith",
"name": "jsmith",
"identities": [
"jsmith"
],
"is_local": false
}
],
"groups": [
{
"id": "root",
"name": "root",
"group_type": "local",
"is_local": true
},
{
"id": "daemon",
"name": "daemon",
"group_type": "local",
"is_local": true
},
{
"id": "sudo",
"name": "sudo",
"group_type": "local",
"is_local": true
},
{
"id": "postgres",
"name": "postgres",
"group_type": "local",
"is_local": true
},
{
"id": "wheel",
"name": "wheel",
"group_type": "local",
"is_local": true
},
{
"id": "alice",
"name": "alice",
"group_type": "local",
"is_local": true
},
{
"id": "carol",
"name": "carol",
"group_type": "local",
"is_local": true
},
{
"id": "svc_deploy",
"name": "svc_deploy",
"group_type": "local",
"is_local": true
},
{
"id": "linux-admins",
"name": "linux-admins",
"group_type": "directory",
"is_local": false,
"identities": [
"linux-admins"
]
},
{
"id": "dbas",
"name": "dbas",
"group_type": "directory",
"is_local": false,
"identities": [
"dbas"
]
}
],
"credentials": [
{
"id": "root:SHA256:AVLp5MVQPuVN21outJNeQ1jECeaGcPNchYKjWkgdrRQ",
"name": "backup@ci.example.com",
"credential_type": "ssh_key",
"holders": [
{
"id": "backup@ci.example.com",
"is_local": false
},
{
"id": "dcooper@example.com",
"is_local": false
}
],
"is_active": true,
"can_expire": false,
"assumes_user": {
"id": "root"
}
},
{
"id": "root:SHA256:F9PpGsngzsZUNdILKaPPnVMowTBXWl43kYojRg2Y8lg",
"name": "alice@example.com",
"credential_type": "ssh_key",
"holders": [
{
"id": "alice@example.com",
"is_local": false
}
],
"is_active": true,
"can_expire": false,
"assumes_user": {
"id": "root"
}
},
{
"id": "alice:SHA256:F9PpGsngzsZUNdILKaPPnVMowTBXWl43kYojRg2Y8lg",
"name": "alice@example.com",
"credential_type": "ssh_key",
"holders": [
{
"id": "alice@example.com",
"is_local": false
}
],
"is_active": true,
"can_expire": false,
"assumes_user": {
"id": "alice"
}
},
{
"id": "alice:SHA256:mdjRRFt76vijB/211jtzs1JjGFJR6LVIbEqfsGAoPR4",
"name": "laptop",
"credential_type": "ssh_key",
"is_active": true,
"can_expire": false,
"assumes_user": {
"id": "alice"
}
}
],
"resources": [
{
"id": "/usr/bin/rsync",
"name": "/usr/bin/rsync",
"resource_type": "command"
},
{
"id": "/usr/bin/systemctl restart nginx",
"name": "/usr/bin/systemctl restart nginx",
"resource_type": "command"
}
],
"identity_to_privileges": [
{
"id": "root",
"grantee_type": "user",
"is_local": true,
"privileges": [
"sudo-all"
],
"apply_to_host": true
},
{
"id": "sudo",
"grantee_type": "group",
"is_local": true,
"privileges": [
"sudo-all"
],
"apply_to_host": true
},
{
"id": "wheel",
"grantee_type": "group",
"is_local": true,
"privileges": [
{
"name": "sudo-all",
"no_password": true
},
"login"
],
"apply_to_host": true
},
{
"id": "svc_deploy",
"grantee_type": "user",
"is_local": true,
"privileges": [
{
"name": "sudo-command",
"no_password": true
}
],
"resources": [
"command./usr/bin/rsync",
"command./usr/bin/systemctl restart nginx"
]
},
{
"id": "linux-admins",
"grantee_type": "group",
"is_local": false,
"privileges": [
"login"
],
"apply_to_host": true
},
{
"id": "alice",
"grantee_type": "user",
"is_local": true,
"privileges": [
"login"
],
"apply_to_host": true
},
{
"id": "carol",
"grantee_type": "user",
"is_local": true,
"privileges": [
"login"
],
"apply_to_host": true
},
{
"id": "jsmith",
"grantee_type": "user",
"is_local": false,
"privileges": [
"login"
],
"apply_to_host": true
},
{
"id": "dbas",
"grantee_type": "group",
"is_local": false,
"privileges": [
"login"
],
"apply_to_host": true
}
]
}
]
}