OAA with SCIM Lifecycle Management

Overview

Veza can automate user provisioning and de-provisioning for any application that uses the Open Authorization API (OAA) for data gathering and authorization modeling, and exposes SCIM-compliant endpoints for user and group management.

This enables organizations to:

• Use your application's existing SCIM endpoints for automated provisioning operations
• Model complex authorization structures using OAA's flexible templates (applications, resources, permissions, custom properties) for Access Graph visibility, Access Reviews, and other Veza features.
• Gather authorization metadata using a variety of methods (custom connectors, APIs, manual JSON payloads, CSV files)

Supported Actions

Action Type	Supported	Description
Sync Identities	✅	Create new users or update existing user attributes in the target application
Manage Relationships	✅	Add or remove users from groups
De-provision Identity	✅	Deactivate user accounts (sets active=false in SCIM)
Delete Identity	✅	Permanently delete user accounts from the target application
Create Entitlement	✅	Create new groups in the target application

Lifecycle Management and Access Requests with Open Authorization API

There are several potential ways to integrate a custom application for automated lifecycle management and access requests:

1. External SCIM for Open Authorization API: You may build your OAA integration using the custom application template and leverage dedicated SCIM endpoints for user and group management. This is useful when you need full control over how authorization metadata is represented in the Veza Access Graph:
   • Your application supports SCIM, and you want to model a wider range of authorization entities and metadata (e.g., credentials, resources) than the Veza SCIM integration supports.
   • You already have a custom OAA integration and want to add provisioning capabilities using SCIM.
2. Full SCIM Connector: Use the built-in SCIM connector for both basic data gathering and lifecycle management. This will provide visibility into supported SCIM entities and relationships with schedulable extractions, but not for the full range of entities and metadata that might be modeled using the Application Template such as roles and resources.
3. Custom REST API Actions: Actions in Veza may directly call any external API and capture the response in audit trails. This can enable Lifecycle Management and Access Requests for any target system, provided it has appropriate endpoints for managing users and access controls.

Aspect	External OAA with SCIM Write-Back	Built-In SCIM Connector
Extraction Method	You build the OAA push payload directly	Auto-discovery via SCIM endpoints
Authorization Modeling	Full OAA Application support (roles, permissions, resources)	Users and groups only
Lifecycle Management	Via SCIM endpoints	Via SCIM endpoints
Use Case	Complex custom applications where visibility or access reviews are needed.	Standard SaaS with SCIM support

This document describes how to enable External SCIM for an Open Authorization API integration, and supported actions.

How It Works

Data Gathering (OAA):

You will need to design and build a custom integration to publish information about the application to the Veza Access Graph:

• The payload can include local users, groups, permissions, resources, and complex authorization relationships
• Data can be gathered from any source: APIs, databases, configuration files, etc.

See the rest of the Open Authorization API documentation for examples and best practices when designing and deploying custom integrations.

Lifecycle Management (SCIM):

You can enable the SCIM connection at the custom provider level:

• Setting provisioning: true and external_lifecycle_management_type: SCIM for the custom provider enables Veza to use your application's SCIM endpoints for provisioning
• Provide SCIM connection information and credentials (configuration_json)
• Veza maps lifecycle actions to SCIM operations (POST /Users, PATCH /Users/{id}, etc.)

Important: When configuring a custom application for SCIM integration, the OAA payload structure (Application template) and SCIM configuration serve different purposes:

• The OAA Payload (push_application() or API push) defines local users, groups, permissions, and resources used for visibility and authorization modeling in Veza, and can be updated independently.
• The SCIM Configuration (configuration_json) for the custom provider defines how to connect to SCIM endpoints (including authentication, URL, and endpoint paths), and is used only for lifecycle management and access request operations.

Both must be consistent (describe and contain the same users and groups), but are configured separately.

Required SCIM 2.0 Endpoints

Your application must expose SCIM 2.0 compliant endpoints with the following operations:

User Management:

• GET /Users - List and filter users
• GET /Users?filter=userName eq "{username}" - Query users by userName
• POST /Users - Create new users
• GET /Users/{id} - Retrieve specific user by ID
• PATCH /Users/{id} - Update user attributes
• DELETE /Users/{id} - Delete user (required if using Delete Identity action)

Group Management:

• GET /Groups - List groups
• GET /Groups/{id} - Retrieve specific group by ID
• POST /Groups - Create new groups
• PATCH /Groups/{id} - Update group membership
• DELETE /Groups/{id} - Delete group (optional)

Note: If the Users and Groups APIs are not at the standard /Users and /Groups paths, you can specify alternate endpoint paths in the configuration.

Authentication

Your SCIM API must support one of the following authentication methods:

• Bearer Token: API token passed in Authorization: Bearer {token} header
• Basic HTTP Authentication: Username and password passed in Authorization: Basic {credentials} header

The authentication credentials must have both read and write permissions to the SCIM endpoints.

Optional: Extension Attributes

To synchronize custom attributes beyond the standard SCIM user schema:

• Expose a GET /Schemas endpoint that returns SCIM schema definitions
• Enable schema fetching in your configuration (see Configuration section)

Configuration

External SCIM for Lifecycle Management is configured via the Veza REST API.

Create Custom Provider with External SCIM

Create a Custom Provider that uses external SCIM endpoints specifically for lifecycle management:

curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
  -H "authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "MyCustomApp",
    "custom_template": "application",
    "provisioning": true,
    "external_lifecycle_management_type": "SCIM",
    "configuration_json": "{\"scim_url\":\"https://api.myapp.com/scim/v2\",\"scim_token\":\"your-bearer-token\"}"
  }'

Required Fields

