Release Notes

Custom Application with SCIM (OAA)

Enable SCIM-based provisioning for custom applications with Open Authorization API

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"
}
PreviousCoupa Contingent WorkforceNextExchange Server

Last updated

Was this helpful?