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.

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

Getting Started introduces important OAA workflows, the custom application template, and common API operations. When planning your connector, you may also want to review the Core Concepts for more information about naming considerations, mapping custom applications to the OAA schema, and other topics.

Veza provides a Python SDK and working example connectors, 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:

• Custom Application Template - suitable for most applications

• Custom Identity Provider Template - for custom Identity Providers

• API reference - operations for creating, updating, and deleting OAA providers and data sources

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

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

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

3. Publish the payload for processing using Veza APIs (after registering a new custom provider and data source if they don't already exist).

1. Extracting metadata from the source application

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 OAA template.

Before building a connector, you should read the best practices for sourcing metadata and naming conventions, or see the current list of community connectors for real-world examples.

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_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
jane = custom_app.add_local_user("jane", identities="[email protected]")
resource1 = custom_app.add_resource(name="customers", resource_type="database")
jane.add_permission(permission="owner", resources=[customers])

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 Custom Application reference.

{
  "applications": [
    {
      "name": "Support Portal",
      "application_type": "support_portal",
      "description": "Our customer support portal",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[email protected]"
          ],
          "groups": [
            "admins"
          ],
          "is_active": true,
          "last_login_at": "2022-03-21T18:56:38Z"
        },
        {
          "name": "sue",
          "identities": [
            "[email protected]"
          ]        }
      ],
      "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"
        }
      ]
    }
  ]
}

Custom Properties

In addition to built-in properties such as department or last_login_at, most entities can have additional user-defined custom properties. Using custom properties enables integrations to capture application-specific data that can be useful for reporting and provide additional insight during investigations.

You can also apply Veza tags to entities within the payload.

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.

Optionally, subsequent changes can be incremental updates, where the payload only contains entities to modify, add, or remove.

Using oaaclient

The module oaaclient.client can be used to instantiate a Veza connection and manage OAA providers:

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

See Client for additional documentation.

Alternatively, you can make the required REST API calls using the client of your choice or by invoking oaaclient as a command-line tool.

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.

3. The maximum payload size is 100MB. If you need to compress the payload, you can enable the option when creating the OAA data source.

Warnings

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 external id, a warning will be raised if a matching IdP group name or user principal name can't be found.

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

{
  "warnings": [
    {
      "message": "Cannot find identity by names (values: [email protected])"
    }
  ]
}

Veza will always return the warnings key in the response. If a response is empty, there are no warnings.

Errors

For all Veza APIs, error messages 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:

1. The field in which the error occurs

2. The detailed reason for the error

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.

Python Code for the can be referenced on the Veza GitHub

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

Python Code for the can be referenced on the Veza GitHub

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.

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.

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 GitHub repository 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 User Guide.

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

OAA Identity Provider Users can be connected to other IdPs by using the source_identity property on the IdP users. For details see Source Identity Assignments

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.

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

For CSV Upload Integrations, 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.

{
    "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.

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.

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.

You should represent system users using local_user 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.

• Users can also be grouped and assigned permissions with local_groups.

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:

self.app.add_local_role("Write", ["Pull", "Fork", "Push", "Merge"])

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:

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"])

As demonstrated in the OAA PagerDuty connector, this is a quick way to model authorization structures such as:

Both custom properties and Veza Tags can be used to add rich metadata and apply labeling strategies across entities in the Veza data catalog. Both can be viewed by checking an entity's details from tables view or Authorization Graph, 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 using 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.

Modifying Tags with Incremental Updates

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.

...
"local_groups": [
    {
      "name": "LGroup1",
      "identities": [
        "[email protected]"
      ],
      "tags": [
        {
          "key": "NewTag2Key",
          "value": "NewTag2Value"
        }
      ],
      "operation": "add_tag"
    }
]
...

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.

The `oaaclient` package provides data models, methods and a command-line interface for using the . You can use it to populate OAA templates including as Application, IdP, and HRIS, 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.

Handling Errors

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.

Additional documentation

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.

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

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

Custom Identity Provider

Intended for modeling sources of users, group, and federated identity metadata, the can be used to enumerate users and groups that access other external applications and resources, similar to built-in connectors for Okta and AzureAD. These users and groups typically represent the top-level corporate identities within an organization.

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.

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

Built-in properties (such as last_login, created_at, and is_active for local users) enrich Veza graph entities with additional metadata. These built-in properties are described in the template documentation for applications and identity providers.

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.

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

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.

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

OAA custom property examples

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.

Custom properties with oaaclient Python SDK

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", "[email protected]")

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:

  "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": {},
        "resources": [
          {
            "resource_type": "project",
            "properties": {
              "id": "NUMBER",
              "visibility": "STRING"
            }
          }
        ]
      }
    ]
  }

