Custom Application

Template for pushing custom data source entities and authorization

Overview

The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.

The template has three primary elements, covered in detail in this document:

• Applications - describes one or more application instances for the custom data source. An application may consist of any of the following entities:

  • Local Users - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as last_login_at) and can be linked to a source identity like Okta or AzureAD.

  • Local Groups - defines a group of users, permissions to the application or resources can be assigned to a group.

  • Local Roles - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.

  • Resources - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.

    • Sub Resources - resources can additionally have sub-resources for additional levels of depth.

• Permissions - define the applications specific permissions and map to Veza canonical permissions.

• Identity to Permissions - Assign local and federated users and groups to permissions or roles to the application and resources.

• Additionally, a custom property definition may describe user-configured key:pair values that can be applied to entities in the payload.

To use the generic app template, set the template type to application when creating a new data provider:

curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
-H "authorization: Bearer {API_KEY}" \
--compressed --data-binary '{"name":"DemoApp","custom_template":"application"}'

Sample Payload

Simple Custom Application

This example demonstrates using local users and groups to assign permissions directly to the application and resources.

{
  "custom_property_definition": {
    "applications": [
      {
        "application_type": "sample",
        "application_properties": {},
        "local_user_properties": {},
        "local_group_properties": {},
        "local_role_properties": {},
        "resources": []
      }
    ]
  },
  "applications": [
    {
      "name": "Sample App",
      "application_type": "sample",
      "description": "This is a sample app",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[e-mail]"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "id": "0000000001"
        },
        {
          "name": "jane",
          "identities": [
            "[e-mail]"
          ],
          "groups": [
            "admins"
          ],
          "created_at": "2021-08-13T06:28:13.250Z",
          "id": "0000000002"
        }
      ],
      "local_groups": [
        {
          "name": "admins"
        }
      ],
      "local_roles": [],
      "tags": [],
      "custom_properties": {},
      "resources": [
        {
          "id": "0001",
          "name": "Entity1",
          "resource_type": "thing",
          "description": "Some entity in the application",
          "sub_resources": [
            {
              "name": "Child 1",
              "resource_type": "child",
              "description": "My information about resource"
            }
          ]
        },
        {
          "id": "0002",
          "name": "Entity2",
          "resource_type": "thing",
          "description": "Another entity in the application"
        }
      ]
    }
  ],
  "permissions": [
    {
      "name": "admin",
      "permission_type": [
        "DataRead",
        "DataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "operator",
      "permission_type": [
        "DataRead",
        "MetadataRead"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "manager",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "application_permissions": [
        {
          "application": "Sample App",
          "permission": "operator",
          "apply_to_application": true
        },
        {
          "application": "Sample App",
          "resources": [
            "0001"
          ],
          "permission": "manager"
        }
      ]
    },
    {
      "identity": "admins",
      "identity_type": "local_group",
      "application_permissions": [
        {
          "application": "Sample App",
          "permission": "admin",
          "apply_to_application": true
        }
      ]
    }
  ]
}

Sample Application using Roles

{
  "applications": [
    {
      "name": "Sample App",
      "application_type": "sample",
      "description": "This is a sample app",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[e-mail]"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "id": "0000000001"
        },
        {
          "name": "jane",
          "identities": [
            "[e-mail]"
          ],
          "created_at": "2021-08-13T06:28:13.250Z",
          "id": "0000000002"
        }
      ],
      "local_groups": [],
      "local_roles": [
        {
          "name": "admin",
          "permissions": [
            "manage_users"
          ],
          "tags": [],
          "custom_properties": {}
        },
        {
          "name": "user",
          "permissions": [
            "view_tickets",
            "close_tickets"
          ],
          "tags": [],
          "custom_properties": {}
        }
      ],
      "tags": [],
      "custom_properties": {},
      "resources": []
    }
  ],
  "permissions": [
    {
      "name": "manage_users",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "view_tickets",
      "permission_type": [
        "DataRead"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    },
    {
      "name": "close_tickets",
      "permission_type": [
        "MetadataWrite"
      ],
      "apply_to_sub_resources": false,
      "resource_types": []
    }
  ],
  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        }
      ]
    },
    {
      "identity": "0000000002",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        },
        {
          "application": "Sample App",
          "role": "admin",
          "apply_to_application": true,
          "resources": []
        }
      ]
    }
  ]
}

