Modules

Classes

Functions

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

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

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

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=["jane@example.com"])
# 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)

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.

Copyright 2023 Veza Technologies Inc.

Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

class CaseInsensitiveDict

Case Insensitive Key Dictionary

Dictionary like object with case insensitive keys for types that support .lower() such as strings.

Keys do not have to be strings, in the case where the key type does not support .lower() such as integers the value is used as is.

Example: from oaaclient.structures import CaseInsensitiveDict >>> x = CaseInsensitiveDict() >>> x["User"] = "value" >>> x.get("user") 'value' >>> "USER" in x True >>> print(x) {'user': 'value'} >>> x CaseInsensitiveDict({'user': 'value'})

method __init__

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

Copyright 2022 Veza Technologies Inc.

Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

Global Variables

• OAACLIENT_VERSION

• PROVIDER_ICON_MAX_SIZE

function report_builder_entrypoint

Entry point for oaaclient-report-builder command

Reads a JSON file and passes it to the oaaclient.utils.build_report method

function main

class OAAClientError

Error raised by OAAClient.

Raised for issues connecting to the OAA API and when the API returns an error.

Args:

• error (str): short string for error message

• message (str): detailed error message

• status_code (int, optional): status code for HTTP related errors. Defaults to None.

• details (list, optional): list of additional details for error. Defaults to None.

method __init__

class OAAResponseError

Error returned from API Call

method __init__

class OAAConnectionError

Error with API Connection

method __init__

class OAAClient

Class for OAA API Connection and Management.

Utilities for OAA-related operations with Veza API calls. Manages custom providers and data sources, and can push OAA payloads from JSON or template objects.

Connection url and API key can be automatically loaded from OS environment values if set. To utilize environment variables initialize OAAClient without providing a URL or API key value and set the VEZA_URL and VEZA_API_KEY OS environment variables.

Args:

• url (str, optional): URL for Veza instance.

• api_key (str, optional): Veza API key.

• username (str, optional): Not used (legacy). Defaults to None.

• token (str, optional): Legacy parameter name for API key. Defaults to None.

Attributes:

• url (str): URL of the Veza instance to connect to

• api_key (str): Veza API key

• enable_compression (bool): Enable or disable compression of the OAA payload during push, defaults to enabled (True)

Raises:

• OAAClientError: For errors connecting to API and if API returns errors

method __init__

method add_query_report

Add a Query to a Report

Adds a Query to an existing Report by ID

Args:

• report_id (str): Report UUID to add Query to

• query_id (str): Query UUID to add

Returns:

• dict: API Response

method api_delete

Perform REST API DELETE operation.

Args:

• api_path (str): API Path API path relative to Veza URL

Raises:

• OAAResponseError: API returned an error

• OAAConnectionError: Connection error during HTTP operation

Returns:

• dict: API response from call

method api_get

Perform a Veza API GET operation.

Makes the GET API call to the given path and processes the API response. Returns the value or values result returned from the API.

• For API endpoints that return a list like /api/v1/providers/custom function will return a list of entities or an empty list if the API returns no results.

• For API endpoints that are a specific ID such as /api/v1/providers/custom/<uuid> function will return the dictionary result of the JSON returned by the API.

Args:

• api_path (str): API path relative to Veza URL (example /api/v1/providers).

Raises:

• OAAResponseError: API returned an error

• OAAConnectionError: Connection error during HTTP operation

Returns:

• list|dict: Returns list or dict based on API destination

method api_patch

Perform REST API PATCH operation.

Args:

• api_path (str): API Path API path relative to Veza URL

Raises:

• OAAResponseError: API returned an error

• OAAConnectionError: Connection error during HTTP operation

Returns:

• dict: API response from call

method api_post

Perform a Veza API POST operation.

Call POST on the supplied Veza instance API path, submitting a data payload.

Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.

Args:

• api_path (str): API path relative to Veza URL example /api/v1/providers

• data (dict): dictionary object included as JSON in body of POST operation

• params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.

Raises:

• OAAResponseError: API returned an error

• OAAConnectionError: Connection error during HTTP operation

Returns:

• dict: API response as dictionary

method api_put

Perform Veza API PUT operation.

Call PUT on the supplied Veza instance API path, including the data payload.

Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.

Args:

• api_path (str): API path relative to Veza URL example /api/v1/providers

• data (dict): dictionary object included as JSON in body of PUT operation

• params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.

Raises:

• OAAResponseError: API returned an error

• OAAConnectionError: Connection error during HTTP operation

Returns:

• dict: API response as dictionary

method create_data_source

Create a new Data Source for the given Provider ID.

Args:

• name (str): Name for new Data Source

• provider_id (str): Unique identifier for the Provider

• options: (dict, optional): Additional arguments to be included with data source create call to Veza. Defaults to None.

Raises:

• ValueError: Data source name contains invalid characters

Returns:

• dict: dictionary of new Data Source

method create_datasource

Deprecated Legacy function for backward-compatibility.

method create_provider

Create a new Provider.

Creates a new Provider with the given name. An error will be raised for naming conflicts.

Args:

• name (str): new Provider name

• custom_template (str): the OAA template to use for the Provider ("application" or "identity_provider")

• base64_icon (str, optional): Base64 encoded string of icon to set for Provider. Defaults to "".

• options: (dict, optional): Additional arguments to be included with provider create call to Veza. Defaults to None.

Raises:

• ValueError: Provider name contains invalid characters

Returns:

• dict: dictionary representing the created Provider

method create_query

Create a new Assessment Query

For details on how to define an Assessment Query see the Veza docs.

Args:

• query (dict): Query definition

