Overview and first steps for building an Open Authorization API connector
Last updated
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:
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.
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).
You can use the to simplify the process of populating the payload, connecting to Veza, and managing OAA providers and data sources.
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 .
Typically, the required information will be available from an API, but you should consult the provider's documentation to ensure the information is available, and consider an alternative method for sourcing the data, if not.
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 Python SDK 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.
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.
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.
oaaclientTypically, 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 256 characters.
To validate an AzureAD or other type of user, go to the Authorization 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.
The field in which the error occurs
The detailed reason for the error
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.
Optionally, subsequent changes can be , where the payload only contains entities to modify, add, or remove.
You can use GET to retrieve any existing provider and data source IDs. For more information about managing Providers and Data Sources see .
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 .
The maximum payload size is 100MB. If you need to compress the payload, you can enable the option when .
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.
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: