Custom Identity Provider Template

Template for pushing IdP domain, user, and group metadata

Use this template to model authorization metadata for custom identity providers using the Open Authorization API.

This document includes an example template and notes for designing and publishing a model of your IdP

domain
users
groups.

A custom property definition can define additional properties to add additional metadata to entities in the payload.

Veza will handle federated identities just as those in supported IdPs such as Okta or Azure AD, enabling search and access review for OAA entities alongside the rest of your data catalog.

Sample Template and Features

The metadata payload describes the Identity Provider domain, users, and groups to add to the Veza authorization graph:

Simple Custom Identity Provider

json

{
  "name": "My IdP",
  "idp_type": "custom_idp",
  "domains": [
    {
      "name": "example.com",
      "tags": [],
    }
  ],
  "users": [
    {
      "name": "m_richardson",
      "email": "[email protected]",
      "identity": "m_richardson",
      "full_name": "Michelle Richardson",
      "department": null,
      "is_active": true,
      "is_guest": false,
      "groups": [
        {
          "identity": "everyone"
        },
        {
          "identity": "developers"
        }
      ],
      "assumed_role_arns": [
        {
          "identity": "arn:aws:iam::123456789012:role/role001"
        },
        {
          "identity": "arn:aws:iam::123456789012:role/role002"
        }
      ],
      "tags": [],
    },
    {
      "name": "evargas",
      "email": "[email protected]",
      "identity": "evargas",
      "full_name": "Elizabeth Vargas",
      "department": null,
      "is_active": true,
      "is_guest": false,
      "groups": [
        {
          "identity": "everyone"
        },
        {
          "identity": "developers"
        },
        {
          "identity": "sec-ops"
        }
      ],
      "assumed_role_arns": [],
      "tags": [],
    },
    {
      "name": "willis",
      "email": "[email protected]",
      "identity": "c_williams",
      "full_name": null,
      "department": null,
      "is_active": true,
      "is_guest": false,
      "groups": [
        {
          "identity": "everyone"
        }
      ],
      "assumed_role_arns": [],
      "tags": []
    }
  ],
  "groups": [
    {
      "name": "developers",
      "identity": "developers",
      "full_name": null,
      "is_security_group": null,
      "tags": []
    },
    {
      "name": "sec-ops",
      "identity": "sec-ops",
      "full_name": null,
      "is_security_group": null,
      "tags": []
    },
    {
      "name": "everyone",
      "identity": "everyone",
      "full_name": "All Company Employees",
      "is_security_group": null,
      "tags": []
    }
  ]
}

Modeling assumable Amazon Web Services roles

For cases where federated IdP entities are granted AWS permissions via IAM roles, the template supports defining assumable roles per-user. Binding a custom IdP user or group to an AWS role or group ARN enables Veza to parse and display the resource-level actions permitted within AWS.

json

{
      "name": "Custom User",
      "assumed_role_arns": {
        "identity": [
          "arn:aws:iam::123456789012:role/S3Access"
          ]
        },
    }

Custom IdP users and groups can be assigned permissions in other OAA applications by setting the principal type to idp in identity_to_permissions in the custom application payload.

Source Identity Assignments

For use cases where a custom IdP is federated with another identity provider user identities can be linked between the two. Authorizations granted to the user will also be granted the source identity. The link is created by providing the unique identity ID and provider type as part of the user entry.

json

{
  "name": "Custom User",
  "identity": "00001",
  "source_identity": {
    "identity": "[email protected]",
    "provider_type": "okta"
  }
}

For provider_type the following values are accepted:

Provider	`provider_type` string
Active Directory	`active_directory`
Any	`any`
AzureAD	`azure_ad`
OAA	`custom`
Google Workspace	`google_workspace`
Okta	`okta`
One Login	`one_login`

Resource manager assignments

New in Veza release 2022.2.1

To assign an IdP user or group as the manager of any resource Veza has discovered, list the node type and node id in the entities_owned field, for example:

json

{
  "name": "Custom User",
  "identity": "000011",
  "entities_owned": [
    {
      "node_type": "S3Bucket",
      "id": "arn:aws:s3:::amazon-connect-53f87966654d"
    }
  ]
}

When parsing the payload, resources in the data catalog will be updated with a SYSTEM_resource_managers tag to enable entitlement reviews. The owner(s) will be suggested as reviewers for Veza Workflows that target an individual named resource with the correct tag.

Manager assignments

