SCIM User Provisioning

SCIM allows passbolt to integrate with Microsoft Entra ID (Azure AD) and Okta for automated user provisioning.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an open standard for managing user identities across different systems.

SCIM defines a schema for representing users and groups in JSON, along with API endpoints that identity providers can call to manage users. passbolt's initial SCIM implementation supports user management via /Users endpoints.

When you add, modify, or remove users in Microsoft Entra ID or Okta, the identity provider sends HTTP requests to passbolt's SCIM endpoints. passbolt processes these requests and updates its user records accordingly.

How SCIM Works with passbolt

The integration works in four steps:

Enable SCIM in passbolt settings to generate an endpoint URL and authentication token
Configure your identity provider (Microsoft Entra ID or Okta) with the SCIM URL and token
Map user attributes between your identity provider and passbolt
Users are automatically provisioned when added, modified, or removed in your identity provider

Prerequisites

You need:

Passbolt Pro Edition version 5.5 or later
Administrator access to passbolt
Access to Microsoft Entra ID or Okta
HTTPS enabled on your passbolt instance

HTTPS Required

SCIM requires HTTPS for secure communication.

Enable SCIM in passbolt

Access SCIM Settings

Log in as administrator
Go to Administration > User Provisioning > SCIM

Enable SCIM

Toggle Enable SCIM to activate the feature
passbolt generates a SCIM endpoint URL and an authentication token, and shows the token's expiry date in the Secret token expiry field
Click Save Settings to apply the configuration

Keep Your Token Secure

Store the authentication token securely and share only with authorised personnel.

SCIM Endpoint Information

When enabled, passbolt provides:

SCIM Endpoint URL:

https://your-passbolt-instance.com/scim/v2/<settings_id>

The <settings_id> is a unique identifier generated when SCIM is enabled.

Authentication Token: A token with format pb_[A-Za-z0-9_-]{43} (a pb_ prefix followed by 43 base64url characters, which may include - and _) sent as a Bearer token in the Authorization header.

Secret Token Expiry

The authentication token, labelled Secret token on the SCIM settings page, remains valid for the duration set by PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_EXPIRY, one year by default. Its expiry date is shown in the Secret Token expiry field. Since version 5.17.0, passbolt can also reject the requests of an identity provider that still uses an expired token.

Expiry States

The SCIM settings page shows how close the token is to its expiry date.

Within the warning window. From 14 days before the expiry date by default, the Secret token expiry field switches to a warning state with the message "This token is about to expire." A warning banner at the bottom of the page reads: "The SCIM secret token expires on date. To avoid service disruption, generate a new token and save it in your identity provider settings before the expiration date."

Expired. An error banner is shown at the bottom of the page. When the expiry is enforced, it reads: "The SCIM secret token expired and user provisioning has stopped. To resume service, generate a new token and save it in your identity provider settings." When the expiry is not enforced, which is the default, the banner reports the expired token with a different wording, since provisioning carries on.

The settings cannot be saved while the token is expired: the message "This token has expired." appears below the Secret token expiry field. Saving is also refused when that field is empty and the token has not been regenerated, with the message "Enter an expiry date, or regenerate the secret token." Regenerating the token clears both errors.

What Happens When the Token Expires

What passbolt does with a request that uses an expired token depends on whether the expiry is enforced. Enforcement is off by default, see Enforce the Expiry.

Behaviour	Expiry not enforced (default)	Expiry enforced
Request	Accepted, and a warning is written to the application log	Rejected with `401 Unauthorized`
User provisioning	The operation is performed	The operation is not performed
Administrators	Notified by email	Notified by email

Provisioning stops until the token is replaced

With enforcement on, every SCIM request fails once the token has expired. The identity provider cannot create, update, suspend or delete any user until you regenerate the token and save the new one in its settings.

Regenerate the Secret Token

Go to Administration > User Provisioning > SCIM
Click the regenerate button of the Secret Token field
Click Save Settings
Copy the new token into your identity provider: the Secret Token field under Admin Credentials in Microsoft Entra ID, or the API Token field in Okta

