See the included topics for more information about developing an Open Authorization API connector.

Custom providers and data sources

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.

Custom application names and types

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 Zendesk will allow for search Zendesk Users, Zendesk 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 "Portal - Production" and "Portal - Development".

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.

Use Cases

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.

First Steps

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:

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 the Authorization 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.

Examples

Below are some examples of how applications may be modeled in OAA. These examples have all been implemented using the Application template.

PagerDuty

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.

GitLab

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 OAA Local Role to the Resource that represents the GitLab Group, denoting their level of access (Owner, Developer, Guest, and so on). Veza can return all the members of a GitLab Group by querying for the relation between the OAA User and the OAA Resource. Additionally, the role within the GitLab Group is preserved by the OAA Role.

• 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.

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:

1. Extracting metadata from the source application

2. Generating a sample payload

Most programming languages offer ways to populate and manipulate a JSON schema. You can also use the Python SDK for prebuilt functions:

Custom Properties

3. Creating and Updating Custom Providers and Data Sources

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.

Updates

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.

Using oaaclient

Notes

• 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.

Troubleshooting

Veza enforces strict validation of the json_data field containing the OAA payload. Three checks are performed:

1. All required fields must be present.

2. String fields must be valid UTF-8 strings, no larger than 256 characters.

Warnings

• 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.

Errors

1. The field in which the error occurs

2. The detailed reason for the error

The Open Authorization API enables developers to push metadata to the Veza Authorization 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:

• assemble a dict or similar data structure and convert to JSON

• make REST API calls to publish the payload

Deploying your connector

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

Choosing between full push and incremental updates

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.

To use incremental updates:

• Set the is_incremental flag in the payload to true

• Add an add, modify or delete operation to all entities

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.

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.

Custom Application

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 id for Local Users, Groups and Roles all entities must use the id field. To use the id field for Resources all Resources and Sub-Resources must have an id

Resources

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

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.

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.

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.

Modifying Tags with Incremental Updates

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.

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:

1. Include a definition of all properties as part of the payload push. The definition sets the type for the property.

2. Set the custom properties for each object.

Use cases

If 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 property types

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.

• 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.

Modifying custom properties

Once pushed, properties and types can't be altered. You can re-submit the payload with additional custom property definitions to add new properties.

• 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.

OAA custom property examples

Custom properties with oaaclient Python SDK

Custom properties for a custom application

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:

The following example shows a custom property definition for GitLab:

Properties are set on users and resources in custom_properties:

Custom properties for a custom identity provider

Using local_users to describe local and federated identities and service accounts

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.

• 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.

Map provider permissions to Veza canonical permissions

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.

Modeling role-based access control

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:

Use these REST API calls to manage and update custom providers and data sources with Open Authorization API.

Create Custom Provider

Creates a custom provider and returns the provider ID.

List Custom Providers

Lists all configured custom providers.

Get Custom Provider by ID

Returns details for an individual custom provider.

Delete Custom Provider

Delete a custom provider by ID.

List Custom Provider Datasources

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

Create Custom Provider Datasource

Register a new datasource for a custom provider. There can be more than one datasource for a single provider.

Get Datasource by ID

Returns details for a single datasource.

Delete Custom Provider Datasource

Unbind a datasource from a custom provider, and delete it.

Push Custom Provider Datasource

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.

Push Custom Provider Datasource CSV

CSV data must base64 encoded into the JSON body of the request.

{
    "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}\"}"

Compression

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:

cat app_payload.json | gzip | base64 -o json_data.b64

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).

Escaping unsafe characters

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:

payload = {"id": provider_id,
           "data_source_id": data_source_id,
           "json_data": json.dumps(template_contents)
           }

Custom Provider Icons

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:

