Directory Sync (SCIM) - Banata Auth Docs

Directory Sync automates user provisioning between your customers' identity providers (IdPs) and your application using the SCIM 2.0 protocol. When an employee is added, updated, or removed in an IdP like Okta, Azure AD, or OneLogin, the corresponding user record in Banata Auth is automatically created, modified, or disabled — no manual intervention required.

This keeps your application's user directory in sync with your customer's corporate directory at all times, reducing admin overhead and eliminating the security risks of stale accounts.

Key Capabilities

Automatic provisioning — New employees added in the IdP are automatically created as users in your application.
Automatic deprovisioning — Employees removed from the IdP are disabled and their sessions revoked, ensuring immediate access removal.
Profile synchronization — Changes to user attributes (name, email, department, etc.) in the IdP are propagated to Banata Auth automatically.
Group synchronization — Group membership changes in the IdP are reflected in Banata Auth, enabling role and permission mapping based on your customers' organizational structure.

How It Works

Directories and Organizations

Each SCIM directory is scoped to a specific organization in Banata Auth. This means every customer organization can have its own directory connection, keeping user provisioning isolated per tenant. You can configure multiple directories across different organizations, each connected to a different IdP.

Push-Based Synchronization

Banata Auth exposes a SCIM 2.0-compliant endpoint for each directory. The IdP pushes user and group changes to this endpoint in real time. Whenever a change occurs in the IdP — a new hire, a termination, a group membership update — the IdP sends an HTTP request to the SCIM endpoint, and Banata Auth processes the event accordingly.

Here is how the setup flow works:

