LogoLogo
User GuideDeveloper DocumentationIntegrationsRelease Notes
  • 🏠Veza Documentation
  • ☑️Getting Started
  • 📖Veza Glossary
  • ❓Product FAQ
  • 🛡️Security FAQ
    • Advanced Security FAQ
  • Release Notes
    • 🗒️Release Notes
      • Release Notes: 2025-04-30
      • Release Notes: 2025-04-16
      • Release Notes: 2025-04-02
      • Release Notes: 2025-03-19
      • Archive
        • 2024.9.23
        • 2024.9.16
        • 2024.9.9
        • 2024.9.2
        • 2024.8.26
        • 2024.8.19
        • 2024.8.12
        • 2024.8.5
        • 2024.7.29
        • 2024.7.22
        • 2024.7.15
        • 2024.7.1
        • 2024.6.24
        • 2024.6.17
        • 2024.6.10
        • 2024.6.3
        • 2024.5.27
        • 2024.5.20
        • 2024.5.13
        • 2024.5.6
        • 2024.4.29
        • 2024.4.22
        • 2024.4.15
        • 2024.4.8
        • 2024.4.1
        • 2024.3.25
        • 2024.3.18
        • 2024.3.11
        • 2024.3.4
        • 2024.2.26
        • 2024.2.19
        • 2024.2.12
        • 2024.2.5
        • 2024.1.29
        • 2024.1.22
        • 2024.1.15
        • 2024.1.8
        • 2024.1.1
        • 2023.12.18
        • 2023.12.11
        • 2023.12.4
        • 2023.11.27
        • 2023.11.20
        • 2023.11.13
        • 2023.11.6
        • 2023.10.30
        • 2023.10.23
        • 2023.10.16
        • 2023.10.9
        • 2023.10.2
        • 2023.9.25
        • 2023.9.18
        • 2023.9.11
        • 2023.9.4
        • 2023.8.28
        • 2023.8.21
        • 2023.8.14
        • 2023.8.7
        • 2023.7.31
        • 2023.7.24
        • 2023.7.17
        • 2023.7.10
        • 2023.7.3
        • 2023.6.26
        • 2023.6.19
        • 2023.6.12
        • 2023.6.5
        • 2023.5.29
        • 2023.5.22
        • 2023.5.15
        • 2023.5.8
        • 2023.5.1
        • 2023.4.24
        • 2023.4.17
        • 2023.4.10
        • 2023.4.3
        • 2023.3.27
        • 2023.3.20
        • 2023.3.13
        • 2023.3.6
        • 2023.2.27
        • 2023.2.20
        • 2023.2.13
        • 2023.2.6
        • 2023.1.30
        • 2023.1.23
        • 2023.1.16
        • 2023.1.9
        • 2023.1.2
        • 2022.12.12
        • 2022.12.5
        • 2022.11.28
        • 2022.11.14
        • 2022.11.7
        • 2022.10.31
        • 2022.10.24
        • 2022.10.17
        • 2022.10.1
        • 2022.6.2
        • 2022.6.1
        • 2022.5.1
        • 2022.4.1
        • 2022.3.1
  • Features
    • 🔎Access Visibility
      • Graph
      • Query Builder
      • Saved Queries
      • Filters
      • Query Mode
      • Intermediate Entities
      • Regular Expressions
      • Tags
      • Tagged Entity Search
      • Assumed AWS IAM Roles
      • Veza Query Language
        • Quick Start
        • Syntax
        • VQL API
    • 💡Access Intelligence
      • Overview
      • Dashboards
        • Reports
        • Scheduled Exports of Query Results via a Secure Email Link
      • Risks
      • Analyze
      • Compare
      • Rules and Alerts
      • Entities
      • NHI Identify Classification Logic
      • NHI Secrets
    • 🔏Access Reviews
      • Get Started: Access Reviewers
      • Get Started: Review Operators
      • Access Review Tasks
        • Assign Reviewers
        • Create a Configuration
        • Create a Review
        • Draft Reviews
        • Edit a Configuration
        • Filters and Bulk Actions
        • Manage Access Reviews
        • Using the Reviewer Interface
        • Row Grouping for Access Reviews
        • Schedule an Access Review
      • Access Review Configuration
        • Access Reviews Query Builder
        • Access Reviews Global Settings
        • Configuring a Global Identity Provider
          • Alternate Manager Lookup
        • Customizing Default Columns
        • Email Notifications and Reminders
        • Identity Provider and HRIS Enrichment
        • Managers and Resource Owners
        • Multi-Level Review
        • 1-Step Access Reviews
        • On-Demand Reviews
        • Veza Actions for Access Reviews
        • Review Intelligence Policies
        • Review Presentation Options
        • Reviewer Selection Methods
        • Reviewer Digest Notifications
      • Access Review Scenarios
        • Access Reviews: Active Directory Security Groups
        • Access Reviews: Okta App Assignments
        • Access Reviews: Okta Group Membership
        • Access Reviews: Okta Admin Roles
        • Access Reviews: Azure AD Roles
        • Access Reviews with Saved Queries
        • Source-Only Access Reviews
    • 📊Access Monitoring
    • 🔄Lifecycle Management
      • Implementation and Core Concepts
      • Access Profiles
      • Policies
      • Conditions and Actions
      • Attribute Sync and Transformers
        • Lookup Tables
      • Integrations
        • Active Directory
        • Exchange Server
        • Okta
        • Salesforce
        • Workday
    • ⚖️Separation of Duties (SoD)
      • Managing SoD Risks with Veza
      • Creating SoD Detection Queries
      • Analyzing Separation of Duties Query Results
      • Example Separation of Duties Queries
      • SoD Manager Assignment
      • Access Reviews for SoD
  • Integrations
    • ✨Veza Integrations
      • Adobe Enterprise
      • Amazon Web Services
        • Add Existing AWS Accounts
        • Automatically Add New AWS Accounts
        • AWS DynamoDB
        • AWS KMS
        • AWS RDS MySQL
        • AWS RDS PostgreSQL
        • AWS Redshift
        • Activity Monitoring for AWS
        • Using AWS Secrets Manager for RDS Extraction
        • Notes & Supported Entities
      • Anaplan
      • Atlassian Cloud Products
      • Auth0
      • BambooHR
      • Bitbucket Data Center
      • BlackLine
      • Beeline
      • Boomi
      • Box
      • Bullhorn
      • Cassandra
      • Cisco Duo
      • Clickhouse
      • Concur
      • Confluence Server
      • Confluent
      • Coupa
      • Coupa Contingent Workforce
      • Crowdstrike Falcon
      • CSV Upload
        • CSV Upload Examples
        • CSV Upload Troubleshooting
        • CSV Upload API
      • Databricks (Single Workspace)
      • Databricks (Unity Catalog)
      • Delinea Secret Server
      • Device42
      • DocuSign
      • Dropbox
      • Egnyte
      • Expensify
      • Exchange Online (Microsoft 365)
      • Fastly
      • Google Cloud
        • Check Google Cloud Permissions
        • Notes & Supported Entities
      • Google Drive
      • GitHub
      • GitLab
      • HashiCorp Vault
      • HiBob
      • Hubspot
      • IBM Aspera
      • iManage
      • Ivanti Neurons
      • Jamf Pro
      • Jenkins
      • JFrog Artifactory
      • Jira Data Center
      • Kubernetes
      • LastPass
      • Looker
      • MongoDB
      • Microsoft Active Directory
      • Microsoft Azure
        • Azure SQL Database
        • Azure PostgreSQL Database
        • Microsoft Dynamics 365 CRM
        • Microsoft Dynamics 365 ERP
        • Notes & Supported Entities
      • Microsoft Azure AD
      • Microsoft SharePoint Online
      • Microsoft SharePoint Server
      • Microsoft SQL Server
      • MuleSoft
      • MySQL
      • NetSuite
      • New Relic
      • Okta
        • Okta MFA status
      • OneLogin
      • OpenAI
      • Oracle Cloud Infrastructure
      • Oracle Database
      • Oracle Database (AWS RDS)
      • Oracle E-Business Suite (EBS)
      • Oracle EPM
      • Oracle Fusion Cloud
      • Oracle JD Edwards EnterpriseOne
      • PagerDuty
      • Palo Alto Networks SASE/Prisma Access
      • PingOne
      • PostgreSQL
      • Power BI
      • Privacera
      • PTC Windchill
      • Qualys
      • QNXT
      • Ramp
      • Redis Cloud
      • Rollbar
      • Salesforce
      • Salesforce Commerce Cloud
      • SCIM integration
      • ServiceNow
      • Slack
      • Smartsheet
      • Snowflake
        • Snowflake Native Application
        • Snowflake Masking Policies
        • Exporting Saved Query Results to Snowflake
        • Audit Log Export
        • Event Export
      • Solarwinds
      • Spotio
      • Sumo Logic
      • Tableau Cloud
      • Teleport
      • Terraform
      • ThoughtSpot
      • Trello
      • Trino (PrestoSQL)
      • UKGPro
      • Veza
      • Windows Server
        • Enterprise Deployment
      • Workato
      • Workday
      • YouTrack
      • Zendesk
      • Zip
      • Zoom
      • Zscaler
      • 1Password
    • 🎯Integrations Overview
    • ⚠️Prerequisites and Connectivity
      • Insight Point
        • Deploying an Insight Point using the install script
        • Deploy with AWS EC2
        • Deploy with Virtual Appliance
          • Deploy with Virtual Appliance (Legacy)
        • Deploy with Azure Container Instances
        • Insight Point (Helm Chart)
      • Certificates with OpenSSL
    • ⚙️Configuring Integrations
      • Integrations FAQ
      • Extraction and Discovery Intervals
      • Custom Identity Mappings
      • Limiting Extractions
      • Enrichment Rules
      • ℹ️Running Veza Scripts with Python
  • Administration
    • 🛠️Veza Administration
      • Securing Your Veza Tenant
      • Veza Actions
        • Slack
        • ServiceNow
        • Jira
        • Webhooks
      • Virtual Private Veza
      • System Events
      • Sign-In Settings
        • Single Sign-On with Okta
        • Single Sign-On with Okta (OIDC)
        • Single Sign-On with Microsoft Entra
      • User Management
        • Multi-factor Authentication
        • Team Management
        • Support User Access
  • Developers
    • 🌐Veza APIs
      • Authentication
      • Troubleshooting
      • Pagination
      • Open Authorization API
        • Getting Started
        • Core Concepts
          • Connector Requirements
          • Using OAA Templates
          • Providers, Data Sources, Names and Types
          • Sourcing and Extracting Metadata
          • Naming and Identifying OAA Entities
          • Modeling Users, Permissions, and Roles
          • Custom Properties
          • Tagging with OAA
          • Cross Service IdP Connections
          • Incremental Updates
        • OAA Push API
          • OAA Operations
        • OAA Templates
          • Custom Application
          • Custom Identity Provider
          • Custom HRIS Provider
        • OAA .NET SDK
          • C# OAA Application Connector
        • OAA Python SDK
          • Application Outline
          • oaaclient modules
            • Client
            • Structures
            • Templates
            • Utils
        • Sample Apps
        • Example Connectors
      • Integration APIs
        • Enable/Disable Providers
        • Cloud Platforms and Data Providers
        • Identity Providers
        • Data Sources
        • Sync and Parse Status
      • Query APIs
        • Quick Start
        • Query Builder Terminology
        • Query Builder Parameters
        • Query Builder Results
        • List saved queries
        • Save a query
        • Get a saved query
        • Update a query
        • Delete a query
        • Get query node destinations
        • Get query nodes
        • Get query result
        • Get query spec node destinations
        • Get query spec nodes
        • Get query spec results
        • Private APIs
          • Get Access Relationship
          • Role Existence
          • Role Maintenance
          • Cohort Role Analysis
        • Tags
          • Create, Add, Remove Tag
          • Promoted Tags
      • Access Reviews APIs
        • Workflow Parameters Reference
        • List Workflows
        • List Certifications
        • List Certification Results
        • Update Certification Result
        • Force Update Result
        • Update Webhook Info
        • Get Certification Result
        • Manage Reviewer Deny List
        • Quick Filters
        • Help Page Templates
        • Smart Action Definitions
        • Delegate Reviewers
        • List Reviewer Infos
        • Get Access Graph
        • Automations API
        • Global Settings APIs
      • System Audit Logs
      • System Events
      • Notification Templates
        • Notification Templates API
      • Team and User Management APIs
        • Team API Keys
      • SCIM Provisioning
        • SCIM API Reference
        • SCIM Provisioning with Okta
  • Product Updates
    • 🆕Product Updates
      • Product Update: March'25
      • Product Update: February'25
      • UX Update - Integration Management
      • Product Update: January'25
      • Product Update: December'24
      • Product Update: November'24
      • Product Update: October'24
      • Product Update: September'24
      • Product Update: August'24
      • UX Update: Veza Integrations
      • Product Update: July'24
      • Product Update: June'24
      • Product Update: May'24
      • Product Update: April'24
      • UX Update - Enhanced Reviewer Experience for Veza Access Reviews
      • Product Update: March'24
      • Product Update: February'24
      • Design Update: February'24
      • UX Update - New Navigation Experience
      • UX Update - Access Review Dashboards
      • Building Veza’s Platform and Products
      • Veza Product Update - Jan'24
      • Veza Product Update - 2H 2023
      • Veza Product Update - December'23
      • Veza Product Update - November'23
      • Veza Product Update - October'23
      • Veza Product Update - September'23
      • Veza Product Update - August'23
      • Veza Product Update - July'23
      • Veza Product Update - June'23
      • Veza Product Update - May'23
      • Veza Product Update - April'23
      • Veza Product Update - March'23
      • Veza Product Update - Feb'23
      • Veza Product Update - Jan'23
