This guide covers setting up the module and connecting an identity provider (IdP). For the architecture and development setup see ?#developer.

1. Install and enable

1. Install the module from the HumHub Marketplace (or drop it into your modules directory).
2. Enable it at Administration → Modules → SCIM.
3. Open the admin page via the Configure button on that module — or go directly to /scim/admin.

2. Create a tenant

A tenant is one IdP connection. Each tenant has its own endpoint URL, bearer token and attribute mapping.

1. On /scim/admin, click Create tenant.
2. Give it an id (lower-case, used in the URL — e.g. entra) and a name.
3. Pick a provider preset — this seeds a sensible default attribute mapping:
   • Microsoft Entra ID
   • Okta
   • OneLogin
   • Google Workspace
   • Generic SCIM provider
4. Submit. The bearer token is shown exactly once — copy it now. Only its hash is stored; if you lose it, rotate the token to get a new one.

3. Connect your IdP

In your IdP's provisioning / SCIM connector, enter:

The exact endpoint URL is also displayed on the tenant edit page. The IdP will verify the connection against /ServiceProviderConfig and then start syncing.

4. Attribute mapping

Each tenant maps HumHub profile fields to SCIM attributes as a newline-separated list on the tenant edit page. The preset fills this in; adjust it to match your profile fields.

Each line is one of:

• A bare HumHub field — resolves automatically:
  • the core fields firstname, lastname, title, externalId map to their standard SCIM paths;
  • language maps to preferredLanguage, time_zone to timezone;
  • any other HumHub profile field maps to the HumHub SCIM extension urn:humhub:scim:2.0:User.

• field=>scimPath — maps a HumHub field to an explicit SCIM path, e.g. the enterprise extension:

  department=>urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
  

Notes:

• The list is taken literally — it is the complete set of mapped fields, not a set of overrides on top of a default.
• userName, the primary email, active (enabled/disabled) and password have fixed handling and are always mapped — you do not list them.
• Select / checkbox profile field types are not yet supported; use plain text-like fields (Text, TextArea, Number, Date).

5. Tenant options

On the tenant edit page:

• Enabled — turn provisioning for this tenant on or off. A disabled tenant rejects new requests; already-provisioned users keep their accounts.
• Restrict to auth clients — limit this tenant's users to a chosen set of HumHub auth clients (login + attribute sync). Leave all unchecked to allow every configured client.
• Password provisioning — if the tenant's allowed clients include the local password client, a password sent by the IdP is stored as the user's HumHub password (write-only, never returned). The IdP's value is stored as-is; HumHub's local password-strength rules are not enforced.
• Adopt existing users (migration) — when on, a create for a user whose primary email matches an existing non-SCIM HumHub user adopts that account instead of failing: it becomes SCIM-managed and the IdP is authoritative from then on. Users already owned by any SCIM tenant, soft-deleted and pending-approval users are never adopted. Use this for LDAP → SCIM migrations: turn it on for the migration window, let the IdP sync adopt the accounts, then turn it off. Off by default.
• Log SCIM requests — logs each incoming request for this tenant at warning level under the scim.requests category (method, path, status, body with password redacted). Useful when debugging an IdP integration. Off by default.

6. Groups

When the IdP provisions groups, each SCIM group is mapped to a HumHub group and its membership is kept in sync. Members are referenced by their SCIM user id and restricted to users the same tenant provisioned — a tenant can never touch identities it does not own.

Group creation is strict: a 409 uniqueness is returned if a HumHub group with the same name already exists, so an IdP never silently takes over a pre-existing group (e.g. the admin or default group). SCIM-managed groups are labelled SCIM Managed Group (<tenant name>): <externalId> in the HumHub group list.

7. Managing tenants

• Rotate token — generates a new bearer token and invalidates the old one. The new token is shown once; update it in the IdP.
• Delete tenant — refused while the tenant still has provisioned users. To clean out a tenant first, run the console command below, then delete it in the UI.

8. Console commands

Run from the HumHub protected/ directory:

# Create an enabled tenant and print its bearer token once
./yii scim/create-tenant <id> <name>

# List and hard-delete every user and group a tenant provisioned
# (prompts for confirmation) so the tenant can be removed
./yii scim/delete-users <tenant-id>

9. Known limitations

Some deviations are forced by HumHub's data model and are expected:

• One email per user — HumHub stores a single email address. An IdP that pushes multiple emails entries only round-trips the primary work address; the others are dropped.
• Limited preferredLanguage set — only languages installed in HumHub are accepted. An unrecognised locale falls back to its base language (it-IT → it) or is ignored, so a POST/PATCH stays non-destructive.

Both surface as failures in the Microsoft SCIM Validator even on an otherwise-green run, which is expected.