curl -X POST '{{VezaURL}}/api/v1/providers/custom/962d5eff-285c-4b08-a54e-400eead1e680:icon' \
-H "authorization: Bearer $API_KEY" \
-d '{"icon_base64": "PHN2ZyBmaWxsPSIjMDAwMDAwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciICB2aWV3Qm94PSIwIDAgNjQgNjQiIHdpZHRoPSIzMnB4IiBoZWlnaHQ9IjMycHgiPjxwYXRoIGQ9Ik0zMiA2QzE3LjY0MSA2IDYgMTcuNjQxIDYgMzJjMCAxMi4yNzcgOC41MTIgMjIuNTYgMTkuOTU1IDI1LjI4Ni0uNTkyLS4xNDEtMS4xNzktLjI5OS0xLjc1NS0uNDc5VjUwLjg1YzAgMC0uOTc1LjMyNS0yLjI3NS4zMjUtMy42MzcgMC01LjE0OC0zLjI0NS01LjUyNS00Ljg3NS0uMjI5LS45OTMtLjgyNy0xLjkzNC0xLjQ2OS0yLjUwOS0uNzY3LS42ODQtMS4xMjYtLjY4Ni0xLjEzMS0uOTItLjAxLS40OTEuNjU4LS40NzEuOTc1LS40NzEgMS42MjUgMCAyLjg1NyAxLjcyOSAzLjQyOSAyLjYyMyAxLjQxNyAyLjIwNyAyLjkzOCAyLjU3NyAzLjcyMSAyLjU3Ny45NzUgMCAxLjgxNy0uMTQ2IDIuMzk3LS40MjYuMjY4LTEuODg4IDEuMTA4LTMuNTcgMi40NzgtNC43NzQtNi4wOTctMS4yMTktMTAuNC00LjcxNi0xMC40LTEwLjQgMC0yLjkyOCAxLjE3NS01LjYxOSAzLjEzMy03Ljc5MkMxOS4zMzMgMjMuNjQxIDE5IDIyLjQ5NCAxOSAyMC42MjVjMC0xLjIzNS4wODYtMi43NTEuNjUtNC4yMjUgMCAwIDMuNzA4LjAyNiA3LjIwNSAzLjMzOEMyOC40NjkgMTkuMjY4IDMwLjE5NiAxOSAzMiAxOXMzLjUzMS4yNjggNS4xNDUuNzM4YzMuNDk3LTMuMzEyIDcuMjA1LTMuMzM4IDcuMjA1LTMuMzM4LjU2NyAxLjQ3NC42NSAyLjk5LjY1IDQuMjI1IDAgMi4wMTUtLjI2OCAzLjE5LS40MzIgMy42OTdDNDYuNDY2IDI2LjQ3NSA0Ny42IDI5LjEyNCA0Ny42IDMyYzAgNS42ODQtNC4zMDMgOS4xODEtMTAuNCAxMC40IDEuNjI4IDEuNDMgMi42IDMuNTEzIDIuNiA1Ljg1djguNTU3Yy0uNTc2LjE4MS0xLjE2Mi4zMzgtMS43NTUuNDc5QzQ5LjQ4OCA1NC41NiA1OCA0NC4yNzcgNTggMzIgNTggMTcuNjQxIDQ2LjM1OSA2IDMyIDZ6TTMzLjgxMyA1Ny45M0MzMy4yMTQgNTcuOTcyIDMyLjYxIDU4IDMyIDU4IDMyLjYxIDU4IDMzLjIxMyA1Ny45NzEgMzMuODEzIDU3Ljkzek0zNy43ODYgNTcuMzQ2Yy0xLjE2NC4yNjUtMi4zNTcuNDUxLTMuNTc1LjU1NEMzNS40MjkgNTcuNzk3IDM2LjYyMiA1Ny42MSAzNy43ODYgNTcuMzQ2ek0zMiA1OGMtLjYxIDAtMS4yMTQtLjAyOC0xLjgxMy0uMDdDMzAuNzg3IDU3Ljk3MSAzMS4zOSA1OCAzMiA1OHpNMjkuNzg4IDU3LjljLTEuMjE3LS4xMDMtMi40MTEtLjI4OS0zLjU3NC0uNTU0QzI3LjM3OCA1Ny42MSAyOC41NzEgNTcuNzk3IDI5Ljc4OCA1Ny45eiIvPjwvc3ZnPg=="}'

Create Custom Provider Icon

Upload a custom icon to display for an OAA provider.

Get Custom Provider Icon

Return the type and string-encoded icon for a custom provider.

Delete Custom Provider Icon

Delete the icon associated with an OAA provider.

OAA utilizes templates (JSON schema) for structuring authorization and identity metadata, combined with a REST API to register, update and manage the data. Once uploaded, Veza processes the template payload and incorporates the entities and permissions into the Authorization Metadata Graph.

Choosing the appropriate template (application or identity provider) is the first step in creating a new integration with OAA. The template provides a schema for describing the identities, resources, and authorization relationships local to the OAA data source.

Custom Application

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

Custom Identity Provider

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.

Overview

The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.

The template has three primary elements, covered in detail in this document:

• Applications - describes one or more application instances for the custom data source. An application may consist of any of the following entities:

  • Local Users - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as last_login_at) and can be linked to a source identity like Okta or AzureAD.

  • Local Groups - defines a group of users, permissions to the application or resources can be assigned to a group.

  • Local Roles - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.

  • Resources - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.

    • Sub Resources - resources can additionally have sub-resources for additional levels of depth.

• Permissions - define the applications specific permissions and map to Veza canonical permissions.

• Identity to Permissions - Assign local and federated users and groups to permissions or roles to the application and resources.

To use the generic app template, set the template type to application when creating a new data provider:

Sample Payload

Custom Properties and Tags

Define custom properties

Set custom properties

In the rest of the payload, for each object that should have additional properties, add a custom_properties array containing the property keys and values:

Validation and Troubleshooting

The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:

• Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.

• Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.

• A 200 OK response may include warnings when matching IDP identities can't be found

Applications

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.

Application Properties

Optional fields: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:

• Any type of data in a JSON payload can be null (not set).

• Unused optional arrays and objects should be empty {} or [].

• Unused optional strings, numbers, and booleans should be null.

• Strings and string lists intended to have constant values (enums) such as identity_type may have a default value when not set.