You create a SCIM directory in Banata Auth for a given organization.
Banata Auth generates a unique SCIM endpoint URL and a bearer token for that directory.
You (or your customer's IT admin) configure the IdP with the endpoint URL and bearer token.
The IdP begins pushing user and group changes to Banata Auth in real time.

Authentication

All SCIM endpoints are authenticated using a bearer token. Each directory has its own unique token, generated at the time of directory creation. The IdP must include this token in the Authorization header of every SCIM request:

typescript

Authorization: Bearer scim_tok_xxxxxxxxxxxxxxxx

Supported SCIM Operations

Banata Auth processes the following SCIM operations:

SCIM Operation	Resource	Effect in Banata Auth
`POST /Users`	User	Creates a new user in the organization. If the user already exists (matched by email), the existing record is linked.
`PUT /Users/:id`	User	Updates the user's profile attributes (name, email, etc.).
`PATCH /Users/:id`	User	Partially updates user attributes. Commonly used for activating or deactivating a user.
`DELETE /Users/:id`	User	Deactivates the user and revokes all active sessions. The user record is retained for audit purposes.
`POST /Groups`	Group	Creates a new group in the organization.
`PUT /Groups/:id`	Group	Replaces the group's attributes and membership list.
`PATCH /Groups/:id`	Group	Partially updates group attributes or membership (add/remove members).
`DELETE /Groups/:id`	Group	Removes the group and disassociates all members.

Dashboard Setup

You can create and manage SCIM directories directly from the Banata Auth dashboard.

Step 1: Navigate to Directory Sync

Open the Banata Auth dashboard and navigate to the Directory Sync section under your project settings. This page lists all configured SCIM directories across your organizations.

Step 2: Create a Directory

Click Create Directory and fill in the required fields:

Organization — Select the organization this directory will be associated with.
Directory Name — A human-readable name for the directory (e.g., "Acme Corp Okta Directory").
Directory Type — The IdP type (Okta, Azure AD, OneLogin, Google Workspace, or Generic SCIM).

Step 3: Copy the SCIM Endpoint and Bearer Token

After creating the directory, Banata Auth displays:

SCIM Endpoint URL — The URL the IdP will send SCIM requests to (e.g., https://api.banata-auth.com/scim/v2/dir_xxx).
Bearer Token — The authentication token the IdP must include in all requests.

Copy both values. The bearer token is only shown once at creation time. If you lose it, you can rotate the token from the dashboard.

Step 4: Configure Your Identity Provider

Use the SCIM endpoint URL and bearer token to configure provisioning in your IdP. The exact steps vary by provider:

Okta:

In the Okta Admin Console, go to Applications and select your application.
Navigate to the Provisioning tab and click Configure API Integration.
Paste the SCIM endpoint URL into the SCIM 2.0 Base URL field.
Paste the bearer token into the API Token field.
Click Test API Credentials to verify the connection.
Enable the desired provisioning features (Create Users, Update User Attributes, Deactivate Users).

Azure AD (Entra ID):

In the Azure Portal, go to Enterprise Applications and select your application.
Navigate to Provisioning and set the mode to Automatic.
Under Admin Credentials, paste the SCIM endpoint URL into the Tenant URL field.
Paste the bearer token into the Secret Token field.
Click Test Connection to verify.
Configure attribute mappings as needed, then start the provisioning service.

OneLogin:

In the OneLogin Admin Panel, go to Applications and select your application.
Navigate to the Provisioning tab and enable provisioning.
Under SCIM Base URL, paste the SCIM endpoint URL.
Under SCIM Bearer Token, paste the bearer token.
Save and configure the desired provisioning actions.

SDK Usage

You can also manage SCIM directories programmatically using the Banata Auth SDK.

Initialize the Client

typescript

import { BanataAuth } from "@banata-auth/sdk";
 
const client = new BanataAuth({ apiKey: "sk_..." });

List SCIM Directories

Retrieve all configured SCIM directories across your project:

typescript

const { data: directories } = await client.directorySync.listDirectories();
 
for (const dir of directories) {
  console.log(dir.id, dir.name, dir.state);
}

Get a Specific Directory

Retrieve details about a single directory by its ID:

typescript

const directory = await client.directorySync.getDirectory("dir_xxx");
 
console.log(directory.name);         // "Acme Corp Okta Directory"
console.log(directory.state);        // "active"

Create a Directory

typescript

const newDirectory = await client.directorySync.createDirectory({
  name: "Acme Corp Azure AD",
  organizationId: "org_xxx",
  provider: "azure-ad",
});
 
console.log(newDirectory.id);          // "dir_yyy"

Delete a Directory

typescript

await client.directorySync.deleteDirectory("dir_xxx");

SCIM Events

When the IdP pushes changes to the SCIM endpoint, Banata Auth processes each operation and triggers the corresponding internal action. The table below summarizes the supported events and their effects.

Event	Trigger	Banata Auth Action
User Created	IdP sends `POST /Users`	A new user is created in the organization. If a user with the same email already exists, the existing user is linked to the directory instead of creating a duplicate.
User Updated	IdP sends `PUT /Users/:id` or `PATCH /Users/:id`	The user's profile attributes are updated to match the IdP. Fields such as name, email, and department are synchronized.
User Deactivated	IdP sends `PATCH /Users/:id` with `active: false`	The user is deactivated in Banata Auth. All active sessions are revoked. The user can no longer sign in.
User Reactivated	IdP sends `PATCH /Users/:id` with `active: true`	The user is reactivated and can sign in again with their previous credentials.
User Deleted	IdP sends `DELETE /Users/:id`	The user is deactivated and marked as deleted. The user record is retained for audit trail purposes but cannot sign in.
Group Created	IdP sends `POST /Groups`	A new group is created in the organization. Group membership is set based on the request payload.
Group Updated	IdP sends `PUT /Groups/:id` or `PATCH /Groups/:id`	The group's name, description, or membership list is updated. Members may be added or removed.
Group Deleted	IdP sends `DELETE /Groups/:id`	The group is removed and all members are disassociated.

Webhook Integration

You can subscribe to SCIM-related events via webhooks to trigger custom logic in your application when directory changes occur. The following webhook event types are available:

scim.user.created
scim.user.updated
scim.user.deleted
scim.group.created
scim.group.updated
scim.group.deleted

Each webhook payload includes the full user or group object, the directory ID, and the organization ID. This allows you to react to provisioning events in real time — for example, sending a welcome email when a new user is provisioned, or cleaning up application-specific resources when a user is deprovisioned.

Next Steps

Organizations — Learn how to set up the organizations that SCIM directories are scoped to.
Single Sign-On (SSO) — Pair Directory Sync with SSO to give your enterprise customers a complete identity management experience.
Webhooks — Set up webhook listeners to react to SCIM provisioning events in your application.
Roles & Permissions — Map synced groups to roles and permissions in your application for automated access control.