Custom Principal

Template for modeling a lightweight identity source with users, groups, and tenants

Use this template to model a source of identities (users, groups, and tenants) using the Open Authorization API. Principals represent identity sources that connect to other OAA template types on the same provider, enabling Veza to map users and groups to the applications and resources they access.

The Custom Principal template differs from the Custom Identity Provider in scope: a Principal is a lightweight identity source meant to feed users and groups into Custom Application or other templates on the same provider. Custom IdP models a full identity provider with domains and federated identity features.

The template has three primary entities:

• Tenant - the top-level container for the principal instance. Each submission has exactly one tenant.

• Users - the individual identities in the principal system. Users can belong to groups and have custom properties like is_active, email, and timestamps.

• Groups - collections of users. Groups support hierarchical nesting through parent group references.

A custom property definition can define additional properties for tenants, users, and groups.

To use the principal template, set custom_templates to a list that includes principal when creating the provider. Because a principal is almost always used alongside an application, include both templates:

curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'

Then create a data source for the principal on that provider, specifying the principal template:

curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
-H "authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
--data '{"name":"Principal Data Source","custom_template":"principal"}'

Sample Payloads

Custom Principal with Users and Groups

This example demonstrates a corporate directory with users assigned to groups, custom properties, and hierarchical group nesting.

{
  "custom_property_definition": {
    "tenant_properties": {
      "region": "STRING"
    },
    "user_properties": {
      "department": "STRING",
      "mfa_enabled": "BOOLEAN"
    },
    "group_properties": {
      "is_security_group": "BOOLEAN"
    }
  },
  "name": "Example Corp",
  "principal_type": "corporate_directory",
  "tenant": {
    "name": "Example Corp",
    "id": "tenant-001",
    "tenant_unique_id": "tenant-001",
    "tags": [
      {
        "key": "environment",
        "value": "production"
      }
    ],
    "custom_properties": {
      "region": "us-west-2"
    }
  },
  "users": [
    {
      "name": "Alice Johnson",
      "id": "alice01",
      "email": "[email protected]",
      "user_unique_id": "alice01",
      "display_name": "Alice Johnson",
      "is_active": true,
      "created_date": "2024-01-15T09:00:00.000Z",
      "last_login": "2025-02-20T14:30:00.000Z",
      "identities": [
        "[email protected]"
      ],
      "groups": [
        {
          "id": "grp-engineering"
        }
      ],
      "custom_properties": {
        "department": "Engineering",
        "mfa_enabled": true
      }
    },
    {
      "name": "Bob Smith",
      "id": "bob02",
      "email": "[email protected]",
      "user_unique_id": "bob02",
      "is_active": true,
      "identities": [
        "[email protected]"
      ],
      "groups": [
        {
          "id": "grp-engineering"
        },
        {
          "id": "grp-admins"
        }
      ],
      "custom_properties": {
        "department": "Engineering"
      }
    }
  ],
  "groups": [
    {
      "name": "Engineering",
      "id": "grp-engineering",
      "group_unique_id": "grp-engineering",
      "group_type": "Department",
      "identities": [
        "[email protected]"
      ],
      "custom_properties": {
        "is_security_group": false
      }
    },
    {
      "name": "Admins",
      "id": "grp-admins",
      "group_unique_id": "grp-admins",
      "group_type": "Security",
      "custom_properties": {
        "is_security_group": true
      }
    },
    {
      "name": "Platform Team",
      "id": "grp-platform",
      "group_unique_id": "grp-platform",
      "group_type": "Team",
      "parent_group": {
        "id": "grp-engineering"
      }
    }
  ]
}

Real-World Example: Atlassian Cloud Admin

Veza's Atlassian Cloud connector uses the Custom Principal template to model the organization-level identity directory in Atlassian Cloud. The principal feeds users and groups into the Jira Cloud and Confluence Cloud application connectors on the same provider, linking identities to the resources they access.

This approach separates identity management (who exists, what products they can access) from application-level authorization (what permissions they have in Jira projects or Confluence spaces). The principal captures the organization directory, while separate Custom Application submissions model Jira and Confluence.