Custom Properties and Tags

Custom properties and Veza Tags can be applied to most objects in the OAA payload: the application and its local_users, local_groups, local_roles and resources/sub_resources.

Define custom properties

  "custom_property_definition": {
    "applications": [
      {
        "application_type": "sample",
        "application_properties": {},
        "local_user_properties": {
          "license_type": "STRING",
          "license_expires": "TIMESTAMP"
        },
        "local_group_properties": {},
        "local_role_properties": {},
        "resources": []
      }
    ]
  }

Set custom properties

In the rest of the payload, for each object that should have additional properties, add a custom_properties array containing the property keys and values:

      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[e-mail]"
          ],
          "groups": null,
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "last_login_at": null,
          "deactivated_at": null,
          "password_last_changed_at": null,
          "tags": [],
          "custom_properties": {
            "license_type": "pro",
            "license_expires": "2023-01-01T00:00:00.000Z"
          }
        }
      ]

Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the incremental update remove_tag operation.

Validation and Troubleshooting

The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:

• Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.

• Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.

• A 200 OK response may include warnings when matching IDP identities can't be found

Applications

The OAA payload must contain at least one top-level application. To model data systems with multiple components (such as different servers or repositories), applications can have resources and sub-resources.

You can also specify more than one application in the OAA payload, each with its own identities, permissions, roles, and resources.

The application_typeis applied to all application resources and identities, and can be used as a filterable property in Veza search.

{
  "applications": [
    {
      "name": "Custom App",
      "application_type": "Source Control",
      "description": "Has a resource for each repository",
      "custom_properties": {},
      "tags": [],
      "local_users": [],
      "local_groups": [],
      "local_roles": [],
      "resources": []
    }
  ]
}

Application Properties

Field	Type	Description
name	string	Identifies the app in Veza Search. Used to bind permissions to the application
application_type	string	Applied to all entities within the application as a searchable property. Multiple instances of an application can share the same type
description	string	Any additional notes to show in the entity details, limit 256 characters
custom_properties	dictionary	Custom Properties contain property_values validated against the custom_property_definition
tags	array	Specify tags with a key and optional value (optional)
local_users	array	Contains zero or more local users (see local_identities).
local_groups	array	Contains zero or more local groups (collections of users).
local_roles	array	Defines permissions for any roles within the application.
resources	array	Contains any resources and sub-resources.

Optional fields: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:

• Any type of data in a JSON payload can be null (not set).

• Unused optional arrays and objects should be empty {} or [].

• Unused optional strings, numbers, and booleans should be null.

• Strings and string lists intended to have constant values (enums) such as identity_type may have a default value when not set.

OAA apps need to contain at least one identity, which could be a local_group, local_role, or an IdP identity. Role assignments are made in the identity_to_permissions section.

Resources

Each application can contain one or more resources that users can access. Resources can have additional searchable properties and may contain additional sub-resources.

Sub-resources describe additional layers of the application principals can have authorization to, and support the same properties as resources, including additionally nested sub-resources.

"resources": [
  {
    "name": "Entity1",
    "id": "Unique ID",
    "resource_type": "thing",
    "description": "Some entity in the application",
    "sub_resources": [
      {
        "name": "Child 1",
        "resource_type": "child",
        "description": "My information about resource",
        "sub_resources": [],
        "custom_properties": {},
        "tags": []
      }
    ],
    "custom_properties": {},
    "tags": []
  },
  {
    "name": "Entity2",
    "id": "Another Unique ID",
    "resource_type": "thing",
    "description": "Another entity in the application",
    "sub_resources": [],
    "custom_properties": {},
    "tags": []
  }
]

Resource Properties

An application can have any number of nested sub resources.

Field	Type	Description
name	string	Resource name. Primary ID for mapping users to individual resource permissions.
id	string	Optional value to use as the unique ID, instead of the resource name*.
resource_type	string	Searchable label for the resource type. The application entity details in Veza will show the contained resource types as properties.
description	string	Shown in Veza entity details, max 255 characters.
custom_properties	dictionary	See Custom Properties.
sub_resources	array	Used for additional resource layers, nested data sources, services, and so on.
connections	Resource Connections	Optional list of resource connections to external entities discovered by Veza
tags	array	Specify tags with a key and optional value (optional)

