Outbound provisioning/sync user to external systems and applications (SCIM client)

[mffap]

As an administrator, I want to configure outbound SCIM provisioning for users, manage SCIM servers, and define which users are provisioned to external systems, so that I can ensure users exist in external applications before SSO login attempts and maintain consistent user lifecycle management across multiple applications.

Description:

To support applications that require user pre-existence for SSO login and to enable consistent lifecycle management across multiple applications, we need to implement outbound SCIM provisioning for users.
This feature will allow administrators to configure SCIM servers, define which users are provisioned to external systems, and automatically synchronize user data.
By ensuring users exist in external systems before SSO login attempts, we can streamline the login process and prevent authorization issues.
Furthermore, by synchronizing user lifecycle events (e.g., deactivation, deletion), we can ensure that user access is consistently managed across all applications. The initial implementation will focus on the user resource.

Acceptance Criteria

• SCIM Server Management:
  • Given: An administrator wants to configure outbound SCIM provisioning.
  • Then: The system should provide a management interface for SCIM servers, allowing administrators to:
    • Add new SCIM server configurations.
    • Configure SCIM server endpoints (URL).
    • Configure authentication credentials (e.g., API keys, tokens).
    • Test SCIM server connectivity.
    • Edit and delete existing SCIM server configurations.
• User Provisioning Configuration:
  • Given: An administrator wants to define which users are provisioned.
  • Then: The system should provide configuration options to:
    • Select specific users or groups of users to be provisioned.
    • Define attribute mappings between ZITADEL user attributes and external SCIM server attributes.
    • Specify the provisioning behavior (e.g., create, update, delete).
    • Enable/disable provisioning for individual users or groups.
• Automatic User Synchronization:
  • Given: A user is created, updated, or deleted in ZITADEL.
  • When: Outbound SCIM provisioning is enabled for the user.
  • Then: ZITADEL should automatically send SCIM requests to the configured external SCIM server to synchronize the user data.
• Error Handling and Logging:
  • Given: An error occurs during outbound SCIM provisioning.
  • Then: The system should:
  • Log the error with detailed information.
  • Provide error notifications or alerts to administrators.
  • Implement a retry mechanism for failed provisioning attempts.
• Data Consistency:
  • Given: User data is synchronized between ZITADEL and an external SCIM server.
  • Then: The user data should be consistent across both systems.
• SCIM Standard and RFC Compliance:
  • Given: The outbound SCIM provisioning feature is implemented.
  • Then: The implementation must adhere to the SCIM standard framework and relevant RFCs, including:
    • Support for required SCIM operations (e.g., create, read, update, delete).
    • Use of standard SCIM resource schemas.
    • Proper handling of SCIM error responses.
• Documentation:
  • Given: An administrator or developer accesses the system documentation.
  • Then: The documentation should explain:
    • How to configure outbound SCIM provisioning.
    • How to manage SCIM servers.
    • How to define user provisioning rules.
    • How to handle errors and troubleshoot issues.
• Testing:
  • Given: The outbound SCIM user provisioning feature is implemented.
  • Then:
    • Unit tests should verify individual components of the provisioning logic.
    • Integration tests should verify the interaction between ZITADEL and external SCIM servers.
    • End-to-end tests should simulate user provisioning workflows, including creation, updates, and deletions.
    • Test cases should cover valid and invalid configuration scenarios.

Architecture

The implementation requires specific behaviours (such as searching for the user in the external SCIM endpoint, etc.) which cannot be implemented using the actions alone. On the other hand (as mentioned) likely a lot of vendors will not be fully compliant or need additional fields (custom schema) / very custom mapping.

• Provide Standard SCIM Client with default Implementation/Mapping (analog generic idps)
• With actions we allow customers to extend/customize the generic implementation
• In the future we might provide specific implementations for specific providers
• The handling of the subscribed events (I would start with predefined e.g User Added, User Updated, Delete etc, which also includes subresources such as metadata), will be handled using the existing queue as with event actions.
• The server and provisioning configuration need to be possible on a instance and organization level, where the latter can be used to specifically create a configuration or partially overwrite the instance, e.g. when to provision.

Technical Considerations

Integrations / References

• Atlassian (https://developer.atlassian.com/cloud/admin/user-provisioning/rest/intro/#about)
• Google Workspace (https://developers.google.com/admin-sdk/directory/v1/guides/manage-users)
• ServiceNow (https://docs.servicenow.com/bundle/vancouver-platform-security/page/integrate/authentication/task/create-a-rest-message.html)
• Salesforce (https://help.salesforce.com/s/articleView?id=sf.identity_scim_rest_api.htm&type=5)
• Slack (https://api.slack.com/admins/scim)

Additional Context

This feature might also be used for applications that don't support federated authentication (SAML, OpenID Connect). We strongly discourage use of such a feature to provision credentials. Instead users should look into a reverse-proxy / zero trust pattern to secure their applications.

Out of scope

• Inbound SCIM, as this is already implemented https://zitadel.com/docs/apis/scim2
• Group resource, in a first version we focus on users only

[mffap]

+1 from inbound

• AWS
• Google Workspace
• Office 365

[compgeniuses]

Hwo come all the proposed integrations ervices are the big cloud services, and not the small apps and providers as well, and even opensource solutions like

Glpi, Meshcentral, Zammad, matomo, etc, will those also feature, or were those just examples given

[mffap]

+1 from inbound. Provisioning basic user info from ZITADEL to EntraID (users require access to Teams / O365)

[adlerhurst]

Spike for POC:

@livio-a @adlerhurst

• analyse SCIM definition => documentation for implementation (1d)
  • user
  • group
  • additional resources
• conceptual idea how to map data (0.5d)
  • actions
  • user schema
  • ...?
• Which endpoints should we provide? (only users or also groups) (0.5d)
• Deviation from standard of popular systems? (0.5d)
  • entraID
  • Google
  • Okta
  • Auth0
  • Keycloak
• Is server implementation enough or does it also need a client implementation for inbound? Combinations:
  • ZITADEL is only server
  • Push based: if data manipulated in ZITADEL push to other system, if other system manipulates push to zitadel
  • Pull based: ZITADEL and other system need to pull data
  • ... other options?
• Where to integrate into ZITADEL? (0.5d)
  • events / actions ?
  • api?
  • ... ?

Goal of this POC is to have a proposal ready to gather feedback from interest groups via GH discussion or issue.

[compgeniuses]

progress at last... amen

[livio-a]

Architectural considerations

I suggest to use option 1 from above or a similar approach of that. The implementation requires specific behaviours (such as searching for the user in the external SCIM endpoint, etc.) which cannot be implemented using the actions alone. On the other hand (as mentioned) likely a lot of vendors will not be fully compliant or need additional fields (custom schema) / very custom mapping.
As with the IdPs we would provide a standard implementation (similar to Generic IdPs), which can be customized using function actions. These could allow rewriting of requests to and responses, resp. their bodies from the SCIM server, which would also mean we could do just a basic mapping from the internal model to the SCIM schema and (initially) do not need to provide a configuration possibility for the mapping.

The handling of the subscribed events (I would start with predefined), will be handled using the existing queue as with event actions.

The server and provisioning configuration need to be possible on a instance and organization level, where the latter can be used to specifically create a configuration or partially overwrite the instance, e.g. when to provision.