User provisioning

HarborGuard provisions users from your identity provider through JIT (just-in-time) provisioning at SSO sign-in. SCIM 2.0 push provisioning is on the roadmap — the bearer-token scaffolding exists in Settings -> Security -> SCIM so you can pre-generate a token, but the protocol endpoints are not yet generally available.

This page covers the JIT path you can use today and the IdP-side preparation that will let you switch on SCIM with no app-side reconfiguration when it ships.

JIT provisioning via SSO

Every successful SAML or OIDC login runs the provisioning pipeline:

1. The user is looked up by idpSubjectId. If not found, a HarborGuard user is created with provisionedBy = "sso" and status = "active".
2. idpGroups is replaced with the latest group claims from the SSO assertion.
3. The first matching entry in Role mappings assigns the role and (optionally) a team.
4. If no mapping matches, the user gets the org's default role (Viewer unless changed).

This covers the vast majority of provisioning needs:

• New employee in Okta gets the right role on their first HarborGuard sign-in.
• Group changes propagate on the next sign-in (reassignments take effect within the IdP's session lifetime).
• Suspensions in the IdP block sign-in immediately; revoke active sessions from Settings -> Security -> Sessions if you also want to terminate live sessions.

Limit: JIT cannot deactivate a user who never signs in again. For headless API consumers (CI service accounts), use a dedicated organization API key instead of a user-tied PAT, and revoke the key when the workload is decommissioned.

Group-to-role mapping

Configure mappings under Settings -> Security -> Role mappings:

Mapping rules:

• Mappings are evaluated in order; the first match wins.
• Group names must match the IdP's claim value exactly (case-sensitive).
• Removing a user from harborguard-admins causes them to fall back to the next matching mapping (or the default role) on their next sign-in.
• Mappings are scoped to the org; cross-org propagation does not happen.

Preparing the IdP for SCIM 2.0

You can complete the IdP-side preparation today so SCIM provisioning can be enabled without further IdP changes when the protocol endpoints ship.

Generate the bearer token

In Settings -> Security -> SCIM, click Generate token. The token is shown once and must be copied immediately. Store it in your IdP's secret manager. Rotation is supported any time from the same panel; rotation is recorded as settings.scim.token_regenerated in the audit log.

Okta — Provisioning tab (preparation)

Microsoft Entra ID — Provisioning (preparation)

When SCIM 2.0 lands, switching it on is a single toggle in HarborGuard plus a Test Connection in the IdP — no token regeneration required.

Manual sync

Settings -> Security -> SCIM -> Sync now is wired to your IdP's "provision on demand" affordance for the JIT path: it triggers a no-op response on HarborGuard's side and prompts your IdP to re-issue the next provisioning cycle. Until SCIM 2.0 ships, the practical effect is to remind admins to wait for the next interactive sign-in to flush group changes.

Audit trail

All provisioning events are written to the audit log:

• sso.user.provisioned — JIT created a new user.
• sso.user.linked — JIT matched an existing user by idpSubjectId or email.
• member.role_changed — role mapping assigned a different role on this sign-in.
• settings.scim.token_regenerated — SCIM bearer token rotated.

See Audit log for the full event catalog.