Package: oaaclient
Python SDK for Veza Open Authorization APITheoaaclientpackage provides data models, methods and a command-line interface for using theOpen Authorization API. You can use it to format and publish user, resource, and authorization metadata for processing by a Veza instance.For example usage, please see thesamplesdirectory. For more information on Veza visithttps://www.veza.com.What is OAA?The Open Authorization API is used to submit authorization metadata for custom applications to a Veza instance for parsing and inclusion in the Entity Catalog.A typical OAA-based integration will use APIs to query the source application for information about users, resources, and permissions, along with other authorization entities such as groups and roles.This data payload is published to Veza as a JSON object. Theoaaclientmodules simplify building the required JSON model and pushing the payload to Veza via the REST API.Any application or identity provider added using OAA becomes fully available for search, rules and alerts, and access reviews, similar to any officially-supported integration.Using the SDKTheoaaclientSDK 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 WorkflowCreate the Veza API connection and a new custom application:fromoaaclient.clientimportOAAClientfromoaaclient.templatesimportCustomApplication,OAAPermission# creates a connection class to communicate with Vezaveza_con=OAAClient(url=veza_url,token=veza_api_key)# creates a new Custom Application modelcustom_app=CustomApplication(name="Sample App",application_type="sample")Once theCustomApplicationclass is instantiated, you can use the public methods to populate the new app with local users, groups, resources, and permissions metadata:custom_app.add_custom_permission("owner",[OAAPermission.DataRead,OAAPermission.DataWrite])jane=custom_app.add_local_user("jane",identities="jane@example.com")resource1=custom_app.add_resource(name="Resource 1",resource_type="thing")jane.add_permission(permission="owner",resources=[resource1])Once all identities, permissions and resources are modeled, the client connection handles the final push to Veza:veza_con.push_application(provider,data_source_name,application_object=custom_app)For more examples see thesamples directory.Command Line UseThe oaaclient can also be used as a command line tool for pushing completed OAA payloads to Veza for testing and debugging, without needing to make the API requests "by hand."You will need the following JSON files:provider.json- must contain the provider name and template to use (applicationoridp).{"name":"ProviderName","custom_template":"application"}auth.json- defines the Veza host and API key to use{"host":"https://demo.vezacloud.com","token":"ZXlKaGJHY2lPaUpJ....."}payload.json- The complete OAA JSON body to submit. For full reference see the Veza documentation. This format must match the schema (template) selected inprovider.json.Once the above files are created, the payload can be pushed with the following command:oaaclient--providerprovider.json--authauth.jsonpayload.jsonThe client will read the files and push the payload to Veza. The client will automatically create any required custom provider and data sources.Handling ErrorsTheOAAClientclass handles API connections to Veza. If there are errors connecting or the API returns errorsOAAClientwill raise anOAAClientErrorexception. If the payload does not conform to the template requirements theOAAClientError.detailswill 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,)ifresponse.get("warnings"):print("Push succeeded with warnings:")forwinresponse["warnings"]:print(w)exceptOAAClientErrorase:print(f"Error:{e.error}:{e.message}({e.status_code})",file=sys.stderr)ifhasattr(e,"details"):fordine.details:print(d,file=sys.stderr)Additional documentationSince 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 andoaaclientmodules are thoroughly annotated, for reference when building your own integrations.For additional information on developing a custom OAA integration, please contact your Veza support team for access to theUser Guide.