Feature - SCIM Connector

[sam]

Overview

SCIM (System for Cross-domain Identity Management) lets an external Identity Provider (Entra ID, Okta, etc.) push user and group lifecycle changes into eramba over its API. The IdP is the source of truth - it creates, updates, deactivates and deletes users without anyone touching eramba directly.

Authentication

• Currently the IdP authenticates against the eramba SCIM endpoint using Basic Auth, with the active local credentials of the configured user.
• Missing - Credentials should belong to a dedicated SCIM service account, not a real person’s account. Machine-to-machine integrations must not be tied to an individual user - when that person changes their password, gets MFA, or is deactivated, the whole sync breaks. A service account also keeps the audit trail clean (changes are attributed to SCIM, not to a named admin).
• Bearer token would be the better long-term auth method. It is the de-facto standard for SCIM — most IdPs (Okta, Entra, OneLogin) natively expect a “SCIM endpoint URL + API token” pair, and Basic Auth is the less-supported / less-recommended path. A token decouples the integration from any user account entirely.
• One global SCIM config per instance. Multiple connections per instance is not how permission tiers are modelled - see Permission model below.

SCIM users are remote users

• Any user provisioned through SCIM is automatically flagged as a remote user - same concept as LDAP-synced users. They are owned by the IdP, not by eramba.
• The Local Account toggle stays off for these users.
• The IdP is authoritative for their profile and lifecycle.

Editable vs non-editable - needs to be decided

• A setting controls whether SCIM-provisioned (remote) users can be edited locally inside eramba or are locked / read-only.
• Locked is the cleaner default: prevents local drift, anything changed in eramba would be overwritten on the next sync anyway, and keeps the IdP as single source of truth.
• Editable can be allowed where a customer wants to manage some fields locally — but those fields then risk being overwritten by the IdP.

Permission model

Different users need different access (Awareness only, GRC reader, GRC admin, etc.). We need a way to derive those permissions from what the IdP sends us. Three options were considered:

• Custom SCIM attribute on user (e.g. portal: "awareness") - rejected. Forces customers to define eramba-specific attributes in their IdP. Out of step with how mainstream SaaS products (Slack, GitHub Enterprise, data.world, Databricks) handle this.
• Multiple SCIM connections per permission tier - rejected. Architectural overhead (N endpoints, N service accounts, N audit trails). Users can only belong to one connection at a time, so promotions become delete+create. The customer admin has to manually decide which IdP application a user is assigned to.
• Single connection, IdP groups mapped to eramba groups - chosen. Standard pattern across the SaaS landscape.

Why eramba group, not User Template

User Templates in eramba are a one-time starting profile - once a user is modified, they fall out of the template. This makes templates incompatible with continuous SCIM-driven permission management, especially for users in multiple groups (a second group’s settings would immediately drop them from the first group’s template).

Eramba groups are additive - a user can be a member of multiple groups, and permissions are unioned through Access Control. This matches how SCIM Group membership works natively and how eramba already handles authorisation.

Portal access

• Portal access (Main, Awareness, Vendor Assessments, Account Reviews, Policy, REST APIs) is not a native SCIM attribute and is not pushed directly by the IdP.
• It is derived from eramba group membership: the eramba group a user lands in determines their portal access and permissions.
• Portal access is configured per-eramba-group as a one-time setup and inherited by all SCIM users who become members of that group through their IdP group membership.
• Keeps the SCIM payload on clean core schema (User + Group only) - no custom schema extension required, and the IdP admin only manages group assignment.

Group bootstrap and mapping

On a clean instance eramba has no knowledge of what groups exist in the customer’s IdP. SCIM is push-only from the IdP, so eramba cannot pull a group list - the bootstrap therefore happens after the first SCIM sync, not before. This is the same pattern Slack, GitHub Enterprise and data.world use.

Flow

