keycloak-scim/README.md

keycloak-scim-client

This extension add SCIM2 client capabilities to Keycloak.

It allows to :

• Declare SCIM endpoints (through the identity federation UI). Any tool implementing SCIM protocol can be wired to the Keycloack instance through this declaration.
• Propagate users and groups from Keycloack to SCIM endpoints : when a user/group gets created or modified in Keycloack, the modification is fowarded to all declared SCIM endpoints through SCIM calls within the transaction scope. If propagation fails, changes can be rolled back or not according to a configurable rollback strategy.
• Import users and groups from SCIM endpoints (through the Keycloack synchronization mechanism).

See RFC7643 and RFC7644) for further details

Overview

Motivation

We want to build a unified collaborative platform based on multiple applications. To do that, we need a way to propagate immediately changes made in Keycloak to all these applications. And we want to keep using OIDC or SAML as the authentication protocol.

This will allow users to collaborate seamlessly across the platform without requiring every user to have connected once to each application. This will also ease GDRP compliance because deleting a user in Keycloak will delete the user from every app. The SCIM protocol is standard, comprehensible and easy to implement. It's a perfect fit for our goal.

We chose to build application extensions/plugins because it's easier to deploy and thus will benefit to a larger portion of the FOSS community.

Keycloak specific

This extension uses 3 concepts in KeyCloack :

• Event Listener : used to listen for changes within Keycloack (e.g. User creation, Group deletion...) and propagate them to registered SCIM service providers through SCIM requests.
• Federation Provider : used to set up all the SCIM service providers endpoint without creating our own UI.
• JPA Entity Provider : used to save the mapping between the local IDs and the service providers IDs.

Usage

Development mode

From the repository root :

• Launch the docker-compose image (composed of a postgre and keycloack instance runing on localhost:8080) : docker compose up -d
• Execute gradle jar shadowJar && docker compose restart keycloak to build extension and update the Keycloack instance
• You can access extension logs through docker compose logs -f

Installation

1. Download the latest version
2. Put it in /opt/keycloak/providers/.

It's also possible to build your own custom image if you run Keycloak in a container.

Other installation options are available.

Setup

Enable SCIM Event listeners

1. Go to Admin Console > Events > Config.
2. Add scim in Event Listeners.
3. Save.

Register SCIM Service Providers

1. Go to Admin Console > Realm Settings > Events.
2. Add scim to the list of event listers
3. Save

Configuration

Add the endpoint - for a local set up you have to add the two containers in a docker network and use the container ip see here If you use the rocketchat app you get the endpoint from your rocket Chat Scim Adapter App Details. Endpoint content type is application/json. Auth mode Bearer or None for local test setup. Copy the bearer token from your app details in rocketchat.

If you enable import during sync then you can choose between to following import actions:

• Create Local - adds users to keycloak
• Nothing
• Delete Remote - deletes users from the remote application

Sync

You can set up a periodic sync for all users or just changed users - it's not mandatory. You can either do:

• Periodic Full Sync
• Periodic Changed User Sync

License

Licensed under the Apache License, Version 2.0.

Funding

This project is funded through NGI0 Entrust, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.