* A specific resource type must have only resources with an id, or only resources without an id. When used identity_to_permissions assignments are made by the id value and name functions as a display name.

Resource Connections

In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza authorization graph.

If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the connections to another graph entity node_type and id:

{
  "name": "cog1",
  "resource_type": "cog",
  "connections": [
    {
      "id": "[e-mail]",
      "node_type": "GoogleCloudServiceAccount"
     }
  ]
}

The following node types are currently available:

• SnowflakeUser

• GoogleCloudServiceAccount

• AwsIamRole

• AzureADEnterpriseApplication

• TrinoUser

Identities

Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), you can map the principal to the IdP entity name or login email in identities.

Local Users

Contains any users whose profiles and authentication are handled and stored by the custom application. Local users include their group assignments and any federated identities that should be mapped to the local user:

"local_users": [
  {
    "name": "Evan Gray",
    "unique_id": "egray",
    "identities": ["[e-mail]"],
    "groups": ["contractors"],
    "is_active": true,
    "created_at": "2020-12-19T16:39:57-08:00",
    "last_login_at": "2021-11-19T14:19:30-08:00",
    "password_last_changed_at": null,
    "deactivated_at": null,
    "custom_properties": {},
    "tags": []
   }
]

Field	Type	Description
name	string	Name of the local user, shown in the Veza UI.
unique_id	string	Optional identifier to use for mapping users to groups, roles, and permissions.
identities	identities array	Maps the user to a federated identity by login email or group name. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Must match a discovered Okta, Google Workspace, or Azure AD entity Name, PrincipalName, or Identity.
groups	groups array	list of any group memberships as strings. Must exist in local groups.
is_active	boolean	If activity state is available from the provider, use this field to make the value available as a searchable property (optional).
created_at	RFC3339 string	User creation date (optional), for example 1996-12-19T16:39:57-08:00
last_login_at	RFC3339 string	(optional)
password_last_changed_at	RFC3339 string	(optional)
deactivated_at	RFC3339 string	(optional)
custom_properties	dictionary	See Custom Properties.
tags	tags array	Specify tags with a key and optional value (optional)

local Groups

"local_groups": [
  {
    "name": "US Contractors",
    "unique_id": "us-contractors",
    "identities": ["[e-mail]"],
    "groups": [
      "all-contractors",
      "all-workers"
    ],
    "tags": []
  }
]

If the application has any groups, describe each one in the local_groups array.

Group assignments for entities are defined in identity_to_permissions.

Field	Type	Description
name	string	Name of the local group. Primary ID for mapping group to permissions.
unique_id	string	Optional identifier to use for permissions mapping
custom_properties	dictionary	See Custom Properties.
identities	array	If IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.*
groups	array	List of local group this group is a member of (for applications that support adding groups to other groups)
tags	array	Specify tags with a key and optional value (optional)

*Must match a discovered Okta or Azure entity Name, PrincipalName, or Identity

Local Roles

"local_roles": [
    {
        "name": "administrator",
        "unique_id": "0001",
        "permissions": ["create","destroy"]
    },
    {
        "name": "operator",
        "permissions": ["pull", "read"],
        "tags": []
    }
]

Local roles define collections of local permissions that can be assigned to multiple resources. In the applications section, roles are named and mapped to permissions. Role assignments are defined in identity_to_permissions.

Field	Type	Description
name	string	Name of the local role. Primary ID for mapping role to permissions.
unique_id	string	Optional identifier to use for permissions mapping
permissions	array	Permissions associated with the role. Must exist in permissions
tags	array	Specify tags with a key and optional value (optional)

permissions

"permissions": [
   {
     "name": "Admin",
     "permission_type": [
       "DataRead",
       "DataWrite",
       "MetadataRead",
       "MetadataWrite"
     ]
   },
   {
     "name": "Operator",
     "permission_type": [
       "MetadataRead",
       "DataRead"
     ]
   },
   {
     "name": "Inactive",
     "permission_type": [
       "NonData"
     ]
   }
 ]

Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.

