@maroonedsoftware/scim

SCIM 2.0 (RFC 7643/7644) server toolkit for ServerKit.

This package provides the protocol layer — schemas, filter parser, PATCH applier, error envelope, and a Koa router — for building a SCIM server. Resource storage is left to the consumer via abstract repositories, matching the pattern used by @maroonedsoftware/authentication and @maroonedsoftware/permissions.

What's included

• Resource schemas — User, Group, and the EnterpriseUser extension (RFC 7643).
• Filter parser — full SCIM filter grammar (RFC 7644 §3.4.2.2) returning a typed AST.
• PATCH applier — add / replace / remove ops with the path mini-language (RFC 7644 §3.5.2).
• Error envelope — scimError(status, scimType?) builder producing the SCIM error JSON.
• Abstract repositories — ScimUserRepository, ScimGroupRepository. The consumer implements these against their datastore.
• Services — ScimUserService, ScimGroupService, ScimServiceProviderService.
• Koa middleware — scimErrorMiddleware(), scimContentTypeMiddleware(), requireScimScope(scope).
• Router factory — createScimRouter(options) mounting the standard SCIM endpoints.

Quick start

import Koa from 'koa';
import { ServerKitContext, serverKitContextMiddleware, authenticationMiddleware } from '@maroonedsoftware/koa';
import { createScimRouter, ScimUserRepository, ScimGroupRepository, scimErrorMiddleware } from '@maroonedsoftware/scim';

class MyScimUserRepository extends ScimUserRepository {
  // implement against your datastore
}

class MyScimGroupRepository extends ScimGroupRepository {
  // implement against your datastore
}

const app = new Koa();
app.use(serverKitContextMiddleware(container));
app.use(authenticationMiddleware());

const scimRouter = createScimRouter({
  userRepository: new MyScimUserRepository(),
  groupRepository: new MyScimGroupRepository(),
  basePath: '/scim/v2',
  serviceProviderConfig: {
    documentationUri: 'https://example.com/scim/docs',
    patch: { supported: true },
    bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
    filter: { supported: true, maxResults: 200 },
    changePassword: { supported: false },
    sort: { supported: true },
    etag: { supported: false },
  },
});

app.use(scimErrorMiddleware());
app.use(scimRouter.routes());

Authentication

This package does not validate bearer tokens itself. It reads ctx.authenticationSession (populated by authenticationMiddleware() from @maroonedsoftware/koa) and provides a requireScimScope(scope) guard that checks for SCIM scopes on session.claims.scimScopes. You register an AuthenticationSchemeHandler in your app that turns IdP-issued bearer tokens into a session.

Compliance testing

The router has been designed against RFC 7643/7644. To validate against a real IdP, point Okta or scim2-compliance-test-utils at a sample app that mounts createScimRouter.