Returns:

• dict: API response including ID of created Query

method create_report

Create a new Report

For details on how to define a new Report see the Veza docs.

Args:

• report (dict): Report definition

Returns:

• dict: API response including ID of created Report

method delete_data_source

Delete an existing Data Source by ID.

Removes a Data Source and all entity data.

Args:

• data_source_id (str): ID of Data Source to delete

• provider_id (str): ID of Data Source Provider

Returns:

• dict: API response

method delete_provider

Delete an existing provider by ID.

Deleting a provider removes all datasources and historical data. Fully deleting the provider is a background operation that will complete after API response is returned.

Args:

• provider_id (str): ID of provider to delete

Returns:

• dict: API response

method delete_query

Delete an Assessment Query by ID

Args:

• id (str): UUID of Query to delete

• force (bool): Force deletion of query that may be part of a report. Defaults to False

Returns:

• dict: API response from delete

method delete_report

Delete Report by ID

Args:

• id (str): UUID of Report to delete

Returns:

• dict: API response

method get_data_source

Get Provider's Data Source by name.

Find a Data Source from a specific provider based on the name of the Data Source

Args:

• name (str): Data Source name

• provider_id (str): Provider unique ID

Returns:

• dict: Data Source as dict or None

method get_data_sources

Get Data Sources for Provider by ID.

Get the list of existing Data Sources, filtered by Provider UUID.

Args:

• provider_id (str): ID of Provider

Returns:

• list[dict]: List of Data Sources as dictionaries

method get_provider

Get Provider by name.

Args:

• name (str): name of Provider

Returns:

• dict: dictionary representing Provider or None

method get_provider_by_id

Get Provider by UUID identifier.

Args:

• provider_id (str): Unique global identifier for provider

Returns:

• dict: dictionary representation of Provider or None

method get_provider_list

Return list of Providers.

Returns:

• list[dict]: Returns a list of existing Providers as dictionaries

method get_queries

Get all saved Assessment Queries

Veza can filter out queries that include inactive entity types (e.g. Okta Users on a system without Okta configured). To only retrieve queries that include active entity types set include_inactive_queries to False.

Args:

• include_inactive_queries (bool): Set False to exclude inactive queries from result. Defaults to True.

Returns:

• list: List of assessment Queries as dictionaries

method get_query_by_id

Get Assessment Query by ID

Args:

• id (str): UUID identifier for Query

Returns:

• dict: Query definition

method get_report_by_id

Get Report by ID

Veza can filter out queries from reports that only contain entity types that are not configured (e.g. Okta Users on a system without Okta configured). To only return queries configured on the report that match entity types configured on the system set include_inactive_queries to False

Args:

• id (str): UUID of Report to get

• include_inactive_queries (bool): Set True to include inactive queries. Default True.

Returns:

• dict: Report definition

method get_reports

Get all Reports

Gets Reports created on the system. To get all reports include_inactive_reports and include_inactive_queries must be set to True.

Args:

• include_inactive_reports (bool, Optional): Set to True to include reports that contain no active providers, defaults to True.

• include_inactive_queries (bool, Optional): Set to True to include reports that contain only inactive queries, defaults to True.

Returns:

• list[dict]: List of Reports as dictionary objects

method push_application

Push an OAA Application Object (such as CustomApplication).

Extracts the OAA JSON payload from the supplied OAA class (e.g. CustomApplication, CustomIdPProvider, etc) and push to the supplied Data Source.

The Provider with provider_name must be a valid existing Provider or create_provider must be set to True. A new data source will be created automatically by default if it does not already exist.

For logging, and debugging, the optional save_json flag writes the payload to a local file (before push). Output file name is formatted with a timestamp: {data source name}-{%Y%m%d-%H%M%S}.json

Args:

• provider_name (str): Name of an existing Provider.