Powered by GitBook
On this page
  • 1. Extracting metadata from the source application
  • 2. Generating a sample payload
  • 3. Creating and Updating Custom Providers and Data Sources
  • Using oaaclient
  • Notes
  • Troubleshooting

Was this helpful?

Export as PDF
  1. Developers
  2. Veza APIs
  3. Open Authorization API

Getting Started

Overview and first steps for building an Open Authorization API connector

PreviousOpen Authorization APINextCore Concepts

Last updated 6 months ago

Was this helpful?

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

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

  1. using an API, command line, or another method to collect the needed authorization-related data. Depending on the application, this could include data resources and sub-resources as well as local users, groups, roles, permissions, and correlation to federated identities or external IDs.

  2. describing the users, resources, and permissions, according to a standard JSON schema. The payload can describe any number of application resources and sub-resources, along with information about identities, groups, permissions, and relationships to other graph entities.

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

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

1. Extracting metadata from the source application

The process of retrieving user records, along with lists of resources, group and permissions information, will be unique to each technology and OAA connector. You may also need to consider how to adapt the application's implementation of roles, federated identities, and resource hierarchies to fit the .

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

Before building a connector, you should read the best practices for and , or see the current list of for real-world examples.

2. Generating a sample payload

Most programming languages offer ways to populate and manipulate a JSON schema. You can also use the Python SDK for prebuilt functions:

custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
jane = custom_app.add_local_user("jane", identities="jane@example.com")
resource1 = custom_app.add_resource(name="customers", resource_type="database")
jane.add_permission(permission="owner", resources=[customers])

Below is an example of a populated application template. It demonstrates the basic principles of modeling local user permissions on application resources. For more details on all the available entities and properties see the full reference.

Custom Application Payload
{
  "applications": [
    {
      "name": "Support Portal",
      "application_type": "support_portal",
      "description": "Our customer support portal",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "bob@example.com"
          ],
          "groups": [
            "admins"
          ],
          "is_active": true,
          "last_login_at": "2022-03-21T18:56:38Z"
        },
        {
          "name": "sue",
          "identities": [
            "sue@example.com"
          ]        }
      ],
      "local_groups": [
        {
          "name": "admins"
        }
      ]
    }
  ],
  "permissions": [
    {
      "name": "admin",
      "permission_type": [
        "DataWrite",
        "DataRead",
        "DataDelete",
        "MetadataWrite",
        "MetadataRead"
      ]
    },
    {
      "name": "login",
      "permission_type": [
        "DataRead",
        "MetadataRead"
      ]
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "bob",
      "identity_type": "local_user",
      "application_permissions": [
        {
          "application": "Support Portal",
          "permission": "login"

        }
      ]
    },
    {
      "identity": "sue",
      "identity_type": "local_user",
      "application_permissions": [
        {
          "application": "Support Portal",
          "permission": "login"

        }
      ]
    },
    {
      "identity": "admins",
      "identity_type": "local_group",
      "application_permissions": [
        {
          "application": "Support Portal",
          "permission": "admin"
        }
      ]
    }
  ]
}