Regenerating clears the warning or error state and sets a new expiry date, using the duration set by PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_EXPIRY, one year by default.

Once the new token is saved in the identity provider, resume the operations that failed while the token was expired:

Microsoft Entra ID retries the failed operations on its next provisioning cycles. If the failures lasted long enough, Entra ID may have placed the application in quarantine.
Okta does not retry on its own. The failed operations are listed under Dashboard > Tasks: select them and click Retry Selected.

Administrator Notifications

passbolt emails every administrator when an identity provider request uses a token that is about to expire or already expired:

Trigger	Subject
A SCIM request uses a token within the warning window	"The SCIM secret token expires soon"
A SCIM request uses an expired token, whether the expiry is enforced or not	"The SCIM secret token is expired"

Each email is sent at most once every 24 hours. Both are automatic and cannot be disabled. End users are not notified.

Notifications depend on incoming requests

These emails are only sent when the identity provider calls passbolt. No reminder is scheduled on the passbolt side, so an identity provider that has stopped sending requests triggers no email. Keep an eye on the date shown in the Secret Token expiry field.

Enforce the Expiry

On self-hosted servers, turn enforcement on so that passbolt rejects the requests of an identity provider that still uses an expired token. The same block sets the warning window:

Package Installation
Docker

Open /etc/passbolt/passbolt.php and edit the plugins block:

'passbolt' => [
  'plugins' => [
      'scim' => [
          'security' => [
              'secretToken' => [
                  'enforceExpiry' => true,
                  'warningWindow' => '14 days',
              ],
          ],
      ],
  ],
],

Set the environment variables of the passbolt container:

PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_ENFORCE_EXPIRY: "true"
PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_WARNING_WINDOW: "14 days"

The warning window accepts the same format as the token validity: a number followed by a unit, such as '30 days' or '1 month'.

tip

Check the Secret token expiry field before turning enforcement on. If the token has already expired, regenerate it and update your identity provider first, otherwise provisioning stops as soon as the setting applies.

Available Endpoints

Endpoint	Description
`POST /scim/v2/<settings_id>/Users`	Create a new user
`GET /scim/v2/<settings_id>/Users/{id}`	Retrieve user information
`PATCH /scim/v2/<settings_id>/Users/{id}`	Partial user update
`DELETE /scim/v2/<settings_id>/Users/{id}`	Delete a user
`GET /scim/v2/<settings_id>/Users`	List users (with filtering)
`GET /scim/v2/<settings_id>/ServiceProviderConfig`	Get service provider configuration
`GET /scim/v2/<settings_id>/Schemas`	Get SCIM schemas

Supported Identity Providers

The initial SCIM release has been tested with:

Microsoft Entra ID (Azure AD)
Okta

Supported Operations

The initial SCIM release focuses on user provisioning and supports:

Operation	Method	Endpoint	Description
Create User	POST	`/scim/v2/<settings_id>/Users`	Create a new user
Read User	GET	`/scim/v2/<settings_id>/Users/{id}`	Retrieve user information
Partial Update	PATCH	`/scim/v2/<settings_id>/Users/{id}`	Partial user update
Delete User	DELETE	`/scim/v2/<settings_id>/Users/{id}`	Delete a user
List Users	GET	`/scim/v2/<settings_id>/Users`	List users with filtering

User Creation Process

When a user is created via SCIM:

User is created in passbolt with "invitation pending" status
Welcome email is sent to the user
User must complete account setup to activate their account
User receives a unique passbolt ID

User Updates

SCIM supports updating:

User names (givenName, familyName)
User status (active/inactive)
Username (userName field)

Email addresses cannot be updated for security reasons.

User Deletion

SCIM user deletion follows a two-phase process:

Phase 1 - Disable User:

When a user is deleted or unassigned in your identity provider, a PATCH request sets active: false
The user is disabled in passbolt (soft delete)
User can no longer access passbolt but data remains

Phase 2 - Permanent Deletion:

After 30 days, your identity provider sends a DELETE request
User is permanently deleted from passbolt
All user data is removed
User's private key and secrets are deleted

