SCIM — Integration Guide

Overview

The scim subgraph is a dedicated Rust/Axum microservice that implements the SCIM 2.0 protocol (RFC 7643/7644) for automated user and group provisioning from enterprise Identity Providers — Okta, Azure AD, Google Workspace, and others.

Unlike the other subgraphs, the SCIM service is a pure REST API — it does not participate in the GraphQL federation or the Apollo gateway. Instead, it is called directly by the IdP using SCIM-standard bearer token authentication.

Key distinction: SCIM handles automated provisioning (IdP pushes user lifecycle changes). The Auth & Identity service handles interactive authentication (Visitors logging in). Together with Corporate Identity (SAML & SCIM), they form the enterprise identity stack.

Architecture at a Glance

Position in the Federation

┌──────────────────────────────────┐
│   IdP (Okta / Azure AD / Google) │
└──────────┬───────────────────────┘
           │ SCIM 2.0 REST
           │ Authorization: Bearer <scim_token>
           ▼
    ┌──────────────┐
    │  scim :3019  │  Rust/Axum — pure REST, no GraphQL
    └──────┬───────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐  ┌──────────────┐
│  auth   │  │organizations │
│  :3008  │  │  :3009       │
│ Postgres│  │  MongoDB     │
└─────────┘  └──────────────┘

The SCIM service:

1. Reads from the shared ngwenya_auth Postgres DB (users, scim_tokens)
2. Writes to the same DB (user creation, membership tracking)
3. Will call the Organizations service via HTTP for Team/Group operations

Core Concepts

SCIM Tokens

SCIM bearer tokens are per-Organization credentials generated via the Auth subgraph's GraphQL API. They allow an IdP to authenticate with the SCIM service on behalf of a specific Organization.

Token lifecycle:

1. Organization admin calls generateScimToken(orgId, label) on the Auth GraphQL API
2. Auth service generates a 48-character random token
3. A SHA-256 hash is stored in the scim_tokens Postgres table — the raw token is never persisted
4. The raw token is returned once to the admin
5. Admin pastes the token into their IdP's SCIM configuration
6. On every SCIM request, the service hashes the bearer token and looks up the hash

# Generate a SCIM token (Auth subgraph)
mutation {
	generateScimToken(orgId: "org-abc123", label: "Okta SCIM") {
		token # ← shown ONCE — copy it now
		id
		label
	}
}

# List active tokens
query {
	scimTokens(orgId: "org-abc123") {
		id
		label
		lastUsedAt
		createdAt
	}
}

# Revoke a token
mutation {
	revokeScimToken(orgId: "org-abc123", tokenId: "token-id")
}

SCIM User → Platform User Mapping

SCIM Group → Team Mapping

Groups in SCIM map to Teams in the Organizations service:

REST API Reference

Discovery Endpoints (No Auth Required)

User Endpoints (Bearer Token Required)

Group Endpoints (Bearer Token Required)

Request / Response Examples

Create a User

curl -X POST http://localhost:3019/scim/v2/Users \
  -H "Authorization: Bearer YOUR_SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jdoe@example.com",
    "name": { "givenName": "Jane", "familyName": "Doe" },
    "emails": [{ "value": "jdoe@example.com", "primary": true }],
    "active": true
  }'

Response (201 Created):

{
	"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	"id": "550e8400-e29b-41d4-a716-446655440000",
	"userName": "jdoe@example.com",
	"name": { "givenName": "Jane", "familyName": "Doe" },
	"emails": [{ "value": "jdoe@example.com", "primary": true }],
	"active": true,
	"meta": {
		"resourceType": "User",
		"created": "2026-04-08T22:00:00Z",
		"lastModified": "2026-04-08T22:00:00Z",
		"location": "/scim/v2/Users/550e8400-e29b-41d4-a716-446655440000"
	}
}

Filter Users

# Find user by email
curl -H "Authorization: Bearer TOKEN" \
  "http://localhost:3019/scim/v2/Users?filter=userName%20eq%20%22jdoe@example.com%22"

Deactivate a User (PATCH)

curl -X PATCH http://localhost:3019/scim/v2/Users/USER_UUID \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "replace", "path": "active", "value": false }]
  }'

Setting active: false removes the user from the Organization while preserving their platform account.

Error Handling

All errors follow the SCIM error schema (RFC 7644 §3.12):

{
	"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
	"detail": "Human-readable error message",
	"status": "404"
}

Database Schema

The SCIM service shares the ngwenya_auth PostgreSQL database with the Auth service. SCIM-specific tables are created by auth migrations:

Migration: apps/auth/migrations/20260408000000_saml_scim.sql

IdP Configuration Guides

Okta

1. Add → Application → SCIM 2.0 Test App
2. Set Base URL: https://scim.mallnline.com/scim/v2
3. Set Auth Mode: Bearer Token → paste SCIM token
4. Enable provisioning: Create Users, Update User Attributes, Deactivate Users
5. Test connector → verify green status

Azure AD

1. Enterprise Applications → New Application → Non-gallery
2. Provisioning → Automatic → Tenant URL: https://scim.mallnline.com/scim/v2
3. Secret Token: paste SCIM token
4. Test Connection → verify success
5. Start provisioning

Google Workspace

1. Apps → SAML Apps → Auto-provisioning
2. SCIM endpoint: https://scim.mallnline.com/scim/v2
3. Bearer token: paste SCIM token
4. Map attributes: email → userName

Environment Variables

File Reference

Testing

cd apps/scim && cargo test

Related

• Corporate Identity (SAML & SCIM) — Feature overview of the complete enterprise SSO stack (SAML SP + SCIM provisioning)
• Auth & Identity — Identity management, session lifecycle — hosts SCIM token generation and SAML endpoints
• Organizations & Permissions — The membership and team infrastructure that SCIM provisions into
• Teams & Sub-Groups — SCIM Groups map to Teams via the externalId field