VEZA DEVELOPERS

Appearance

Custom Application Template ​

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:

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

json
{
  "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": [
            "[email protected]"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "id": "0000000001"
        },
        {
          "name": "jane",
          "identities": [
            "[email protected]"
          ],
          "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
json
{
  "applications": [
    {
      "name": "Sample App",
      "application_type": "sample",
      "description": "This is a sample app",
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[email protected]"
          ],
          "is_active": true,
          "created_at": "2022-01-26T20:48:12.460Z",
          "id": "0000000001"
        },
        {
          "name": "jane",
          "identities": [
            "[email protected]"
          ],
          "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 ​

json
  "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:

json
      "local_users": [
        {
          "name": "bob",
          "identities": [
            "[email protected]"
          ],
          "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.

json
{
  "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 ​

FieldTypeDescription
namestringIdentifies the app in Veza Search. Used to bind permissions to the application
application_typestringApplied to all entities within the application as a searchable property. Multiple instances of an application can share the same type
descriptionstringAny additional notes to show in the entity details, limit 256 characters
custom_propertiesdictionaryCustom Properties contain property_values validated against the custom_property_definition
tagsarraySpecify tags with a key and optional value (optional)
local_usersarrayContains zero or more local users (see local users).
local_groupsarrayContains zero or more local groups (collections of users).
local_rolesarrayDefines permissions for any roles within the application.
resourcesarrayContains 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.

json
"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.

FieldTypeDescription
namestringResource name. Primary ID for mapping users to individual resource permissions.
idstringOptional value to use as the unique ID, instead of the resource name*.
resource_typestringSearchable label for the resource type. The application entity details in Veza will show the contained resource types as properties.
descriptionstringShown in Veza entity details, max 255 characters.
custom_propertiesdictionarySee Custom Properties.
sub_resourcesarrayUsed for additional resource layers, nested data sources, services, and so on.
connectionsResource ConnectionsOptional list of resource connections to external entities discovered by Veza
tagsarraySpecify 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:

json
{
  "name": "cog1",
  "resource_type": "cog",
  "connections": [
    {
      "id": "[email protected]",
      "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:

json
"local_users": [
  {
    "name": "Evan Gray",
    "unique_id": "egray",
    "identities": ["[email protected]"],
    "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": []
   }
]
FieldTypeDescription
namestringName of the local user, shown in the Veza UI.
unique_idstringOptional identifier to use for mapping users to groups, roles, and permissions.
identitiesidentities arrayMaps 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.
groupsgroups arraylist of any group memberships as strings. Must exist in local groups.
is_activebooleanIf activity state is available from the provider, use this field to make the value available as a searchable property (optional).
created_atRFC3339 stringUser creation date (optional), for example 1996-12-19T16:39:57-08:00
last_login_atRFC3339 string(optional)
password_last_changed_atRFC3339 string(optional)
deactivated_atRFC3339 string(optional)
custom_propertiesdictionarySee Custom Properties.
tagstags arraySpecify tags with a key and optional value (optional)

local Groups ​

json
"local_groups": [
  {
    "name": "US Contractors",
    "unique_id": "us-contractors",
    "identities": ["[email protected]"],
    "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.

FieldTypeDescription
namestringName of the local group. Primary ID for mapping group to permissions.
unique_idstringOptional identifier to use for permissions mapping
custom_propertiesdictionarySee Custom Properties.
identitiesarrayIf IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.*
groupsarrayList of local group this group is a member of (for applications that support adding groups to other groups)
tagsarraySpecify tags with a key and optional value (optional)

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

Local Roles ​

json
"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.

FieldTypeDescription
namestringName of the local role. Primary ID for mapping role to permissions.
unique_idstringOptional identifier to use for permissions mapping
permissionsarrayPermissions associated with the role. Must exist in permissions
tagsarraySpecify tags with a key and optional value (optional)

Permissions ​

json
"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
FieldTypeDescription
namestringNative permission name, such as “Push” (used to bind local and IdP identities to native permissions).
permission_typeenumList of canonical privilege(s) the permission represents.
application_typeenumOptional list of custom application application_type the permission applies to.
apply_to_sub_resourcesboolTo 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 ​

json
"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:
FieldTypeDescription
identitystringPrincipal name or email address. Maps to IdP login email or group name.
identity_typestringSets whether the identity corresponds to an IdP identity, or is local to the application
application_permissionsarrayList each local permission available to the identity (must be a valid permission name from the previous section).
role_assignmentsarrayAny 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 ​

json
{
    "identity": "[email protected]",
    "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.

FieldTypeDescription
applicationstringMaps to an application name from the first section. Must exist in applications
resourcesarrayList of application resource or sub-resource names to apply the permission. Must exist in applications
apply_to_applicationbooleanSet to true to model environments where permissions apply to the top-level application as well as its resources.
permissionstringMaps 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.

json
{
    "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"]
        }
    ]
}
FieldTypeDescription
applicationstringThe application where the role applies. Must exist in applications
rolestringThe role name. Must exist in local_roles
apply_to_applicationbooleanSet to true to model environments where the role applies to the top-level application and all its resources.
resourcesarrayList of resources and sub-resources where the role applies. Must exist in applications

Identities to Permissions mapping ​

json
  "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": []
        }
      ]
    }
  ]