• data_source_name (str): Name for Data Source (will be created if it doesn't exist).

• application_object (Class): OAA object to extract the payload from

• save_json (bool, optional): Save the JSON payload to a local file before push. Defaults to False.

• create_provider (bool, optional): Create a new Provider if Provider does not already exists. Defaults to False.

• options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.

Raises:

• OAAClientError: If any API call returns an error (including errors processing the OAA payload).

Returns:

• dict: API response from push, including any warnings that are returned.

method push_metadata

Push an OAA payload dictionary to Veza.

Publishes the supplied metadata dictionary representing an OAA payload to the specified provider and data source. The function will create a new data source if it does not already exist, but requires the Provider be created ahead of time.

Args:

• provider_name (str): Name of existing Provider

• data_source_name (str): Name for Data Source, will be created if doesn't exist.

• metadata (dict): Dictionary of OAA payload to push.

• save_json (bool, optional): Save the OAA JSON payload to a local file before push. Defaults to False.

• options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.

Raises:

• OAAClientError: If any API call returns an error including errors processing the OAA payload.

Returns:

• dict: API response to the push request (including any warnings).

method update_provider_icon

Update an existing custom provider icon from base64 encoded string.

To load an icon from file, use utils.encode_icon_file to get the base64 encoding of the file first

Args:

• provider_id (str): unique ID of existing provider

• base64_icon (str): base64 encoded string of new icon

Raises:

• ValueError: If icon size exceeds maximum allowed size

method update_report

Update an existing report

Args:

• report_id (str): UUID of Report to updated

• report (dict): Updated Report definition

Returns:

• dict: API response

method update_user_agent

Updates the User-Agent string passed with all API calls

Generates a User-Agent with the oaaclient version, Python version and platform information.

The optional extra string will be appended if provided.

Args:

• extra (str, optional): Additional information to append to User-Agent string. Defaults to "".

class OAARetry

Super class for urllib3.util.retry

Super class to allow modifying the default max backoff time from 120 seconds to our own value

Args:

• Retry (type): description

method __init__

oaaclient utility functions.

Copyright 2022 Veza Technologies Inc.

Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

helper functions commonly used by OAA integrations

function log_arg_error

log_arg_error(log: object, arg: str = None, env: str = None) → None

Helper function for logging errors when loading parameters

Helper function used to create consistent messages in connectors when required parameters can be set at command line or as environment variables.

Message can include information on parameter and/or environment variable but must provide one.

Args:

• log (object): logging facility object to log to

• arg (str, optional): Command line option for parameter such as --veza-url. Defaults to None.

• env (str, optional): OS Environment variable for parameter such as VEZA_URL. Defaults to None.

Raises:

• Exception: if neither arg or env are supplied

function load_json_from_file

load_json_from_file(json_path: str) → dict

Load JSON from file

Args:

• json_path (str): path to JSON file on disk

Raises:

• Exception: Unable to process JSON

• Exception: Error reading JSON file

Returns:

• dict: JSON decoded to dictionary

function encode_icon_file

encode_icon_file(icon_path: str) → str

read an icon file to a base64 encoded string

Args:

• icon_path (str): Path to icon file on disk

Returns:

• str: base64 encoding of file

function exists_in_query_array

exists_in_query_array(value_to_find, input_array) → bool

function build_report

build_report(veza_con, report_definition: dict) → dict

Creates or updates a Veza report from a dictionary

Creates a report and containing queries from a dictionary definition. Function will create any queries it does not find based on name. If a query with the same name already exists the existing query will be added to the report.

If a report already exists with the same name any missing queries will be added to the report.

report_definition must be a dictionary with name for the report and queries list of Veza query definitions:

{"name": "My Report", "queries": [{..},{...}]}

Args:

• veza_con (OAAClient): OAAClient connection to make Veza API calls

• report_definition (dict): Report definition

Raises:

• ValueError: Missing name or queries key

Returns:

• dict: API response from Report creation or update

function truncate_string

truncate_string(source_str: str, length: int = 256) → str

Helper function to truncate strings

Helper function to truncate strings to conform to maximum length requirements for templates.

Returns a string that is the first N bytes of the source string

Args:

• source_str (str): Source string to truncate

• length (int, optional): Length to shorten to. Defaults to 256.

Returns:

• str: truncated string

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

Copyright 2022 Veza Technologies Inc.

Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

Global Variables

• PROPERTY_NAME_REGEX

function append_helper

append_helper(base, addition)

Helper function to simplify appending.

Handles multiple cases:

• base is None: starts a list

• addition is list: extends base with list

• addition is anything else: append element to list

Args:

• base (List or None): base list to append to, can be None

• addition (*): What to append to the list

Returns:

• list: will always return a list

function unique_strs

unique_strs(input: 'list') → list

Returns a list of unique strings from input list case insensitive

Returns the unique list of strings from input list in a case insensitive manner. For duplicate strings with different cast (e.g. "STRING" and "string") the case of the first occurrence is returned.

Args:

• input (list): list of strings

Returns:

• list: list of unique strings

class OAATemplateException

General exception used for violations of the template schema.

method __init__

__init__(message)

class OAAPermission

Canonical permissions used by Veza Authorization Framework.

Used to describe the raw data or metadata permissions granted by CustomPermission

class OAAIdentityType

Types of identities for permission mapping.

class Provider

Base class for CustomProvider.

method __init__

__init__(name, custom_template)

method serialize

serialize()

class Application

Base class for CustomApplication.

method __init__

__init__(name, application_type, description=None)

class CustomApplication

Class for modeling application authorization using the OAA Application template.

CustomApplication class consists of identities, resources and permissions and produces the OAA JSON payload for the custom application template.

Class uses dictionaries to track most entities that can be referenced after creation. Dictionaries keys are case insensitive of the entity identifier (name or id). This applies to local_users, local_groups, local_roles, idp_identities, resources and custom_permissions.

Args:

• name (str): Name of custom application

• application_type (str): Searchable property, can be unique or shared across multiple applications

• description (str, optional): Description for application. Defaults to None.

Attributes:

• application_type (str): Searchable application type

• custom_permissions (dict[OAAPermission]): Dictionary of class instances

• description (str): Description for application

• identity_to_permissions (dict): Mapping of authorizations for identities to resources

• idp_identities (dict[IdPIdentity]): Contains federated identities without a corresponding local account

• local_groups (dict[LocalGroup]): Contains application groups (collections of users)

• local_roles (dict[LocalRole]): Contains application roles (collections of permissions)

• local_users (dict[LocalUser]): Contains users local to the application and their properties

• name (str): Name of custom application

• properties (dict): key value pairs of property values, property keys must be defined as part of the property_definitions

• property_definitions (ApplicationPropertyDefinitions): Custom property names and types for the application

• resources (dict[CustomResource]): Contains data resources and subresources within the application

method __init__

__init__(name: 'str', application_type: 'str', description: 'str' = None) → None

method add_access

add_access(identity, identity_type, permission, resource=None)

Legacy method for backwards compatibility.

.. deprecated:

---



### <kbd>method</kbd> `add_access_cred`

```python
add_access_cred(unique_id: 'str', name: 'str') → AccessCred

Create an Access Credential

Access creds can be used to represent alternative access methods such as API keys or application integrations.

Access creds can be assigned roles and permissions similar to local users. Access credentials can exist independently for use cases such as administratively created integrations or can be assigned to a local user for use cases like personal access tokens.

Args:

• unique_id (str): unique identifier for access cred

• name (str): name for access cred

Raises:

• OAATemplateException: Access credential with unique ID already exists

Returns:

• AccessCred: New access cred

method add_custom_permission

add_custom_permission(
    name: 'str',
    permissions: 'List[OAAPermission]',
    apply_to_sub_resources: 'bool' = False,
    resource_types: 'List[str]' = None
) → CustomPermission

Create a new custom permission.

Creates a new CustomPermission object for the application that can be used to authorize identities to the application, resources/sub-resource or as part of a role.

Args:

• name (str): Name of the permission

• permissions (list[OAAPermission]): Canonical permissions the custom permission represents

• apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.

• resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.

Returns: CustomPermission

method add_idp_identity

add_idp_identity(name: 'str') → IdPIdentity

Create an IdP principal identity.

IdP users and groups can be authorized directly to applications and resources by associating custom application permissions and roles with an IdP identity's name or email.

Args:

• name (str): IdP unique identifier for user or group.

Returns: IdPIdentity

method add_local_group

add_local_group(
    name: 'str',
    identities: 'List[str]' = None,
    unique_id: 'str' = None
) → LocalGroup

Create a new local group.

Groups can be associated to resources via permissions or roles. All users in the local group are granted the group's authorization.

Local groups will be identified by name by default, if unique_id is provided it will be used as the identifier instead

Local groups can be referenced after creation using .local_groups dictionary attribute. Dictionary is case insensitive keyed by unique_id or name if not using unique_id.

Args:

• name (str): Display name for group

• identities (list): List of IdP identities to associate group with.

• unique_id (str, optional): Unique identifier for group for reference by ID

Returns: LocalGroup

method add_local_role

add_local_role(
    name: 'str',
    permissions: 'List[str]' = None,
    unique_id: 'str' = None
) → LocalRole

Create a new local role.

• A local role represents a collection of permissions.

• Identities (local user, group, idp user) can be assigned a role to the application or resource, granting the role's permissions.

• Local roles will be identified by name by default, if unique_id is provided it will be used as the identifier instead.

• Local roles can be referenced after creation if needed through .local_roles case insensitive dictionary attribute.

• When a permission that has resource_types is added to a role, it will only apply to resources with a matching resource_type

Args:

• name (str): Display name for role

• permissions (list): List of Custom Permission names to include in role. CustomPermission must be created separately.

• unique_id (str, optional): Unique identifier for role for reference by ID

Returns: LocalRole

method add_local_user

add_local_user(
    name: 'str',
    identities: 'List[str]' = None,
    groups: 'List[str]' = None,
    unique_id: 'str' = None
) → LocalUser

Create a new local user for application.

Local users can be assigned to groups and associated with resources via permissions or roles. Groups and identities can be provided at creation or added later. See Identity and LocalUser class for operations.

Local users will be identified by name by default, if unique_id is provided it will be used as the identifier instead.

Local users can be referenced after creation using the .local_users dictionary attribute. Dictionary is case insensitivekeyed by unique_id or name if not using unique_id.

Use unique_id when name is not guaranteed to be unique. All permission, group and role assignments will be referenced by unique_id.

Args:

• name (str): Display name for user

• identities (list): List of identities as strings (usually email) for local user. Used to map local user to discovered IdP identities.

• groups (list[LocalGroup]): List of group names (as string) to add user to

• unique_id (str, optional): Unique identifier for user for reference by ID

Returns: LocalUser

method add_resource

add_resource(
    name: 'str',
    resource_type: 'str',
    description: 'str' = None,
    unique_id: 'str' = None
) → CustomResource

Create a new resource under the application.

Resource type is used to group and filter application resources. It should be consistent for all common resources of an application.

Returns new resource object.

Resource is identified by name by default unless unique_id is provided. name must be unique if not using unique_id.

Resources can be referenced after creation using the .resources dictionary attribute. Dictionary is keyed by unique_id or name if not using unique_id. Use unique_id when name is not guaranteed to be unique.

Args:

• name (str): Name of resources

• resource_type (str): Type for resource

• description (str, optional): Description of resources. Defaults to None.

• unique_id (str, optional): Unique identifier for resource. defaults to None.

Returns: CustomResource

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a tag to the Application

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method app_dict

app_dict() → dict

Return the 'applications' section of the payload as serializable dictionary.

method define_custom_permission

define_custom_permission(
    custom_permission: 'CustomPermission'
) → CustomPermission

Add a custom permission to the application.

.. deprecated: ``` See CustomApplication.add_custom_permission()

**Args:**

 - <b>`custom_permission`</b> (CustomPermission):  CustomPermission class



**Raises:**

 - <b>`Exception`</b>:  Duplicate Keys



**Returns:**

 - <b>`CustomPermission`</b>:  The defined custom Permission

---


### <kbd>method</kbd> `get_identity_to_permissions`

```python
get_identity_to_permissions() → list

Collect authorizations for all identities into a single list.

method get_payload

get_payload() → dict

Get the OAA payload.

Returns the complete OAA template payload for application as serializable dictionary

Returns:

• dict: OAA payload as dictionary

method permissions_dict

permissions_dict() → dict

Return the 'permissions' section of the payload as serializable dictionary.

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set a custom property value for the application.

Property name must be defined for CustomApplication before calling set_property. See example below and ApplicationPropertyDefinitions.define_application_property for more information on defining properties.

Args:

• property_name (str): Name of property to set value for, property names must be defined as part of the application property_definitions

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property name is not defined

Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_application_property(name="my_property", property_type=OAAPropertyType.STRING) >>> app.set_property("my_property", "property value")

class CustomResource

Class for resources and sub-resources.

Should be used for representing components of the application to which authorization is granted. Each resource has a name and a type. The type can be used for grouping and filtering.

Arguments:

• name (str): display name for resource, must be unique to parent application or resource unless using unique_id

• resource_type (str): type for resource

• description (str): description for resource

• application_name (str): name of parent application

• resource_key (str, optional): for sub-resources the full unique identifier required for identity_to_permissions section. Defaults to name or unique_id if not provided.

• property_definitions (ApplicationPropertyDefinitions, optional): Property definitions structure for the resource

• unique_id (str, optional): Optional unique identifier for the resource. Defaults to None.

Attributes:

• name (str): display name for resource, must be unique to parent application or resource

• unique_id (str): resource's unique identifier if provided.

• resource_type (str): type for resource

• application_name (str): name of parent application

• resource_key (str): for sub-resources represents the sub-resource's parent path

• sub_resources (dict): dictionary of sub-resources keyed by name

• properties (dict): dictionary of properties set for resource

• tags (list[Tag]): list of tags

method __init__

__init__(
    name: 'str',
    resource_type: 'str',
    description: 'str',
    application_name: 'str',
    resource_key: 'str' = None,
    property_definitions: 'ApplicationPropertyDefinitions' = None,
    unique_id: 'str' = None
) → None

method add_access

add_access(identity, identity_type, permission)

No longer supported, access should be added through identity (local_user, local_group, idp)

method add_resource_connection

add_resource_connection(id: 'str', node_type: 'str') → None

Add an external connection to the resource.

Used to add a relationship to another entity discovered by Veza such as a service account or AWS IAM role.

Args:

• id (str): Unique identifier for connection entity

• node_type (str): Veza type for connecting node

method add_sub_resource

add_sub_resource(
    name: 'str',
    resource_type: 'str',
    description: 'str' = None,
    unique_id: 'str' = None
) → CustomResource

Create a new sub-resource under current resource

Args:

• name (str): display name for resource

• resource_type (str): type for resource

• description (str, optional): String description. Defaults to None.

• unique_id (str, optional): Unique identifier for new subresource, Defaults to name.

Returns: CustomResource

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to resource.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set the value for a custom property on a resource or sub-resource.

Property name must be defined for resource type before calling set_property(). See example below and ApplicationPropertyDefinitions.define_resource_property for more information on defining properties.

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property_name is not defined

Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_resource_property(resource_type="cog", name="my_property", property_type=OAAPropertyType.STRING) >>> cog1 = app.add_resource(name="cog1", resource_type="cog") >>> cog1.set_property("my_property", "this value")

method to_dict

to_dict() → dict

Return the dictionary representation of resource.

class Identity

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

Args:

• name (str): name of identity

• identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)

• unique_id (str, optional): ID of entity for reference by ID

Attributes:

• name (str): name of identity

• identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)

• application_permissions (list[CustomPermission]): List of permissions identity has directly to custom application

• resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

• application_roles (LocalRole): List of roles identity has directly to custom application

• resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

• properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

• tags (list[Tag]): List of tags

method __init__

__init__(
    name: 'str',
    identity_type: 'OAAIdentityType',
    unique_id: 'str' = None,
    property_definitions: 'ApplicationPropertyDefinitions' = None
) → None

method add_permission

add_permission(
    permission: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'bool' = False
) → None

Add a permission to an identity.

Permission can apply to either the application or application resource/sub-resources

Args:

• permissions ([str]): List of strings representing the permission names

• resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

• apply_to_application (bool): Apply permission to application when True, defaults to False

method add_role

add_role(
    role: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'Optional[bool]' = None,
    assignment_properties: 'Optional[dict]' = None
) → None

Add a role to an identity.

Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

Args:

• role (str): Name of role as string

• resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

• apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any

• assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to identity.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method get_identity_to_permissions

get_identity_to_permissions(application_name: 'str') → dict

Get a JSON serializable dictionary of all the identity's permissions and roles.

Formats the identity's permissions and roles for the Custom Application template payload

Returns:

• dict: JSON serializable dictionary of all the identity's permissions and roles

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set a custom defined property to a specific value on an identity.

Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property with property_name is not defined.

Example:

app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")

class LocalUserType

Enum for

class LocalUser

LocalUser identity, derived from Identity base class.

Used to model an application user. Can be associated with an external IdP user, or represent a local account.

Args:

• name (str): name of identity

• identities (list): list of strings for IdP identity association

• groups (list[LocalGroup]): list of group names as strings to add user too

• unique_id (string, optional): For reference by ID

Attributes:

• name (str): name of identity

• id (str): ID of entity for ID based reference

• email (string): Users email address

• identities (list): list of strings for IdP identity association

• groups (list[LocalGroup]): list of group names as strings to add user too

• identity_type (OAAIdentityType): Veza Identity Type (local_user)

• application_permissions (list[CustomPermission]): Permissions identity has directly to custom application

• resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

• application_roles (list[LocalRole]): Custom application roles assigned directly to the identity

• resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

• properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

• tags (list[Tag]): List of tags

• is_active (bool): Defaults to None for unset

• created_at (str): RFC3339 time stamp for user creation

• last_login_at (str): RFC3339 time stamp for last login

• deactivated_at (str): RFC3339 for user deactivate time

• password_last_changed_at (str): RFC3339 time stamp for last password change

• user_type (LocalUserType): Set the local user account type

method __init__

__init__(
    name: 'str',
    identities: 'List[str]' = None,
    groups: 'List[str]' = None,
    unique_id: 'str' = None,
    property_definitions: 'ApplicationPropertyDefinitions' = None
) → None

method add_access_cred

add_access_cred(access_cred: 'str') → None

Add access cred to user (access cred must be created separately)

Args:

• access_cred (str): unique identifier of access cred

method add_group

add_group(group: 'str') → None

Add user to local group (group must be created separately).

Args:

• group (str): identifier of local group

method add_identities

add_identities(identities: 'List[str]') → None

Add multiple identities to a local user from a list.

Args:

• identities (list[str]): list of identities to add to user

method add_identity

add_identity(identity: 'str') → None

Add an identity to user.

Identity should match the email address or another principal identifier for an IdP user (Okta, Azure, ect). Veza will create a connection from the application local user to IdP identity.

Args:

• identity (str): email or identifier for IdP user

method add_permission

add_permission(
    permission: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'bool' = False
) → None

Add a permission to an identity.

Permission can apply to either the application or application resource/sub-resources

Args:

• permissions ([str]): List of strings representing the permission names

• resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

• apply_to_application (bool): Apply permission to application when True, defaults to False

method add_role

add_role(
    role: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'Optional[bool]' = None,
    assignment_properties: 'Optional[dict]' = None
) → None

Add a role to an identity.

Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

Args:

• role (str): Name of role as string

• resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

• apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any

• assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to identity.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method get_identity_to_permissions

get_identity_to_permissions(application_name: 'str') → dict

Get a JSON serializable dictionary of all the identity's permissions and roles.

Formats the identity's permissions and roles for the Custom Application template payload

Returns:

• dict: JSON serializable dictionary of all the identity's permissions and roles

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set a custom defined property to a specific value on an identity.

Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property with property_name is not defined.

Example:

app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")

method to_dict

to_dict() → dict

Output user to dictionary for payload.

class LocalGroup

LocalGroup identity.

Derived from Identity base class. Used to represent groups of local users for application.

Args:

• name (str): name of group

• identities (list): list of strings for IdP identity association

• unique_id (string, optional): Unique identifier for group

Attributes:

• name (str): name of identity

• identities (list): list of strings for IdP identity association

• groups (list[LocalGroup]): list of group names as strings that group is member of for nested groups

• identity_type (OAAIdentityType): Veza Identity Type, local_group

• application_permissions (list[CustomPermission]): permissions identity has directly to custom application

• resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

• application_roles (list[LocalRole]): list of roles identity has directly to custom application

• resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

• properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

• tags (list[Tag]): List of tags

• created_at (str): RFC3339 time stamp for group creation time

method __init__

__init__(
    name,
    identities=None,
    unique_id: 'str' = None,
    property_definitions: 'ApplicationPropertyDefinitions' = None
)

method add_group

add_group(group: 'str') → None

Add a nested group to local group (group must be created separately).

Args:

• group (str): identifier of local group

method add_identity

add_identity(identity: 'str') → None

Add an identity to group.

The email address or another valid identifier should match that of an IdP principal (Okta, Azure, ect). Veza will create a connection from the application local group to IdP identity.

Args:

• identity (str): primary IdP identifier for group to associate

method add_permission

add_permission(
    permission: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'bool' = False
) → None

Add a permission to an identity.

Permission can apply to either the application or application resource/sub-resources

Args:

• permissions ([str]): List of strings representing the permission names

• resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

• apply_to_application (bool): Apply permission to application when True, defaults to False

method add_role

add_role(
    role: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'Optional[bool]' = None,
    assignment_properties: 'Optional[dict]' = None
) → None

Add a role to an identity.

Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

Args:

• role (str): Name of role as string

• resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

• apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any

• assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to identity.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method get_identity_to_permissions

get_identity_to_permissions(application_name: 'str') → dict

Get a JSON serializable dictionary of all the identity's permissions and roles.

Formats the identity's permissions and roles for the Custom Application template payload

Returns:

• dict: JSON serializable dictionary of all the identity's permissions and roles

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set a custom defined property to a specific value on an identity.

Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property with property_name is not defined.

Example:

app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")

method to_dict

to_dict() → dict

Output group to dictionary for payload.

class IdPIdentity

IdP identity derived from Identity base class.

Used to associate IdP identities (users or groups) directly to resource where concept of local users/groups doesn't apply to application.

Args:

• name (str): Primary IdP identifier for identity (email, group name, etc)

Attributes:

• name (str): name of identity

• identity_type (OAAIdentityType): Veza Identity Type, (idp)

• application_permissions (list[CustomPermission]): permissions identity has directly to custom application

• resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

• application_roles (list[LocalRole]): roles identity has directly to custom application

• resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

• properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

• tags (list[Tag]): List of tags

method __init__

__init__(name: 'str') → None

method add_permission

add_permission(
    permission: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'bool' = False
) → None

Add a permission to an identity.

Permission can apply to either the application or application resource/sub-resources

Args:

• permissions ([str]): List of strings representing the permission names

• resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

• apply_to_application (bool): Apply permission to application when True, defaults to False

method add_role

add_role(
    role: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'Optional[bool]' = None,
    assignment_properties: 'Optional[dict]' = None
) → None

Add a role to an identity.

Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

Args:

• role (str): Name of role as string

• resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

• apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any

• assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to identity.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method get_identity_to_permissions

get_identity_to_permissions(application_name: 'str') → dict

Get a JSON serializable dictionary of all the identity's permissions and roles.

Formats the identity's permissions and roles for the Custom Application template payload

Returns:

• dict: JSON serializable dictionary of all the identity's permissions and roles

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set custom IdP property (no functionality).

IdP identities do not support custom properties since the identity is discovered through the provider (Okta, Azure, etc)

class AccessCred

Access Credential derived from Identity base class.

Access Creds can be used to represent non-user based methods that grant access such as API keys or integrations.

AccessCreds can be assigned roles or permissions to an application or resource. An AccessCred can stand-alone or be associated to a local user.

Args:

• unique_id (str): Unique identifier for access cred

• name (str): Name for access cred, does not need to be unique

Attributes:

• unique_id (str): Unique identifier for access cred

• name (str): Name for access cred, does not need to be unique

• is_active (bool): Indicate if credential is active, defaults to True

• created_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty

• expires_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty

• last_used_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty

• can_expire (bool): Boolean to indicate if credential type can exipre, defaults to unset

method __init__

__init__(
    unique_id: 'str',
    name: 'str',
    property_definitions: 'ApplicationPropertyDefinitions' = None
) → None

method add_permission

add_permission(
    permission: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'bool' = False
) → None

Add a permission to an identity.

Permission can apply to either the application or application resource/sub-resources

Args:

• permissions ([str]): List of strings representing the permission names

• resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

• apply_to_application (bool): Apply permission to application when True, defaults to False

method add_role

add_role(
    role: 'str',
    resources: 'List[CustomResource]' = None,
    apply_to_application: 'Optional[bool]' = None,
    assignment_properties: 'Optional[dict]' = None
) → None

Add a role to an identity.

Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

Args:

• role (str): Name of role as string

• resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

• apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any

• assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to identity.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method get_identity_to_permissions

get_identity_to_permissions(application_name: 'str') → dict

Get a JSON serializable dictionary of all the identity's permissions and roles.

Formats the identity's permissions and roles for the Custom Application template payload

Returns:

• dict: JSON serializable dictionary of all the identity's permissions and roles

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set a custom defined property to a specific value on an access credential.

Property name must be defined for access credentials before calling set_property(). See example below and ApplicationPropertyDefinitions.define_access_cred_property for more information on defining properties.

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property with property_name is not defined.

Example:

app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_access_cred_property(name="my_property", property_type=OAAPropertyType.STRING) >>> cred1 = app.add_access_cred(unique_id="cred001", name="Cred 001") >>> cred1.set_property("my_property", "value for cred001")

method to_dict

to_dict() → dict

Output Access credential dictionary for payload

class LocalRole

Represent a Custom Application Local Role.

Local Roles are a collection of permissions (as CustomPermission). Roles can be used to associate a local user, group or IdP identity to an application, resource or sub-resource.

Permissions can either be assigned at creation and/or added later.

If the CustomPermission definition includes resource types in the resource_types list, the permission will only be assigned to resources/sub-resources that match that type as part of an assignment.

Args:

• name (str): name of local role

• permissions (list[CustomPermission], optional): List of custom permission names (strings) to associate with the role. Defaults to empty list.

• unique_id (string, optional): Unique identifier for role for identification by ID

Attributes:

• name (str): name of local role

• unique_id (str): Unique identifier for role for identification by ID

• permissions (list[CustomPermission]): list of custom permission names (strings) to associate with the role

• roles (list[LocalRole]): list of roles nested inside the role

• tags (list[Tag]): list of Tags instances

method __init__

__init__(
    name: 'str',
    permissions: 'List[str]' = None,
    unique_id: 'str' = None,
    property_definitions: 'ApplicationPropertyDefinitions' = None
) → None

method add_permissions

add_permissions(permissions: 'List[str]') → None

Add a permission to the role.

Args:

• permissions (list): List of permission names (strings) to add to role

method add_role

add_role(role: 'str') → None

Add a nested sub-role to the role (nested role must be created separately)

Args:

• role (str): identifier of the local role to nest inside this role

method add_tag

add_tag(key: 'str', value: 'str' = '') → None

Add a new tag to role.

Args:

• key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

• value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".

method set_property

set_property(
    property_name: 'str',
    property_value: 'any',
    ignore_none: 'bool' = False
) → None

Set the value for custom property on a local role.

Property name must be defined for local roles before calling set_property(). See example below and ApplicationPropertyDefinitions.define_local_role_property for more information on defining properties.

Args:

• property_name (str): Name of property to set value for

• property_value (Any): Value for property, type should match OAAPropertyType for property definition

• ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

Raises:

• OAATemplateException: If property name is not defined.

Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_role_property(name="my_property", property_type=OAAPropertyType.STRING) >>> role1 = app.add_local_role(name="role1") >>> role1.set_property(property_name="my_property", property_value="role1s value")

method to_dict

to_dict() → dict

Convert role to dictionary for inclusion in JSON payload.

Returns:

• dict: serializable dictionary of role

class CustomPermission

CustomPermission class for defining CustomApplication permissions.

• Custom permissions represent the named permissions for the application in its terms (e.g. "Admin" or "PUSH") and define the Veza canonical mapping (e.g. DataRead, MetadataRead, DataWrite).

• A permission can either be applied directly to an application or resource or assigned as part of a role.

• Optionally, when permissions are used as part of a role, if the resource_types list is populated the permission will only be applied to resources who's type is in the resource_types list when the role is applied to a resource.

Args:

• name (str): Display name for permission

• permissions (list): List of OAAPermission enums that represent the canonical permissions

• apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.

• resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.

Attributes:

• name (str): Display name for permission

• permissions (list[OAAPermission]): List of OAAPermission enums that represent the canonical permissions

• apply_to_sub_resources (bool): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource.

• resource_types (list): List of resource types as strings that the permission relates to.

method __init__

__init__(
    name: 'str',
    permissions: 'List[OAAPermission]',
    apply_to_sub_resources: 'bool' = False,
    resource_types: 'list' = None
) → None

method add_resource_type

add_resource_type(resource_type: 'str') → None

Add a resource type to the resource_types list.

Extends the list of resource types permission applies to when used in role assignment.

Args:

• resource_type (str): The resource type string value

method to_dict

to_dict() → dict

Returns dictionary representation for payload.

class OAAPropertyType

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

class ApplicationPropertyDefinitions

Model for defining custom properties for application and its entities (users, groups, roles, resources).

Property definitions define the names for additional entity properties and the expected type.

Args:

• application_type (str): type of custom application property definitions apply to

Attributes:

• application_properties (dict): property definitions for application

• local_user_properties (dict): property definitions for local users

• local_group_properties (dict): property definitions for local groups

• local_role_properties (dict): property definitions for local roles

• resources (dict): property definitions for resources keyed by resource type

method __init__

__init__(application_type: 'str') → None

method define_access_cred_property

define_access_cred_property(
    name: 'str',
    property_type: 'OAAPropertyType'
) → None

Define an access cred property.

Args:

• name (str): name for property

• property_type (OAAPropertyType): type for property

method define_application_property

define_application_property(
    name: 'str',
    property_type: 'OAAPropertyType'
) → None

Define an application property.

Args:

• name (str): name for property

• property_type (OAAPropertyType): type for property

method define_local_group_property

define_local_group_property(
    name: 'str',
    property_type: 'OAAPropertyType'
) → None

Define a local group property.

Args:

• name (str): name for property

• property_type (OAAPropertyType): type for property

method define_local_role_property

define_local_role_property(name: 'str', property_type: 'OAAPropertyType') → None

Define a local role property.

Args:

• name (str): name for property

• property_type (OAAPropertyType): type for property

method define_local_user_property

define_local_user_property(name: 'str', property_type: 'OAAPropertyType') → None

Define a local user property.

Args:

• name (str): name for property

• property_type (OAAPropertyType): type for property

method define_resource_property

define_resource_property(
    resource_type: 'str',
    name: 'str',
    property_type: 'OAAPropertyType'
) → None

Define a property for a resource by type of resource.

Args:

• resource_type (str): type of resource property definition is for

• name (str): property name

• property_type (OAAPropertyType): type for property

method define_role_assignment_property

define_role_assignment_property(
    name: 'str',
    property_type: 'OAAPropertyType'
) → None

method to_dict

to_dict() → dict

Return property definitions as dictionary ready for OAA payload

method validate_name

validate_name(name: 'str') → None

Check property name for valid characters

Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

Args:

• name (str): name of property to validate

Raises:

• OAATemplateException: Name is not a string

• OAATemplateException: Name contains invalid characters or does not start with a letter

method validate_property_name

validate_property_name(
    property_name: 'str',
    entity_type: 'str',
    resource_type: 'str' = None
) → bool

Validate that a property name has been defined for given resource type.

Args:

• property_name (str): name of property to validate

• entity_type (str): type of entity custom property is for (application, local_user, local_group, local_role, resource)

• resource_type (str): (optional) type for validating resource property names, only applicable to entity_type resource

Raises:

• OAATemplateException: If property name has not been previously defined for entity

class IdPEntityType

IdP entity types.

class IdPProviderType

Veza supported IdP provider types.

class CustomIdPProvider

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

CustomIdPProvider class consists of IdP domain information, user, group and external associations for identities like AWS Roles.

Classes uses dictionaries to track most components, dictionaries are all keyed by string of the entity name

Args:

• name (str): Name of IdP

• idp_type (str): Type descriptor for IdP, can be unique or share across multiple IdP e.g. ldap, IPA

• domain (str): IdP domain name

• description (str, optional): Description for IdP. Defaults to None.

Attributes:

• name (str): Name of custom IdP

• idp_type (str): Type for IdP

• description (str): Description for IdP

• domain (CustomIdPDomain): Domain model, created with domain name at init

• users (dict[CustomIdPUser]): Dictionary of CustomIdPUser class instances

• groups (dict[CustomIdPGroup]): Dictionary of CustomIdPGroup class instances

• property_definitions (IdPPropertyDefinitions): Custom Property definitions for IdP instance

method __init__

__init__(
    name: 'str',
    idp_type: 'str',
    domain: 'str',
    description: 'str' = None
) → None

method add_app

add_app(id: 'str', name: 'str') → CustomIdPApp

summary

Args:

• id (str): description

• name (str): description

Raises:

Returns:

• CustomIdPApp: description

method add_group

add_group(
    name: 'str',
    full_name: 'str' = None,
    identity: 'str' = None
) → CustomIdPGroup

Add group to IdP.

Arguments:

• name (str): primary ID for group

• full_name (str): optional display name for group

• identity (str): optional unique identifier for group, if None name is used as identity

method add_user

add_user(
    name: 'str',
    full_name: 'str' = None,
    email: 'str' = None,
    identity: 'str' = None
) → CustomIdPUser

Add user to IdP

if no identity is set name will be used as identity

Arguments:

• name (str): primary ID for user

• full_name (str): optional full name for display

• email (str): optional email for user

• identity (str): optional unique identifier for user, if None name is used as identity

Returns: CustomIdPUser

method get_payload

get_payload() → dict

Return formatted payload as dictionary for JSON conversion and upload

class CustomIdPDomain

Domain model for Custom IdP provider.

Args:

• name (str): domain name

Attributes:

• name (str): domain name

method __init__