113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
# keycloak-scim-client
|
|
|
|
This extension add [SCIM2](http://www.simplecloud.info) 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](https://datatracker.ietf.org/doc/html/rfc7643)
|
|
and [RFC7644](https://datatracker.ietf.org/doc/html/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](https://lab.libreho.st/libre.sh/scim/keycloak-scim/-/jobs/artifacts/main/raw/build/libs/keycloak-scim-1.0-SNAPSHOT-all.jar?job=package)
|
|
2. Put it in `/opt/keycloak/providers/`.
|
|
|
|
It's also possible to build your own custom image if you run Keycloak in a [container](/docs/container.md).
|
|
|
|
Other [installation options](/docs/installation.md) 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](https://docs.docker.com/engine/reference/commandline/network/)
|
|
If you use the [rocketchat app](https://lab.libreho.st/libre.sh/scim/rocketchat-scim) 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](/LICENSE).
|
|
|
|
## Funding
|
|
|
|
This project is funded through [NGI0 Entrust](https://nlnet.nl/entrust), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/Libre.sh-SCIM).
|
|
|
|
[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
|
|
[<img src="https://nlnet.nl/image/logos/NGI0_tag.svg" alt="NGI Zero Logo" width="20%" />](https://nlnet.nl/entrust)
|