Properties are set on users and resources in custom_properties:

{
  "name": "support-bot",
  "identities": ["[email protected]"],
  "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 properties for a custom identity provider

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

Modules

• : Classes for calling Veza APIs and managing OAA providers and data sources.

• : Classes for constructing an OAA JSON payload (Custom "Application" or "IdP").

• : oaaclient utility functions.

Classes

• : OAA API Connection and Management.

• : Error raised by OAAClient.

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

• : Domain model for Custom IdP provider.

• : Group model for CustomIdPProvider.

• : CustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template.

• : User model for CustomIdPProvider.

• : CustomPermission class for defining CustomApplication permissions.

• : Class for resources and sub-resources.

• : IdP entity types.

• : IdP identity derived from Identity base class.

• : Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain).

• : Veza supported IdP provider types.

• : Base class for deriving all identity types (should not be used directly).

• : LocalGroup identity.

• : Represent a Custom Application Local Role.

• : LocalUser identity, derived from Identity base class.

• : Types of identities for permission mapping.

• : Canonical permissions used by Veza Authorization Framework.

• : Supported types for custom properties on OAA entities such as application, resource, and identity.

• : General exception used for violations of the template schema.

• : Base class for CustomProvider.

• : Veza tag data model.

Functions

• : Helper function to simplify appending.

• : Returns a list of unique strings from input list case insensitive

• : read an icon file to a base64 encoded string

• : Load JSON from file

• : Helper function for logging errors when loading parameters

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.

See the sample payload below for more examples.

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:

  "resources": [
    {
      "name": "resource1",
      "resource_type": "type1",
      "tags": [
        {
          "key": "keyDelta1",
          "value": "valDelta1"
        }
      ],
      "operation": "add_tag"
    },
    {
      "name": "resource1",
      "resource_type": "type1",
      "operation": "modify"
    }
  ]

Sample payload

The following JSON example for custom application 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).

{
  "incremental_change": true,
  "applications": [
    {
      "name": "Controller1",
      "application_type": "WebServer",
      "description": "The base web server",
      "local_users": [
        {
          "name": "LUser1",
          "identities": [
            "[email protected]"
          ],
          "operation": "delete"
        },
        {
          "name": "LUser1",
          "identities": [
            "[email protected]"
          ],
          "operation": "add"
        }
      ],
      "local_groups": [
        {
          "name": "LGroup1",
          "identities": [
            "[email protected]"
          ],
          "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": "[email protected]",
      "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": "[email protected]",
      "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"
        }
      ]
    }
  ]
}

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:

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

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.

OAA does support 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

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.

Code goals

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.

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

High-level code flow

The exact flow of an OAA connector can change to meet specific requirements, but the general steps are as follows:

1. Process and validate configuration parameters. Ensure that all required values are present and valid.

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

3. Create an instance of the Veza.OAA.Application.CustomApplication class to populate with application metadata.

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

5. Check if the Provider and Data Source exist on Veza. Create them if they do not exist.

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

7. Exit.

Customizing the example

To use this example as a starting point for your application integration, follow these steps:

1. Update the name, applicationType, and description of the CustomApplication object based on the source system for integration with Veza.

2. Define any custom_properties needed. Properties must be defined on the CustomApplication object before their values are set on any entities.

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

4. Run the connector to validate the output in Veza.

Example: custom application

The following code provides a template and examples for creating a new application integration using the Veza.OAA SDK.

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
    }
}

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:

Code goals

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.

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

High-level code flow

The exact flow of the connector can change to meet specific requirements, but the general steps are as follows:

1. Process and validate configuration parameters. Ensure you have supplied all necessary values such as host names, user names, and API keys.

2. Call the main run function with all the required and optional parameters.

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

4. Create an instance of the oaaclient.templates.CustomApplication to populate with the application information.

5. Connect to the system and perform discovery of required entities:

   1. The discovery order for users, groups, roles, and so on can be changed based on relationships and interface.

   2. Populate the CustomApplication instance with the identity, roles and permissions, resources, and authorization information.

6. Check if Provider and Data Source exist on Veza. Create them if they do not exist.

7. Push the application to the Data Source. The SDK creates the JSON payload from the CustomApplication instance.

   1. Process any returned warnings or errors.

8. Exit.

Implementing from the example

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

2. Define any custom properties needed in the __init__ method. Properties must be defined on the CustomApplication entities before setting them.

3. 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 SDK operations.

4. Run the connector to validate the output in Veza.

5. Automate the connector to run on a regular schedule.

Code walkthrough for custom application

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

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