Canonical permission types are:

• DataRead

• DataWrite

• MetadataRead

• MetadataWrite

• NonData

• DataCreate

• DataDelete

• MetadataCreate

• MetadataDelete

• Uncategorized

Field	Type	Description
name	string	Native permission name, such as “Push” (used to bind local and IdP identities to native permissions).
permission_type	enum	List of canonical privilege(s) the permission represents.
application_type	enum	Optional list of custom application application_type the permission applies to.
apply_to_sub_resources	bool	To more accurately model applications where permissions should apply to any children of a resource, set TRUE to define the permission as inheritable. This eliminates the need to include the permission at each sub level.

To better model systems where roles can contain different permissions to different types of resources, permissions can apply to individual resource_types.

• When the payload is parsed, individual permissions are created for each type of resource the permission applies to.

• Without resource_types specified, the permission will function normally. When directly connecting principals and resources, resource_type is ignored.

identity_to_permissions

"identity_to_permissions": [
     {
       "identity": "Evan Gray",
       "identity_type": "local_user",
       "application_permissions": [
          {
           "application": "Veza AI",
           "resources": ["terraform-dev", "prod"],
           "permission": "pull"
         },
         {
           "application": "Veza AI",
           "resources": ["terraform-dev", "prod"],
           "permission": "push"
         }
       ]
     }
   ]

Contains an object for each local and IdP identity, and the individual permissions to applications and resources.

• You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the identity, and setting the identity_type to idp.

• Permissions and role assignments can apply to the entire application or scoped to specific resources.

• For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:

Field	Type	Description
identity	string	Principal name or email address. Maps to IdP login email or group name.
identity_type	string	Sets whether the identity corresponds to an IdP identity, or is local to the application
application_permissions	array	List each local permission available to the identity (must be a valid permission name from the previous section).
role_assignments	array	Any roles assigned to the identity, and the resources they apply to (role/resource must exist in applications).

• Each identity can be either a local_user, local_role, or local_group name, or the identifier of an IdP user, group, or role (email address or group name).

• identity_type must be one of (idp (default), local_group, local_role, or local_user.

application_permissions

{
    "identity": "[e-mail]",
    "identity_type": "idp",
    "application_permissions":
    [
        {
            "application": "source control",
            "resources": ["util-tools", "terraform"],
            "apply_to_application": false,
            "permission": "write"
        },
        {
            "application": "source control",
            "resources": [],
            "apply_to_application": true,
            "permission": "read"
        }
    ]
}

Binds the identity (IdP entity, local user, or local group) to local permission, by application and resources.

Field	Type	Description
application	string	Maps to an application name from the first section. Must exist in applications
resources	array	List of application resource or sub-resource names to apply the permission. Must exist in applications
apply_to_application	boolean	Set to true to model environments where permissions apply to the top-level application as well as its resources.
permission	string	Maps to a permission name from the second section. Must exist in permissions

role_assignments

Local roles are assigned to identities in the role_assignments array. Roles can apply to the entire application or only to specific (sub) resources.

{
    "identity": "john_smith",
    "identity_type": "local_user",
    "role_assignments":[
        {
            "application": "custom application",
            "role": "administrator",
            "apply_to_application": true,
            "resources": []
        },
        {
            "application": "custom application",
            "role": "ops",
            "apply_to_application": false,
            "resources": ["oaa-vm-1"]
        }
    ]
}

Field	Type	Description
application	string	The application where the role applies. Must exist in applications
role	string	The role name. Must exist in local_roles
apply_to_application	boolean	Set to true to model environments where the role applies to the top-level application and all its resources.
resources	array	List of resources and sub-resources where the role applies. Must exist in applications

Identities to Permissions mapping

  "identity_to_permissions": [
    {
      "identity": "0000000001",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        }
      ]
    },
    {
      "identity": "0000000002",
      "identity_type": "local_user",
      "role_assignments": [
        {
          "application": "Sample App",
          "role": "user",
          "apply_to_application": true,
          "resources": []
        },
        {
          "application": "Sample App",
          "role": "admin",
          "apply_to_application": true,
          "resources": []
        }
      ]
    }
  ]