Atlassian Cloud Admin Payload

This payload models an Atlassian Cloud organization with managed and external users, product-access groups, and custom properties tracking account metadata.

{
  "custom_property_definition": {
    "user_properties": {
      "account_type": "STRING",
      "account_status": "STRING",
      "access_billable": "BOOLEAN",
      "product_access": "STRING_LIST",
      "user_type": "STRING"
    },
    "group_properties": {
      "description": "STRING"
    }
  },
  "name": "Atlassian Cloud Admin",
  "principal_type": "Atlassian Cloud Admin",
  "tenant": {
    "name": "acme-corp",
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "tenant_unique_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  },
  "users": [
    {
      "name": "Jane Doe",
      "id": "5b10ac8d82e05b22cc7d4ef5",
      "email": "[email protected]",
      "user_unique_id": "5b10ac8d82e05b22cc7d4ef5",
      "is_active": true,
      "identities": [
        "[email protected]"
      ],
      "groups": [
        {
          "id": "jira-software-users"
        },
        {
          "id": "confluence-users"
        }
      ],
      "custom_properties": {
        "account_type": "atlassian",
        "account_status": "active",
        "access_billable": true,
        "product_access": ["jira-software", "confluence"],
        "user_type": "managed"
      }
    },
    {
      "name": "[email protected]",
      "id": "7c20bd9e93f16c33dd8e5fg6",
      "email": "[email protected]",
      "user_unique_id": "7c20bd9e93f16c33dd8e5fg6",
      "is_active": true,
      "identities": [
        "[email protected]"
      ],
      "groups": [
        {
          "id": "jira-software-users"
        }
      ],
      "custom_properties": {
        "account_type": "atlassian",
        "account_status": "active",
        "access_billable": true,
        "product_access": ["jira-software"],
        "user_type": "external"
      }
    }
  ],
  "groups": [
    {
      "name": "jira-software-users",
      "id": "jira-software-users",
      "group_unique_id": "jira-software-users",
      "group_type": "product-access",
      "custom_properties": {
        "description": "Users with access to Jira Software"
      }
    },
    {
      "name": "confluence-users",
      "id": "confluence-users",
      "group_unique_id": "confluence-users",
      "group_type": "product-access",
      "custom_properties": {
        "description": "Users with access to Confluence"
      }
    },
    {
      "name": "org-admins",
      "id": "org-admins",
      "group_unique_id": "org-admins",
      "group_type": "admin",
      "custom_properties": {
        "description": "Organization administrators"
      }
    }
  ]
}

Key patterns from this integration:

• user_type distinguishes managed users (in the organization's domain) from external collaborators, enabling access reviews to flag external access.

• product_access as a STRING_LIST tracks which Atlassian products each user can access (Jira, Confluence, Bitbucket), providing visibility into license usage.

• access_billable flags whether the user counts toward the organization's Atlassian license seat count.

• Groups map to product access rather than organizational structure — groups like jira-software-users and confluence-users reflect Atlassian's product-based access model.

• The principal connects to application templates on the same provider. Users and groups defined here appear as identities in Jira Cloud and Confluence Cloud Custom Application submissions, linking organization membership to application-level permissions.

Top-Level Payload

Field	Type	Description
name	string	Name of the principal provider instance
principal_type	string	Type descriptor for the principal provider (e.g., corporate_directory). Applied as a searchable property
custom_property_definition	object	Defines custom properties for tenants, users, and groups. See Custom Properties
tenant	object	The tenant object for this principal
users	array	Array of user objects
groups	array	Array of group objects
incremental_change	boolean	When true, enables incremental updates (optional)

Tenant

Each principal submission contains exactly one tenant, representing the top-level container for the identity source.

"tenant": {
  "name": "Example Corp",
  "id": "tenant-001",
  "tenant_unique_id": "tenant-001",
  "tags": [],
  "custom_properties": {}
}

Tenant Properties

Field	Type	Description
name	string	Display name for the tenant
id	string	Unique identifier for the tenant
tenant_unique_id	string	Optional unique identifier, typically a URL or external ID. Defaults to id if not provided
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	enum	For incremental updates, the operation to apply (optional)

Users

Users represent individual identities in the principal system. Each user can be linked to external identities and assigned to groups.

"users": [
  {
    "name": "Alice Johnson",
    "id": "alice01",
    "email": "[email protected]",
    "user_unique_id": "alice01",
    "display_name": "Alice Johnson",
    "is_active": true,
    "created_date": "2024-01-15T09:00:00.000Z",
    "last_login": "2025-02-20T14:30:00.000Z",
    "identities": ["[email protected]"],
    "groups": [{"id": "grp-engineering"}],
    "tags": [],
    "custom_properties": {}
  }
]

User Properties

Field	Type	Description
name	string	Display name for the user
id	string	Unique identifier for the user. Defaults to name if not provided
email	string	Email address for the user (optional)
user_unique_id	string	Optional unique identifier. Defaults to email if set, otherwise id
display_name	string	Display name shown in Veza (optional)
is_active	boolean	Whether the user account is active
created_date	string	Date the user was created, in RFC 3339 format (e.g., 2024-01-15T09:00:00.000Z)
deactivated_date	string	Date the user was deactivated, in RFC 3339 format (optional)
last_login	string	Date of the user's last login, in RFC 3339 format (optional)
identities	array	List of identity strings (e.g., email addresses) used for linking to external identity providers
groups	array	List of group references as {"id": "group_id"} objects
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	enum	For incremental updates, the operation to apply (optional)

Groups

Groups represent collections of users. Groups can have external identities and support hierarchical nesting through parent group references.

"groups": [
  {
    "name": "Engineering",
    "id": "grp-engineering",
    "group_unique_id": "grp-engineering",
    "group_type": "Department",
    "identities": ["[email protected]"],
    "tags": [],
    "custom_properties": {}
  },
  {
    "name": "Platform Team",
    "id": "grp-platform",
    "group_type": "Team",
    "parent_group": {
      "id": "grp-engineering"
    }
  }
]

Group Properties

Field	Type	Description
name	string	Display name for the group
id	string	Unique identifier for the group. Defaults to name if not provided
group_unique_id	string	Optional unique identifier for the group. Defaults to id if not provided
group_type	string	Type descriptor for the group (e.g., Security, Department, Team)
parent_group	object	Reference to a parent group as {"id": "parent_group_id"} for hierarchical nesting (optional)
identities	array	List of identity strings for linking to external identity providers
tags	array	Specify tags with a key and optional value
custom_properties	dictionary	Custom Properties validated against the custom_property_definition
operation	enum	For incremental updates, the operation to apply (optional)

Custom Property Definitions

Custom properties allow you to attach additional metadata to principal entities. Define properties in the custom_property_definition object, then set values on individual entities.

"custom_property_definition": {
  "tenant_properties": {
    "region": "STRING"
  },
  "user_properties": {
    "department": "STRING",
    "mfa_enabled": "BOOLEAN"
  },
  "group_properties": {
    "is_security_group": "BOOLEAN"
  }
}

Scope	Description
tenant_properties	Custom properties for the tenant entity
user_properties	Custom properties for user entities
group_properties	Custom properties for group entities

Property values must match their declared type. Supported types are described in Custom Properties.

Incremental Updates

After the initial metadata push (which must contain the full payload), you can modify, add, or remove the tenant, users, and groups without resubmitting other entities. An incremental update is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.

Creating and Updating a Custom Principal

To create the OAA provider and push data:

1. Create the provider with both the principal and application template types:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'

2. Create a data source on the provider, specifying the principal template:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data '{"name":"Principal Data Source","custom_template":"principal"}'

3. Push the payload to the data source:

   curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
   -H "authorization: Bearer {API_KEY}" \
   -H "Content-Type: application/json" \
   --data "{\"json_data\": $(jq -Rs . payload.json)}"

   The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.

Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.