Exception - Cannot Delete: If the user cannot be deleted (e.g., sole owner of shared resources), the user is disabled and an administrator must resolve the issue manually, for example by reassigning ownership of the shared resources before deleting the user.

Two-Phase Deletion

User deletion occurs in two phases: first disable, then permanent deletion after 30 days. Users who cannot be deleted remain disabled until manually resolved.

Administrator Accounts

Since passbolt 5.11.0, a SCIM request that would suspend an administrator is rejected with an HTTP 403 error by default, to protect against administrator lockout through a compromised or misconfigured identity provider. Phase 1 of the deletion flow therefore fails for administrator accounts, and the identity provider reports a provisioning error for that user. To allow the identity provider to suspend administrators, set the PASSBOLT_PLUGINS_SCIM_SECURITY_ALLOW_SUSPEND_ADMINISTRATORS environment variable to true on a self-hosted server.

Environment Variables

On self-hosted servers, SCIM behaviour can be tuned with environment variables:

Variable	Default	Description
`PASSBOLT_PLUGINS_SCIM_ENABLED`	`true`	Enable the SCIM plugin
`PASSBOLT_PLUGINS_SCIM_LOG_SCIM_REQUESTS`	`false`	Log incoming SCIM requests, useful for troubleshooting
`PASSBOLT_PLUGINS_SCIM_SECURITY_ALLOW_SUSPEND_ADMINISTRATORS`	`false`	Allow the identity provider to suspend administrator accounts
`PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_COST`	`12`	Bcrypt cost factor for hashing the authentication token
`PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_LEGACY_HASH_ALLOWED`	`true`	Accept tokens hashed with the pre-5.10.0 legacy format
`PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_EXPIRY`	`1 year`	How long the authentication token remains valid
`PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_ENFORCE_EXPIRY`	`false`	Reject SCIM requests that use an expired authentication token
`PASSBOLT_SCIM_SECURITY_SECRET_TOKEN_WARNING_WINDOW`	`14 days`	How long before the expiry date the warnings start

See the environment variables reference for details on each variable, including the version each one became available in.

Limitations

Email Address Changes Email address updates are not supported. SCIM requests to update email addresses are rejected with error 422 Unprocessable Entity and scimType: mutability.

Group Sync Group synchronisation is not supported. To add users to groups, group managers must manually share credentials to ensure end-to-end encryption.

Bulk Operations SCIM bulk operations are not supported ("bulk": { "supported": false } in ServiceProviderConfig). Identity providers must send individual API requests for each user operation.

Password Management Password changes are not supported. passbolt does not store user passwords - authentication is handled through cryptographic key pairs.

Custom Attributes Only standard SCIM user attributes are supported. Custom schemas and resource extensions are not available.

Token Rotation The authentication token is not rotated automatically. Regenerate it before its expiry date and update your identity provider, see Regenerate the Secret Token.

Comparison with LDAP Directory Sync

Feature	LDAP Directory Sync	SCIM User Provisioning
Target Systems	On-premises Active Directory, OpenLDAP	Cloud identity providers (Azure AD, Okta)
Protocol	LDAP	HTTP/HTTPS REST API
Real-time Updates	Scheduled synchronisation	Near real-time provisioning
User Management	Full user and group sync	User provisioning only
Group Management	Supported	Not supported
Setup Complexity	Moderate	Simple
Network Requirements	Direct LDAP connection	HTTPS connectivity only

Next Steps

To get started with SCIM user provisioning:

Configure your identity provider (Microsoft Entra ID or Okta)
Test the integration with a small number of users
Monitor the provisioning process and review logs
Troubleshoot any issues that arise

What is SCIM?​

How SCIM Works with passbolt​

Prerequisites​

Enable SCIM in passbolt​

Access SCIM Settings​

Enable SCIM​

SCIM Endpoint Information​

Secret Token Expiry​

Expiry States​

What Happens When the Token Expires​

Regenerate the Secret Token​

Administrator Notifications​

Enforce the Expiry​

Available Endpoints​

Supported Identity Providers​

Supported Operations​

User Creation Process​

User Updates​

User Deletion​

Environment Variables​

Limitations​

Comparison with LDAP Directory Sync​

Next Steps​