SCIM provisioning with Entra ID and Okta

Declare the attributes you will receive

Directory fields become typed identity attributes, which policies read as principal.{name}. Declare the ones you map in the options module:

export default {
  // ...database, secret, baseURL, authentication, resourceTypes, resolveResource
  permissions: {
    resourceTypes: {
      project: { actions: ['projects:read', 'projects:write', 'projects:delete'] },
    },
    identityAttributes: { title: 'string', department: 'string', costCenter: 'string' },
  },
};

Mount the SCIM service

npm i @better-iam/scim

Create the service with the host callbacks from iam.protocolHost, put both of its route sets under the IAM route that Next.js serves (/api/iam), and mount it:

import { betterIam } from '@better-iam/server';
import { createScimService } from '@better-iam/scim';
import config from '../better-iam.config.mjs';

export const iam = betterIam(config);

export const scim = createScimService({
  ...iam.protocolHost,
  basePath: '/api/iam/scim/v2',
  adminBasePath: '/api/iam/scim-admin',
  mapAttributes: ({ title, enterprise }) => ({
    ...(title ? { title } : {}),
    ...(typeof enterprise?.department === 'string' ? { department: enterprise.department } : {}),
    ...(typeof enterprise?.costCenter === 'string' ? { costCenter: enterprise.costCenter } : {}),
  }),
});
iam.useProtocol(scim);

Add @better-iam/scim to serverExternalPackages in next.config.mjs next to @better-iam/server.

ProvisionedUser carries userName, displayName, externalId, active, title, emails, name, and enterprise (the enterprise extension object).

Forward every SCIM method

The IAM API needs only GET, POST, and OPTIONS, but identity providers also send PUT, PATCH, and DELETE to update, deactivate, and delete. Forward them to the same handler:

import { iamNext } from '@/lib/iam-next';

export const runtime = 'nodejs';

const handlers = iamNext.handlers();
export const GET = handlers.GET;
export const POST = handlers.POST;
export const OPTIONS = handlers.OPTIONS;
// SCIM updates, deactivations, and deletions.
export const PUT = handlers.POST;
export const PATCH = handlers.POST;
export const DELETE = handlers.POST;

Each export calls the IAM handler with the request unchanged, whatever its method. The edge middleware's default protect (from createIamMiddleware) leaves /api/iam public, so the directory's requests reach the route without a session cookie; a custom protect must do the same.

Create a connection

A connection is one directory's credential for one organization. Acme's administrator creates it on your provisioning settings page and copies two values into their directory: the connection's URL and its bearer token.

'use server';
import { iam, scim } from '@/lib/iam';
import { iamNext } from '@/lib/iam-next';

export async function createScimConnection(name: string) {
  const session = await iamNext.requireSession();
  const connection = await scim.createConnection(await iamNext.credential(), {
    tenantId: session.session.tenantId,
    name,
    expiresIn: 180 * 86400, // seconds; 60 seconds to one year, 90 days when omitted
  });
  return {
    url: `${iam.endpoint.origin}${connection.path}`, // https://app.example.com/api/iam/scim/v2/{id}
    token: connection.token, // shown once: display it, never store it
    expiresAt: connection.expiresAt,
  };
}

createConnection requires iam:scim:connections:create. The token is stored only as a hash, is restricted to this connection and tenant, and expires after expiresIn seconds. iam.endpoint.origin is the origin from baseURL.

The same call is available to browser code as POST /api/iam/scim-admin/connections/create, which needs the session cookie, X-Better-IAM: 1, and a JSON body.

Configure the directory

Give the directory administrator the connection URL and token, and have them enter these values. The field names are the ones the directory's admin console shows; consoles rename fields between versions, so match them by meaning.

The directory first searches for each person (GET /Users?filter=userName eq "..."), creates the ones missing, and then keeps them updated. Every request runs in one transaction, and the connection's lastUsedAt is updated at most once a minute, so the settings page can show whether the directory is still calling.

Map attributes

A SCIM user becomes an identity in the organization. Better IAM stores the fields below:

The enterprise extension schema is urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Everything else directories commonly send is accepted and dropped, in creates, replaces, and PATCH operations alike:

• Read-only attributes (id, meta, groups), which directories echo back in a PUT. RFC 7644 says to ignore them, so they are ignored whatever unsupportedAttributes says. A PATCH whose path targets one (replace meta.created) still fails with 400.
• Core User attributes Better IAM does not store: nickName, profileUrl, userType, preferredLanguage, locale, timezone, password, phoneNumbers, ims, photos, addresses, entitlements, roles, and x509Certificates. A PATCH such as replace phoneNumbers[type eq "work"].value is skipped while the rest of the request applies.
• Extension schemas other than the enterprise extension, such as a custom Okta extension. Their URN is left out of the stored schemas.

An attribute no supported schema defines (a typo such as titel, or badge inside the enterprise extension) still fails with 400 and scimType: mutability, so mapping mistakes surface in the directory's provisioning log. Set unsupportedAttributes: 'reject' to refuse unstored attributes the same way.

The mapped attributes drive policy conditions, for example StringEquals: { 'principal.department': 'Finance' }. See Conditions.

Map groups to roles

A directory group carries no authority by itself: the directory decides who is in "Engineering", and an administrator of your product decides what "Engineering" may do. After the directory has pushed its groups, list them and map each to roles:

'use server';
import { scim } from '@/lib/iam';
import { iamNext } from '@/lib/iam-next';

export async function listPushedGroups(connectionId: string) {
  const session = await iamNext.requireSession();
  // [{ id, groupId, displayName, externalId?, members, roleIds }]
  return scim.listGroups(await iamNext.credential(), { tenantId: session.session.tenantId, connectionId });
}

export async function mapGroupToRoles(connectionId: string, scimGroupId: string, roleIds: string[]) {
  const session = await iamNext.requireSession();
  await scim.setRoleMappings(await iamNext.credential(), {
    tenantId: session.session.tenantId,
    connectionId,
    groupId: scimGroupId, // the SCIM group's `id` from listGroups, not the local groupId
    roleIds, // replaces the group's mapped roles; at most 100
  });
}

• setRoleMappings needs iam:scim:mappings:update on the connection and iam:bindings:create on every role, so nobody can map a role they could not grant directly. Protected roles, such as Owner, are refused.
• The mapping creates group bindings under the administrator's grant authority. Joining the group in the directory then grants the roles here, and leaving it removes them.
• The SCIM token can only move people in and out of groups an administrator mapped. It cannot create roles, policies, or bindings itself.
• Nested groups are not supported, and a group's members must belong to the same connection (up to 1000 member references per request).

Know what deprovisioning does

Directories end access in two ways: they deactivate (active: false) when someone is disabled or unassigned, and some later delete the user. Better IAM handles both:

• Protected identities. Owners and root administrators cannot be changed by SCIM (403 mutability), so a directory mistake cannot lock the organization out.
• Administrator deletions win. An identity an administrator deleted is never updated, reactivated, or re-added to groups by SCIM. A SCIM DELETE of it still succeeds.
• Manager links. Deleting a manager through SCIM releases the reports SCIM linked to them.

To end everything else a leaver holds in one audited step (role bindings outside mapped groups, group memberships, and owned resources handed to a successor), run identities.offboard as well. The Enterprise onboarding walkthrough shows how a SCIM deactivation reaches downstream apps and OAuth clients.

Rotate or revoke the token

Tokens expire; put a reminder on expiresAt, or rotate earlier after a leak or a staff change:

'use server';
import { scim } from '@/lib/iam';
import { iamNext } from '@/lib/iam-next';

export async function rotateScimToken(connectionId: string) {
  const session = await iamNext.requireSession();
  const rotated = await scim.rotateToken(await iamNext.credential(), {
    tenantId: session.session.tenantId,
    connectionId,
  });
  return { token: rotated.token, expiresAt: rotated.expiresAt }; // paste into the directory at once
}

export async function stopProvisioning(connectionId: string) {
  const session = await iamNext.requireSession();
  await scim.revokeConnection(await iamNext.credential(), { tenantId: session.session.tenantId, connectionId });
}