New in Veza release 2022.2.1

Users and groups can be mapped to the identity of another user they report to. When configured, the manager will be suggested as a review for Workflow certifications where the assigned reporter is the single query target "named entity."

json

{
  "name": "Custom User",
  "identity": "000013",
  "manager_id": "000011"
}

Custom Properties and Tags

Custom Properties are the recommended method for adding additional metadata to custom identities and resources.

Additionally, Veza tags can be applied to the IdP domain, users, and groups:

json

"tags": [
  {
    "key": "Tag1key",
    "value": "optional_Tag1Val"
  }
]

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.

Incremental Updates

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

`Custom Identity Provider` definition

The identity provider object models one instance of the custom IdP:

Field	Type	Description
`name`	string	Name to associate with the provider in Veza.
`custom_property_definition`	Custom Property Definition	Defines the key and types for properties that can be applied to other objects in the push payload
`idp_type`	string	Type descriptor for IdP, can be unique or share across multiple IdP (for example `ldap`, `IPA`)
`idp_description`	string	Any notes to add as entity details (optional)
`domains`	IdP Domain	Domain model
`users`	IdP Users	Dictionary of CustomIdPUser class instances
`groups`	IdP Group	Dictionary of CustomIdPGroup class instances
`incremental_change`	boolean	When `true`, enables incremental update operations (optional).

`IdP Domain`

One domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:

Field	Type	Description
`name`	string	IdP Domain name
`custom_properties`	Custom Properties	Each element of the push payload can have `property_values`, validated against the `custom_property_definition`.
`dynamic_properties`	Dynamic Properties	Up to 5 attributes to apply to the domain (deprecated, use custom properties instead)
`tags`	Veza Tags list	Any tags to create and apply to the domain.
`operation`	enum	For incremental updates, the operation to use.

`IdP Users`

Each IdP user object contains the display name, login email, and identity, along with other identity-related properties:

json

{
      "name": "willis",
      "email": "[email protected]",
      "identity": "000001",
      "full_name": "Charles Willis",
      "department": "Sales",
      "is_active": true,
      "is_guest": false,
      "groups": [
        {
          "identity": "everyone"
        }
      ],
      "assumed_role_arns": {
        "identity": [
          "arn:aws:iam::123456789012:role/S3Access"
          ]
      },
      "source_identity": {
        "identity": "[email protected]",
        "provider_type": "okta"
      },
      "tags": [],
      "custom_properties": {},
      "manager_id": "string",
      "entities_owned": {
        "node_type": "S3Bucket",
        "id": "arn:aws:s3:::amazon-connect-53f87966654d"
        }
    }

Field	Type	Description
`name`	string	Primary ID for user
`email`	string	Optional email for user
`identity`	string	Optional unique identifier for user
`groups`	string list	Assign groups memberships by group `identity` (optional)
`full_name`	string	Full name to display in Veza
`department`	string list	Any departments to apply as a searchable property (optional).
`is_active`	boolean	If available, will be applied to the entity as a searchable property (optional).
`is_guest`	boolean	If available, will be applied to the entity as a searchable property (optional).
`assumed_role_arns`	array	AWS IAM roles that can be assumed by the IdP user, in the format `{"identity": ["arn:aws:iam::123456789012:role/S3Access"]}` (optional).
`tags`	Veza Tags list	Any tags to create and apply to the user.
`dynamic_properties`	Dynamic Properties	Up to 5 attributes to apply to the user (deprecated, use custom properties instead)
`custom_properties`	Custom Properties	Each element of the push payload can have `property_values`, validated against the `custom_property_definition`.
`manager_id`	string	If the same as another user's `identity`, that user will be recommended for governance reviews. Entity details for the user will be updated on push to include the manager as a searchable property.
`entities_owned`	Entities Owned array	If another resource is specified by entity type and entity id, a Veza tag will be created on the resource to indicate the owner.
`operation`	enum	For incremental updates, the operation to use (optional).
`source_identity`	Source Identity	Optionally link IdP user to user from another IdP for federation use cases.

`IdP Groups`

Add a group by name in the groups section of the template to enable mapping IdP users to those groups:

json

"groups": [
  {
    "name": "developers",
    "identity": "developers",
    "full_name": null,
    "is_security_group": null,
    "assumed_role_arns": {
      "identity": ["arn:aws:iam::123456789012:role/S3Access"]
    },
    "tags": [],
    "groups": [
      { "group_1_identity": "parent" },
      { "group_2_identity": "parent" }
    ],
    "custom_properties": {}
  }
]

