Getting Started

Overview and first steps for building an Open Authorization API connector

A built-in Veza integration or OAA connector might not be available for an application or identity provider you want to connect to Veza. However, you can still use the Open Authorization API to integrate compatible applications and identity providers with the rest of your Veza data catalog.

The adaptable OAA schema can model a wide range of authorization models and resource hierarchies, and you will typically have several options for sourcing authorization metadata from the application provider. To integrate a custom application with Veza, you will need to be able to:

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

You can use the Python SDK to simplify the process of populating the payload, connecting to Veza, and managing OAA providers and data sources.

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.

Typically, the required information will be available from an API, but you should consult the provider's documentation to ensure the information is available, and consider an alternative method for sourcing the data, if not.

Before building a connector, you should read the best practices for 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="[e-mail]")
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.

Custom Application Payload

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

You can use GET to retrieve any existing provider and data source IDs. For more information about managing Providers and Data Sources see REST API Operations.

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: [e-mail])"
    }
  ]
}

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