# Enterprise Provisioning & SCIM Roadmap

> **Purpose:** Extend enterprise identity from federation-only to full lifecycle
> provisioning, deprovisioning, group sync, and seat governance.
>
> **Primary Surface:** `services/platform-service/src/modules/auth/enterprise/`
>
> **Status:** Planned
>
> **Estimated Effort:** 2-3 weeks

---

## Why This Is Missing

The platform already has enterprise SAML and OIDC federation. That solves login.
It does not solve enterprise lifecycle management:

- just-in-time user provisioning policies
- SCIM user sync
- group sync
- deprovisioning
- seat and entitlement mapping

---

## Recommended Stack

- Extend `platform-service` enterprise auth
- SCIM 2.0 endpoints in Fastify
- org/workspace mapping from the tenant model
- optional background sync jobs using `@bytelyst/queue`

### Default Decision For This Repo

- Keep enterprise provisioning in `platform-service`
- Implement SCIM only after org/workspace/team exists
- Use queued reconciliation jobs for drift repair and large sync batches

---

## Dependencies

- Org, Workspace & RBAC
- Durable Event Bus & Worker Runtime

---

## V1 Non-Goals

- Supporting every optional SCIM feature extension
- Bi-directional identity sync with every enterprise system
- Full HRIS integration

---

## Phase 1 - SCIM Foundations

- [ ] Add SCIM service provider config endpoint
- [ ] Add SCIM resource schemas
- [ ] Add endpoints for:
  - [ ] `/scim/v2/Users`
  - [ ] `/scim/v2/Groups`
  - [ ] PATCH
  - [ ] deactivate
- [ ] Add enterprise API tokens and audit logs

---

## Phase 2 - Provisioning Rules

- [ ] Map SCIM users to org/workspace memberships
- [ ] Map groups to roles or teams
- [ ] Support seat assignment and revocation
- [ ] Add deprovision grace policy

---

## Phase 3 - Admin Controls

- [ ] Admin UI for provisioning state and sync errors
- [ ] reconciliation jobs
- [ ] audit exports
- [ ] break-glass override flows

---

## Tech Stack Options

| Option                          | Pros                                | Cons                                 | Fit                               |
| ------------------------------- | ----------------------------------- | ------------------------------------ | --------------------------------- |
| Native SCIM in platform-service | Full control, strong enterprise fit | Must implement spec carefully        | Best long-term                    |
| IdP proxy product               | Faster setup                        | External dependency and less control | Acceptable only if needed quickly |
| JIT only                        | Minimal effort                      | Not enough for enterprise IT         | Inadequate                        |

---

## Risks

- Enterprise login without enterprise provisioning still creates admin pain
- Group mapping drift leads to incorrect access
- Deprovision lag is a real security risk
