doc: SCIM debugging instructions

doc/conf.py

@@ -65,6 +65,7 @@ def __getattr__(cls, name):
     "pydantic": ("https://docs.pydantic.dev/latest", None),
     "pytest-iam": ("https://pytest-iam.readthedocs.io/en/latest/", None),
     "wtforms": ("https://wtforms.readthedocs.io", None),
+    "scim2-cli": ("https://scim2-cli.readthedocs.io/en/latest", None),
 }
 
 issues_uri = "https://gitlab.com/yaal/canaille/-/issues/{issue}"

doc/locales/doc.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: canaille 0.0.56\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-12-19 10:08+0100\n"
+"POT-Creation-Date: 2024-12-19 10:18+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -3008,7 +3008,7 @@ msgstr ""
 #: ../features.rst:83
 #: ../features.rst:149
 #: ../tutorial/deployment.rst:13
-#: ../tutorial/provisioning.rst:21
+#: ../tutorial/provisioning.rst:9
 #: 6fdf0a969ccb49e1bf9bfc28f4df9169
 #: 4065a0b70a1444058df3bb16f0abc445
 #: bc0be7a805e04b5f91b89db28d7dffae
@@ -3970,7 +3970,9 @@ msgid "Reset one-time password authentication for a user and display the edited
 msgstr ""
 
 #: ../references/configuration.rst:2
+#: ../tutorial/provisioning.rst:18
 #: 6c3d1ad364a84afb9586b1b62e42dedb
+#: 07783d84d6c64841b473c97c38f85937
 msgid "Configuration"
 msgstr ""
 
@@ -6529,29 +6531,44 @@ msgstr ""
 msgid "At the moment, only the server part is implemented. It allows client applications to manage user profiles directly in Canaille."
 msgstr ""
 
-#: ../tutorial/provisioning.rst:9
+#: ../tutorial/provisioning.rst:11
+#: 37c0e4ee9eb54f9f94754fec060e0ac5
+msgid "Some SCIM :ref:`features and endpoints <scim_unimplemented>` are not implemented. In addition to these, Canaille will implement in the future:"
+msgstr ""
+
+#: ../tutorial/provisioning.rst:14
+#: a5d6aea95b444cbb9d10731986ae66ac
+msgid "Access control for clients on the SCIM API endpoint, to finely manage permissions depending on clients."
+msgstr ""
+
+#: ../tutorial/provisioning.rst:15
+#: 98d88ce07bc640bcafedee10c9bbc98f
+msgid "Client-side implementation, to broadcast user and groups modifications among all the clients."
+msgstr ""
+
+#: ../tutorial/provisioning.rst:20
 #: 706556a4f4de43658b7ee3583115216a
 msgid "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. Currently, user tokens are not supported."
 msgstr ""
 
-#: ../tutorial/provisioning.rst:13
+#: ../tutorial/provisioning.rst:24
 #: 5abc69c6a6ff4cd48e3f2b01cdaa1a52
 msgid "Then the :attr:`CANAILLE_SCIM.ENABLE_SERVER <canaille.scim.configuration.SCIMSettings.ENABLE_SERVER>` configuration parameter must be enabled."
 msgstr ""
 
-#: ../tutorial/provisioning.rst:23
-#: 37c0e4ee9eb54f9f94754fec060e0ac5
-msgid "Some SCIM :ref:`features and endpoints <scim_unimplemented>` are not implemented. In addition to these, Canaille will implement in the future:"
+#: ../tutorial/provisioning.rst:33
+#: 432c05f5057e4d6ab93225079865e789
+msgid "Debugging"
 msgstr ""
 
-#: ../tutorial/provisioning.rst:26
-#: a5d6aea95b444cbb9d10731986ae66ac
-msgid "Access control for clients on the SCIM API endpoint, to finely manage permissions depending on clients."
+#: ../tutorial/provisioning.rst:35
+#: ecce1ab63ddd4b1a8dd3c7c65e9a990c
+msgid "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. Then, we recommend the use of :doc:`scim2-cli:index` to interact with the API:"
 msgstr ""
 
-#: ../tutorial/provisioning.rst:27
-#: 98d88ce07bc640bcafedee10c9bbc98f
-msgid "Client-side implementation, to broadcast user and groups modifications among all the clients."
+#: ../tutorial/provisioning.rst:39
+#: 0494884602794d818953870e734c721b
+msgid "scim2-cli usage example"
 msgstr ""
 
 #: ../tutorial/theming.rst:2

doc/tutorial/provisioning.rst

@@ -6,6 +6,17 @@ Canaille partially implement the :rfc:`SCIM <7642>` provisioning protocol at the
 At the moment, only the server part is implemented.
 It allows client applications to manage user profiles directly in Canaille.
 
+.. todo::
+
+   Some SCIM :ref:`features and endpoints <scim_unimplemented>` are not implemented.
+   In addition to these, Canaille will implement in the future:
+
+   - Access control for clients on the SCIM API endpoint, to finely manage permissions depending on clients.
+   - 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.
 Currently, user tokens are not supported.
@@ -18,10 +29,32 @@ Then the :attr:`CANAILLE_SCIM.ENABLE_SERVER <canaille.scim.configuration.SCIMSet
    [CANAILLE_SCIM]
    ENABLE_SERVER = true
 
-.. todo::
-
-   Some SCIM :ref:`features and endpoints <scim_unimplemented>` are not implemented.
-   In addition to these, Canaille will implement in the future:
-
-   - Access control for clients on the SCIM API endpoint, to finely manage permissions depending on clients.
-   - Client-side implementation, to broadcast user and groups modifications among all the clients.
+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.
+Then, we recommend the use of :doc:`scim2-cli:index` to interact with the API:
+
+.. code-block:: console
+   :caption: scim2-cli usage example
+
+    $ pip install scim2-cli
+    $ export SCIM_CLI_URL="https://auth.example"
+    $ 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"
+    }