Resources

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.

Resource Properties

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.

Resource Connections

In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza authorization graph.

If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the connections to another graph entity node_type and id:

The following node types are currently available:

• SnowflakeUser

• GoogleCloudServiceAccount

• AwsIamRole

• AzureADEnterpriseApplication

• TrinoUser

Identities

Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), you can map the principal to the IdP entity name or login email in identities.

Local Users

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:

local Groups

If the application has any groups, describe each one in the local_groups array.

Group assignments for entities are defined in identity_to_permissions.

*Must match a discovered Okta or Azure entity Name, PrincipalName, or Identity

Local Roles

Local roles define collections of local permissions that can be assigned to multiple resources. In the applications section, roles are named and mapped to permissions. Role assignments are defined in identity_to_permissions.

permissions

Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.

Canonical permission types are:

• DataRead

• DataWrite

• MetadataRead

• MetadataWrite

• NonData

• DataCreate

• DataDelete

• MetadataCreate

• MetadataDelete

• Uncategorized

To better model systems where roles can contain different permissions to different types of resources, permissions can apply to individual resource_types.

• When the payload is parsed, individual permissions are created for each type of resource the permission applies to.

• Without resource_types specified, the permission will function normally. When directly connecting principals and resources, resource_type is ignored.

identity_to_permissions

Contains an object for each local and IdP identity, and the individual permissions to applications and resources.

• You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the identity, and setting the identity_type to idp.

• Permissions and role assignments can apply to the entire application or scoped to specific resources.

• For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:

• Each identity can be either a local_user, local_role, or local_group name, or the identifier of an IdP user, group, or role (email address or group name).

• identity_type must be one of (idp (default), local_group, local_role, or local_user.

application_permissions

Binds the identity (IdP entity, local user, or local group) to local permission, by application and resources.

role_assignments

Local roles are assigned to identities in the role_assignments array. Roles can apply to the entire application or only to specific (sub) resources.

Identities to Permissions mapping

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.

Sample Template and Features

The metadata payload describes the Identity Provider domain, users, and groups to add to the Veza authorization graph:

Modeling Assumable Amazon Web Services Roles

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.

Source Identity Assignments

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:

Resource Manager Assignments

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.

Manager Assignments

Users and groups can be mapped to the identity of another user they report to. When configured, the manager will be suggested as a review for Workflow certifications where the assigned reporter is the single query target "named entity."

Custom Properties and Tags

Incremental Updates

Custom Identity Provider definition

The identity provider object models one instance of the custom IdP:

IdP Domain

One domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:

IdP Users

Each IdP user object contains the display name, login email, and identity, along with other identity-related properties:

IdP Groups

Add a group by name in the groups section of the template to enable mapping IdP users to those groups:

IdP Apps

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.

Users and Groups can be assigned to an application by setting the app_assignments in the user or group.

Creating and Updating a Custom Identity Provider

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.

Register a custom identity provider

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:

Push a data source for the custom identity provider

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.

Push metadata for the data source

The payload file must contain the provider and data source ID, and the authorization metadata as a single string, for example:

Identity Mapping Configuration

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.

Identity Mapping Configuration

Identity Mapping Submission

Supported transformations:

• IGNORE_SPECIAL: Ignore special characters (_, -, .) when matching identities

• IGNORE_DOMAIN: Match identities after removing domain portions (e.g., "@example.com")

IdentityMappingPropertyMatchersSubmission

Overview

Use this Open Authorization API template to publish employee metadata for Human Resources Information Systems (HRIS) platforms, typically used by organizations as a single source of truth for employee information.

Unlike an Identity Provider, HR platforms typically do not provide access to other systems. Employee profiles within an HRIS platform are instead used to store important details such as employment status, who individuals report to, department, and country. Veza can use this metadata to:

• Correlate employees in the HRIS system with identities in your identity provider (IdP).

• Enrich Access Reviews with details about linked HRIS employees for users under review.

The template supports:

• A top-level System entity representing the HRIS tenant, organization, or account.

• Employee entities representing current and inactive workers

• Group entities representing teams, departments, cost centers, or other units to which users are assigned.

HRIS template example

Custom properties

Identity mappings

Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or id value in the HRIS payload with the IdP entity's Name, Principal Name, or Identity. The matching process checks these fields in the following sequence:

1. idp_id

2. email

3. id

If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the id is used. Veza issues a warning if no matching entity is found.

Custom HRIS System

The account/tenant/etc. that contains the HR information.

Custom HRIS Employee

Used to represent any person who has been employed by a company.

Custom HRIS Group

Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.

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

  • Principal Name

  • On Premises SAM Account Name

• Okta

  • User Login

Application Template

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.

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.

Identity Provider (IdP) Template

Human Resources Information System (HRIS) Template

Veza will automatically correlate HRIS Employee records and IdP identities based on the HRIS employee's email property. The HRIS employee has an optional parameter for identity_id if the required value is different from the user's email.

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", "delete_tag" to update a tag without altering the entity.

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.

Notes

• 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:

Sample payload