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 a provisioning client. This means that all modifications on user and groups are spread among the client applications implementing the SCIM2 server specification. This ensures that the details of users and groups are always synchronized among all your client applications.

Modifications are sent to client applications whether they come from the web interface, the CLI or from another client application requesting the Canaille SCIM server endpoint.

Canaille will attempt to authenticate against the client SCIM2 server endpoint with a Bearer token it has emitted on behalf of the client. Please make sure that your client application is properly configured to accept Canaille tokens.

Warning

Note that the SCIM client feature is at early development stage and comes with poor performances at the moment.

Todo

Some SCIM features and endpoints are not implemented. In addition to these, Canaille will implement in the future:

  • Client-side implementation, to broadcast user and groups modifications among all the clients.

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:read and scim:users:write to read or write the users;

  • scim:groups:read and scim:groups:write to read or write the groups;

  • scim:read and scim:write to read or write both.

The write scopes also allow reading.

User tokens are only accepted on the /Me endpoint, which allows authenticated users to manage their own resource. 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 and DELETE_ACCOUNT permissions to edit and delete their account.

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.userName is immutable (while it is read-write in RFC7643).

  • User.name.familyName is required (while it is optional in RFC7643).

  • Group.displayName is required (while it is optional in RFC7643).

  • Group.members is 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:

scim2-cli usage example#
 $ 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 bjensen
 {
     "schemas": [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
     ],
     "id": "bjensen",
     "meta": {
         "resourceType": "User",
         "created": "2024-12-05T16:08:51.896646Z",
         "lastModified": "2024-12-05T16:08:51.896646Z",
         "location": "http://scim.example/v2/Users/bjensen",
         "version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
     },
     "userName": "bjensen@example.com"
 }