Field	Type	Description
`name`	string	IdP group name.
`identity`	string	Unique ID used for user-group assignments.
`full_name`	string	Optional display name for group
`groups`	string list	other custom IdP groups this group is a member of
`is_security_group`	boolean	Sets the `is security group` searchable property for the entity in Veza (optional).
`tags`	Veza Tags list	Any tags to create and apply to the group.
`custom_properties`	Custom Properties	Each element of the push payload can have `property_values`, validated against the `custom_property_definition`.
`dynamic_properties`	Dynamic Properties	Up to 5 attributes to apply to the domain. (deprecated, use custom properties instead)
`operation`	enum	For incremental updates, the operation to use (optional).
`assumed_role_arns`	array	AWS IAM roles the group can assume, in the format `{"identity": ["arn:aws:iam::123456789012:role/S3Access"]}` (optional).

IdP entities can be granted permissions on custom applications in the identity_to_permissions section of the custom app metadata payload.

Adding a new custom identity provider

The steps to add a custom IdP are the same as for any other OAA provider: you will need to register the new provider and data source, and then push the domain, user, and group descriptions in a JSON payload.

1. Register a custom identity provider

To create a new custom provider using the identity_provider template, POST the name and template type to /providers/custom:

bash

curl -X POST 'https://<veza_url>/api/v1/providers/custom' \
-H 'authorization: Bearer '<access_token> \
--data-binary '{"name":"SimpleIdP","custom_template":"identity_provider"}'

The response will return the custom IdP ID, which you will need when pushing the metadata payload:

json

{
  "value": {
    "id": "532f6fe3-189f-4576-afdf-8913088961e4",
    "name": "Simple IdP",
    "custom_template": "identity_provider",
    "state": "ENABLED",
    "application_types": [],
    "resource_types": [],
    "idp_types": []
  }
}

2. Push a data source for the custom identity provider

bash

curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources' \
-H 'authorization: Bearer '<access_token> \
--data-binary '{"id":"532f6fe3-189f-4576-afdf-8913088961e4", "name":"SimpleDataSource"}'

Note that the provider id is required in both the path and body of the request. The response will include the new data source ID.

bash

{"value":{"id":"b6a32af6-b854-47e1-8325-e5984f78bb4d","name":"SimpleDataSource"}}

3. Push metadata for the data source

bash

curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources/b6a32af6-b854-47e1-8325-e5984f78bb4d:push' \
-H 'authorization: Bearer '<access_token> \
--compressed --data-binary @payload.json

The payload file must contain the provider and data source ID, and the authorization metadata as a single string, for example:

json

{
  "id": "532f6fe3-189f-4576-afdf-8913088961e4",
  "data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
  "json_data": "{\n\"name\":\"CustomIdentityProvider\",\n\"idp_type\": ... "
}

OAA Push API

OAA Templates

Python SDK

oaaclient modules

Custom Identity Provider Template

Sample Template and Features

Modeling assumable Amazon Web Services roles

Source Identity Assignments

Resource manager assignments

Manager assignments

Custom Properties and Tags

Incremental Updates

`Custom Identity Provider` definition

`IdP Domain`

`IdP Users`

`IdP Groups`

Adding a new custom identity provider

1. Register a custom identity provider

2. Push a data source for the custom identity provider

3. Push metadata for the data source

oaaclient modules

Custom Identity Provider Template ​

Sample Template and Features ​

Modeling assumable Amazon Web Services roles ​

Source Identity Assignments ​

Resource manager assignments ​

Manager assignments ​

Custom Properties and Tags ​

Incremental Updates ​

Custom Identity Provider definition ​

IdP Domain ​

IdP Users ​

IdP Groups ​

Adding a new custom identity provider ​

1. Register a custom identity provider ​

2. Push a data source for the custom identity provider ​

3. Push metadata for the data source ​

Custom Identity Provider Template

Sample Template and Features

Modeling assumable Amazon Web Services roles

Source Identity Assignments

Resource manager assignments

Manager assignments

Custom Properties and Tags

Incremental Updates

`Custom Identity Provider` definition

`IdP Domain`

`IdP Users`

`IdP Groups`

Adding a new custom identity provider

1. Register a custom identity provider

2. Push a data source for the custom identity provider

3. Push metadata for the data source