1. IdP admin (Entra / Okta) assigns groups to the SCIM application. In Entra: “Assigned users and groups” or “Sync only assigned users and groups”. In Okta: the “Push Groups” tab.
2. First SCIM sync pushes the groups to eramba as POST /Groups. Group memberships arrive separately as PATCH /Groups/{id} with member operations.
3. Eramba processes the incoming groups based on the Allow group creation toggle:
   • Toggle ON: eramba auto-creates the group locally using displayName from the IdP, with default-deny permissions (all portals off, no permissions). Admin then opens the group and configures its access.
   • Toggle OFF: the group lands in a “pending mapping” list in the SCIM Connections UI. Admin must explicitly map it to an existing eramba group, or create one for it. Useful when the customer already has an eramba group structure to keep.
4. Admin configures portal access and permissions per group - one-time. From this point on, any user assigned to the group in the IdP automatically inherits this access.
5. Users flow continuously via POST /Users + PATCH /Groups/{id} member operations. New users in already-configured groups become active immediately with the correct permissions.

Edge case - user with no mapped group

When a user arrives via SCIM but none of their groups are configured in eramba yet:

• Default behaviour: user is created as a remote user but left inactive (Status: inactive). Admin sees a clear signal in the UI (“N users awaiting group configuration”) and can resolve it.
• Optional fallback: an admin-configurable “Default group” on the SCIM connection. If set, unmapped users land in this group automatically (typically read-only or Awareness-only). Customers who want strict default-deny leave it unset.

We don’t reject the user with an error response - that would cause IdP retry loops and noise for SCIM admins.

Bulk re-apply

When admin assigns portal/permissions to an already-existing group (or maps an incoming group to an eramba group), eramba recomputes access for all existing members of that group, not only for new users provisioned afterwards.

Group management

• Manage groups - master switch for SCIM group operations.
• Allow group creation - controls the bootstrap branch (auto-create vs pending mapping). See above.
• Allow group deletion - controls whether SCIM DELETE /Groups/{id} removes SCIM-managed groups from eramba.

Delete behaviour

• active = false from the IdP → the user is deactivated in eramba (status), the record is kept.
• A SCIM delete is a separate operation → a configurable fallback user inherits the deleted user’s assignments where eramba needs a replacement owner.

Attribute mapping

SCIM attribute (core schema)	eramba field	Tab
name.givenName	Name	General
name.familyName	Surname	General
emails[primary]	Email	General
userName	Login Name	General
active	Status	Permissions
Groups (members)	Groups → portal + permissions	Permissions / Portals & Access
— (not pushed)	Portal access	Portals & Access (derived from group)
— (always off)	Local Account	General

Provisioning workflow

1. IdP pushes a change to the eramba SCIM endpoint via the SCIM API.
2. eramba authenticates the request against the SCIM service account credentials.
3. Branch on the SCIM operation type:
   • Create / Update → map core attributes to eramba fields, flag user as remote (editable or locked per setting), derive portal access + permissions from the user’s eramba group memberships. User is provisioned and the action is written to the audit log. If no group is mapped yet, user is created inactive (see Edge case - user with no mapped group).
   • active = false → deactivate the user, keep the record.
   • Delete → reassign the user’s ownerships to the fallback user, then remove.

UI

Open questions

• Editable vs non-editable granularity - one global toggle for the whole connector, or per-field control (e.g. name locked but portal editable)?
• SCIM service account type - should it be its own non-interactive account type (no UI login, not counted as a normal user), or just a regular user with a recommendation in the documentation?
• Sync status visibility - what does the SCIM Connections UI show after a sync? Minimum: last sync timestamp, count of received groups/users, list of pending unmapped groups, list of inactive users awaiting group configuration. Full SCIM operation log view can be a follow-up.

Not implementing / Not contemplated

• OAuth 2.0 client credentials grant authentication (bearer token is the first step up from Basic Auth).
• SCIM /Schemas discovery endpoint - useful for IdPs that auto-detect attributes, not strictly required for v1.
• Custom SCIM schema extensions for eramba-specific attributes (intentionally avoided per Permission model rationale).
• Pre-sync group discovery via separate IdP-specific APIs (Microsoft Graph, Okta API) - would be a second integration.
• Multiple SCIM connections per instance.

ref.: Question - Auto-Provisioning Users via SCIM

int. ref.: Jira