OAA Python SDK

Building blocks for your custom OAA integration

oaaclient can be downloaded from GitHub, or installed with pip3 install oaaclient.

The `oaaclient` package provides data models, methods and a command-line interface for using the Open Authorization API. You can use it to populate OAA templates including 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 modules and the samples directory.

Sample Workflow

Create the Veza API connection and a new custom application:

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

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:

# define a permission
custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
# create a local user
jsmith = custom_app.add_local_user(unique_id="jsmith", name="Jane Smith", identities=["[e-mail]"])
# create a resource
resource1 = custom_app.add_resource(name="Resource 1", resource_type="Thing")
# assign a user to a resource
jsmith.add_permission(permission="owner", resources=[resource1])

Once all identities, permissions and resources are added to the CustomApplication object, the client connection handles the final push to Veza:

veza_con.push_application(provider, data_source_name, application_object=custom_app)

See the GitHub Samples 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.

    try:
        response = veza_con.push_application(provider_name=provider_name,
                                             data_source_name=data_source_name,
                                             application_object=custom_app,
                                            )
        if response.get("warnings"):
            print("Push succeeded with warnings:")
            for w in response["warnings"]:
                print(w)
    except OAAClientError as e:
        print(f"Error: {e.error}: {e.message} ({e.status_code})", file=sys.stderr)
        if hasattr(e, "details"):
            for d in e.details:
                print(d, file=sys.stderr)

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 modules are thoroughly annotated, for reference when building your own integrations.

For additional information about developing a custom OAA integration, please see Open Authorization API section of the User Guide.