ScimGroupsController

Kind: Controller

Source: atloria-monorepo/apps/api/src/scim/scim-groups.controller.ts

SCIM 2.0 Groups endpoint (virtual, Phase-2). Backed by ScimGroupMapping — group membership propagates the mapped role/audience onto member users. Kept minimal on purpose: Okta provisions Users-only just fine.

ScimGroupsController exposes the SCIM 2.0 Groups endpoint for identity providers such as Okta. It manages virtual groups backed by ScimGroupMapping, where group membership causes the mapped role or audience to be propagated to member users. The controller is intentionally minimal because user-only provisioning remains the primary supported SCIM workflow.

Diagram

mermaid
graph LR
  IdP[Identity Provider<br/>Okta] -->|SCIM Groups requests| Controller[ScimGroupsController]
  Controller --> Mapping[ScimGroupMapping]
  Mapping --> Role[Mapped Role / Audience]
  Controller --> Members[Group Member Users]
  Role --> Members

Usage

ts
const response = await fetch("https://api.example.com/scim/v2/Groups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCIM_BEARER_TOKEN}`,
    "Content-Type": "application/scim+json",
  },
  body: JSON.stringify({
    schemas: ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    displayName: "Support Team",
    members: [
      {
        value: "user-scim-id-123",
        display: "support@example.com",
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Unable to provision SCIM group: ${response.statusText}`);
}

const group = await response.json();
console.log(group.id);

AI Coding Instructions

• Preserve SCIM 2.0 request and response conventions, including SCIM media types, schemas, IDs, and member payload shapes.
• Treat groups as mappings rather than independent authorization records; membership changes must remain synchronized with ScimGroupMapping.
• Ensure mapped roles or audiences are propagated consistently when members are added, removed, or updated.
• Keep the endpoint intentionally minimal and compatible with IdPs that primarily provision users, especially Okta.
• Avoid introducing group behavior that bypasses existing user, role, audience, or SCIM authentication flows.

Relationships

• MODULE_DECLARES → list
• MODULE_DECLARES → get
• MODULE_DECLARES → create
• MODULE_DECLARES → patch
• DEPENDS_ON → ScimService

Referenced By

• ScimModule (MODULE_DECLARES)