Provisioning#
Canaille partially implement the SCIM provisioning protocol, so user and group modifications can be spread across an entire application ecosystem.
Provisioning server#
Canaille acts as a provisioning server.
This means that client applications can perform requests on the /scim/v2 endpoint, using the SCIM2 protocol, to manage user and group objects.
Provisioning client#
Canaille also acts as a provisioning client.
It sends the user and group modifications to the client applications that implement a SCIM server.
The modifications are sent whether they come from the web interface, the CLI or from another client application that uses the Canaille SCIM server.
The CANAILLE_SCIM.ENABLE_CLIENT configuration parameter enables the provisioning client.
Warning
The SCIM client feature is at early development stage and comes with poor performances at the moment.
Provisioned clients#
Canaille sends a user to these clients:
the clients the user has given consent to, unless they have
owners;the
trustedclients, which receive all the users.
Canaille sends a group to the clients of its members, and to the trusted clients. When a task worker is configured, it sends the user modifications.
SCIM server requirements#
Canaille uses the client_uri of the client as the base URL of its SCIM server.
For instance, with https://app.example/scim/v2 as client_uri, Canaille reads https://app.example/scim/v2/ResourceTypes.
A client without a SCIM server at this URL is skipped.
Each Canaille process keeps the answers of these endpoints for 5 minutes.
A change on the SCIM server of the client can take up to 5 minutes to be seen.
The SCIM server of the client must:
publish the
/ServiceProviderConfig,/ResourceTypesand/Schemasendpoints;support filtering, otherwise Canaille does not provision the client;
store the
externalIdattribute and filter on it.
Canaille sets the externalId of the users and groups to their Canaille id.
Canaille finds the resources of the client with an externalId eq "<id>" filter, then updates or deletes them.
When the server does not support PATCH, Canaille replaces the resources with PUT.
The password of the users is never sent.
Authentication#
Canaille authenticates against the SCIM server of the client with a Bearer token.
Canaille issues this token for the client itself: the token has the client as audience, has no user, and expires after one hour.
To check the token, the client calls the introspection endpoint of Canaille, /oauth/introspect, with its own client credentials.
The introspection response is active while the token is valid.
Troubleshooting#
Canaille logs the provisioning events in the canaille logger:
Level |
Event |
|---|---|
|
The client has no SCIM server at its |
|
The SCIM server refuses the token with a 401 or 403 response. |
|
The SCIM server does not support filtering. |
|
The creation, update or deletion of a user or a group fails. |
|
A deleted user or group is not found on the client. |
|
A member of a group is not found on the client. |
Configuration#
To allow clients to access the SCIM API, the client must have the client_credentials grant type configured. This allows clients to ask an authentication token on their own behalf and use this token to perform queries. The client must also have one of these scopes:
scim:users:readandscim:users:writeto read or write the users;scim:groups:readandscim:groups:writeto read or write the groups;scim:readandscim:writeto read or write both.
The write scopes also allow reading.
The SCIM scopes must be listed in the scope of the client: a client without a scope cannot get them.
Clients created with dynamic client registration cannot access the SCIM API, as they cannot use the client_credentials grant type.
User tokens only give access to the user they belong to,
on the /Me endpoint or on /Users/<id>.
They need the scim:me scope, which users accept on the consent page.
Users can only modify the attributes of their WRITE ACL,
and need the EDIT_SELF permission to edit their account,
and the DELETE_ACCOUNT or MANAGE_USERS permission to delete it.
The /ServiceProviderConfig, /ResourceTypes and /Schemas endpoints need no token.
Then the CANAILLE_SCIM.ENABLE_SERVER
configuration parameter must be enabled.
...
[CANAILLE_SCIM]
ENABLE_SERVER = true
To allow Canaille to act as a SCIM client and broadcast modifications to client applications,
the CANAILLE_SCIM.ENABLE_CLIENT
configuration parameter must be enabled.
...
[CANAILLE_SCIM]
ENABLE_CLIENT = true
The Canaille SCIM server supports bulk operations. The following configuration parameters can be specified regarding bulk operations:
...
[CANAILLE_SCIM]
# Maximum number of operations allowed in a bulk request
BULK_MAX_OPERATIONS = 100
# Maximum payload size (in bytes) allowed in a bulk request
BULK_MAX_PAYLOAD_SIZE = 1048576
Implementation details#
Due to technical reasons, the server-side Canaille User and Group resources implementation subtly differs from the RFC7643 definitions:
User.userNameis immutable (while it is read-write in RFC7643), because the OIDCsubclaim uses it by default.User.name.familyNameis required (while it is optional in RFC7643).Group.displayNameis required (while it is optional in RFC7643).Group.membersis required (while it is optional in RFC7643), i.e. groups cannot be empty.
Debugging#
To check what data are exposed through the Canaille SCIM API, you need a client token and a SCIM client application. To generate a client token, you can simply manually create a token from the button on the client administration page. The token gets the scopes of the client, so the client needs one of the SCIM scopes listed above. Then, we recommend the use of scim2-cli to interact with the API:
$ pip install scim2-cli
$ export SCIM_CLI_URL="https://canaille.example/scim/v2"
$ export SCIM_CLI_HEADERS="Authorization: Bearer <MY_CLIENT_TOKEN>"
$ scim query user 2819c223-7f76-453a-919d-413861904646
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"meta": {
"resourceType": "User",
"created": "2024-12-05T16:08:51.896646Z",
"lastModified": "2024-12-05T16:08:51.896646Z",
"location": "https://canaille.example/scim/v2/Users/2819c223-7f76-453a-919d-413861904646",
"version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
},
"userName": "bjensen@example.com"
}