Custom Properties

3. Creating and Updating Custom Providers and Data Sources

You will use the Veza REST API to create, delete, and update a custom data source under v1/providers/custom/{provider_id}/{datasource_id}. Before you can push an OAA payload, you will need to:

  • Add a custom Provider to represent the generic application provider (such as "GitHub"), and set the name and template (application or IdP).

  • Bind a custom Data Source to the new custom Provider (such as "GitHub Organization") to activate it in the data pipeline. The data source will be the destination for future pushes and updates, and should usually represent the top-level instance of the modeled application.

  • Push the payload to populate the Veza Access Graph with new entities and metadata for the custom data source.

Updates

To update the data, push a new payload to the original provider ID and data source ID. By default, Veza will overwrite any existing data. The previous state will be available in the graph history, based on Veza's snapshot retention schedule.

Using oaaclient

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

Notes

  • Typically, the provider should represent the provider name (such as "CustomSCM"). Any payload pushes will target the data source ("CustomSCMInstance") under the custom provider. The pushed payload can include many nested resources (such as multiple repositories). The template also supports resources with a variety of different types within a single application.

  • The data source and provider name are primarily for internal use. The application_type specified in the template is used when viewing and searching the custom app from the Veza UI.

Troubleshooting

Veza enforces strict validation of the json_data field containing the OAA payload. Three checks are performed:

  1. All required fields must be present.

  2. String fields must be valid UTF-8 strings, no larger than 256 characters.

Warnings

  • To validate an AzureAD or other type of user, go to the Authorization Graph, search for the node of interest, select Show Details, and confirm the principal name is correct.

  • To validate the identifier for a group, find the node for the group and verify the name is as expected.

{
  "warnings": [
    {
      "message": "Cannot find identity by names (values: unknown_user@veza.com)"
    }
  ]
}

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

Errors

  1. The field in which the error occurs

  2. The detailed reason for the error

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

You can also apply to entities within the payload.

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

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

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

See for additional documentation.

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

The maximum payload size is 100MB. If you need to compress the payload, you can enable the option when .

A successful response may include warnings for issues that didn't prevent the processing of OAA data but should still be investigated. When mapping identities to an , a warning will be raised if a matching IdP group name or user principal name can't be found.

For all Veza APIs, include an error code (in standard gRPC error, such as 3 for Invalid Argument) and a descriptive error message. The error message consists of two parts:

🌐
custom properties
Veza tags
incremental updates
REST API Operations
oaaclient.client
Client
command-line tool
external id
error messages
Python SDK
OAA template
sourcing metadata
naming conventions
Custom Application
Extract metadata from the source application
Generate a payload
Publish the payload
creating the OAA data source
community connectors