Field	Required	Description
name	Yes	Display name for the Custom Provider in Veza
custom_template	Yes	OAA template type ("application")
provisioning	Yes	Must be set to true to enable Lifecycle Management
external_lifecycle_management_type	Yes	Lifecycle management mode (use "SCIM" to enable SCIM-based provisioning)
configuration_json	Yes	JSON-encoded string containing SCIM connection details (see structure below)

Configuration JSON Parameters

The configuration_json field contains SCIM endpoint connection details used only for provisioning operations. It does not affect your OAA payload structure.

Configuration Key	Required	Description	Example Value
scim_url	Yes	Base URL for SCIM API (without /Users or /Groups path)	"https://api.myapp.com/scim/v2"
scim_token	No*	Bearer token for authentication	"eyJhbGci..."
username	No*	Username for basic authentication	"scim-admin"
password	No*	Password for basic authentication	"secure-password"
users_endpoint	No	Users endpoint path (defaults to Users if not specified)	"Users"
groups_endpoint	No	Groups endpoint path (defaults to Groups if not specified)	"Groups"
scim_extension_schemas	No	Fetch SCIM schemas for extension attribute support (default: false)	true
ca_certificate	No	Custom CA certificate for SSL verification (PEM format)	"-----BEGIN CERTIFICATE-----..."

* One of scim_token or the username/password pair is required for authentication.

Example Configuration with Bearer Token:

{
  "scim_url": "https://api.customerportal.internal.com/scim/v2",
  "scim_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scim_extension_schemas": true
}

Example Configuration with Basic Authentication:

{
  "scim_url": "https://legacy.mycompany.com/api/scim",
  "username": "scim-service-account",
  "password": "secure-password-here"
}

Push OAA Payload

Push the OAA Application Payload as normal. See the getting started guide for details.

Entity Types and Identity Mapping

Veza creates entities in Access Graph based on the OAA payload, which can be targeted in lifecycle management operations:

• local_users in your Application template → Users to provision via SCIM
• local_groups in your Application template → Groups to manage via SCIM

Entity types are named according to the following pattern:

• User Entity Type: OAA.{application_type}.User
• Group Entity Type: OAA.{application_type}.Group

Where {application_type} is the value you specify in your OAA Application template when building the payload. For example, if the application is defined:

custom_app = CustomApplication(
    name="CustomerPortal",           # Display name
    application_type="CustomerPortal" # This determines entity types!
)

The resulting entity types are:

• OAA.CustomerPortal.User
• OAA.CustomerPortal.Group

Attribute Synchronization

Mapping OAA to SCIM

When Veza provisions users via SCIM, transformers can map attributes from your policy source of identity to SCIM properties:

Veza Attribute (in Policy)	SCIM Property	Type	Required	Description
user_name	userName	String	Yes	Unique username
emails	emails	Array	No	Email addresses
display_name	displayName	String	No	User's display name
title	title	String	No	Job title
nick_name	nickName	String	No	Casual name
external_id	externalId	String	No	External system identifier
phone_numbers	phoneNumbers	Array	No	Phone numbers (JSON array)
addresses	addresses	Array	No	Physical addresses (JSON array)
ims	ims	Array	No	Instant messaging addresses (JSON array)
photos	photos	Array	No	Photo URLs (JSON array)
locale	locale	String	No	User's locale
preferred_language	preferredLanguage	String	No	Preferred language
profile_url	profileUrl	String	No	Profile page URL
timezone	timezone	String	No	User's timezone
user_type	userType	String	No	User classification
formatted_name	name.formatted	String	No	Full formatted name
family_name	name.familyName	String	No	Last name
given_name	name.givenName	String	No	First name
middle_name	name.middleName	String	No	Middle name

Extension Attributes

If the SCIM service exposes a /Schemas endpoint and you enable scim_extension_schemas: true, Veza can synchronize custom extension attributes beyond the standard SCIM user schema. Extension attributes are mapped using the schema URN as defined by your SCIM implementation.

Provisioning Operations

The following SCIM operations are performed when Lifecycle Management actions execute:

Sync Identities (Create User)

Create a new user in the target application.

SCIM Operation:

POST /Users
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jane.doe",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe",
    "formatted": "Jane Doe"
  },
  "emails": [
    {"value": "[email protected]", "primary": true}
  ],
  "active": true
}

The SCIM endpoint creates the user and returns the user object with an assigned id.

Sync Identities (Update User)

Updates an existing user's attributes (one-time or continuously).

SCIM Operations:

1. Query for existing user:

   GET /Users?filter=userName eq "jane.doe"

2. Update the user:

   PATCH /Users/{id}
   Content-Type: application/scim+json

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
     "Operations": [
       {"op": "replace", "path": "displayName", "value": "Jane Smith"}
     ]
   }

De-provision Identity

Remove access when a user leaves the organization or changes roles. The user account is deactivated, but data is preserved.

SCIM Operation:

PATCH /Users/{id}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "active", "value": false}
  ]
}

Deprovision sets active=false, which disables login but preserves the user record.

Delete Identity

Permanently remove a user account.

SCIM Operation:

DELETE /Users/{id}

Manage Relationships (Add User to Group)

Grant a user access via group membership.

SCIM Operations:

1. Retrieve group details:

   GET /Groups/{groupId}

2. Add user to group:

   PATCH /Groups/{groupId}
   Content-Type: application/scim+json

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
     "Operations": [
       {
         "op": "add",
         "path": "members",
         "value": [{"value": "{userId}"}]
       }
     ]
   }

Manage Relationships (Remove User from Group)

Revoke a user's access by removing group membership.

SCIM Operation:

PATCH /Groups/{groupId}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [{"value": "{userId}"}]
    }
  ]
}

Create Entitlement (Create Group)

Creates a new group so that it can be granted as an entitlement.

SCIM Operation:

POST /Groups
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering Team"
}