Merge branch 'scim-etags' into 'main'

Support SCIM ETags

See merge request yaal/canaille!335

Author: azmeuk

CHANGES.rst

@@ -5,6 +5,7 @@ Added
 ^^^^^
 - SCIM ``attributes`` and ``excludedAttributes`` query parameter support.
 - SCIM ``POST /.search`` endpoint.
+- SCIM ETags support. :pr:`335`
 
 [0.2.3] - 2026-03-24
 --------------------

canaille/scim/casting.py

@@ -1,4 +1,5 @@
 import datetime
+import hashlib
 
 from flask import url_for
 from scim2_models import Meta
@@ -11,6 +12,13 @@
 from canaille.scim.models import User
 
 
+def make_etag(model):
+    """Compute a weak ETag from a model's identity and modification time."""
+    raw = f"{model.id}:{model.last_modified}"
+    digest = hashlib.sha256(raw.encode()).hexdigest()[:16]
+    return f'W/"{digest}"'
+
+
 def user_from_canaille_to_scim(user, user_class, enterprise_user_class):
     scim_user_class = user_class if user_class != User else User[EnterpriseUser]
     scim_user = scim_user_class(
@@ -19,6 +27,7 @@ def user_from_canaille_to_scim(user, user_class, enterprise_user_class):
             created=user.created,
             last_modified=user.last_modified,
             location=url_for("scim.query_user", user=user, _external=True),
+            version=make_etag(user),
         ),
         user_name=user.user_name,
         preferred_language=user.preferred_language,
@@ -157,6 +166,7 @@ def group_from_canaille_to_scim(group, group_class):
             created=group.created,
             last_modified=group.last_modified,
             location=url_for("scim.query_group", group=group, _external=True),
+            version=make_etag(group),
         ),
         display_name=group.display_name,
     )

canaille/scim/endpoints.py

@@ -8,7 +8,6 @@
 )
 from authlib.oauth2.rfc6750 import BearerTokenValidator
 from flask import Blueprint
-from flask import Response
 from flask import abort
 from flask import current_app
 from flask import request
@@ -22,13 +21,15 @@
 from scim2_models import Schema
 from scim2_models import SearchRequest
 from werkzeug.exceptions import HTTPException
+from werkzeug.exceptions import PreconditionFailed
 
 from canaille.app import models
 from canaille.app.flask import csrf
 from canaille.backends import Backend
 
 from .casting import group_from_canaille_to_scim_server
 from .casting import group_from_scim_to_canaille
+from .casting import make_etag
 from .casting import user_from_canaille_to_scim_server
 from .casting import user_from_scim_to_canaille
 from .models import EnterpriseUser
@@ -58,6 +59,34 @@ def add_scim_content_type(response):
     return response
 
 
+@bp.after_request
+def set_etag_header(response):
+    """Extract ``ETag`` from ``meta.version`` and handle conditional responses."""
+    data = response.get_json(silent=True)
+    if meta := (data or {}).get("meta"):
+        if version := meta.get("version"):
+            response.headers["ETag"] = version
+    response.make_conditional(request)
+    return response
+
+
+@bp.before_request
+def check_etag():
+    """Verify ``If-Match`` on write operations."""
+    if request.method not in ("PUT", "PATCH", "DELETE"):
+        return
+    arg = next(iter(request.view_args.values()))
+    if_match = request.headers.get("If-Match")
+    if not if_match:
+        return
+    if if_match.strip() == "*":
+        return
+    etag = make_etag(arg)
+    tags = [t.strip() for t in if_match.split(",")]
+    if etag not in tags:
+        raise PreconditionFailed("ETag mismatch")
+
+
 @bp.errorhandler(HTTPException)
 def http_error_handler(error):
     obj = Error(detail=str(error), status=error.code)
@@ -268,6 +297,7 @@ def search():
 @csrf.exempt
 @require_oauth()
 def create_user():
+    req = ResponseParameters.model_validate(request.args.to_dict())
     request_user = User[EnterpriseUser].model_validate(
         request.json, scim_ctx=Context.RESOURCE_CREATION_REQUEST
     )
@@ -277,14 +307,21 @@ def create_user():
         f"SCIM created user {user.id} by client {current_token.client.client_id}"
     )
     response_user = user_from_canaille_to_scim_server(user)
-    payload = response_user.model_dump_json(scim_ctx=Context.RESOURCE_CREATION_RESPONSE)
-    return Response(payload, status=HTTPStatus.CREATED)
+    return (
+        response_user.model_dump(
+            scim_ctx=Context.RESOURCE_CREATION_RESPONSE,
+            attributes=req.attributes,
+            excluded_attributes=req.excluded_attributes,
+        ),
+        HTTPStatus.CREATED,
+    )
 
 
 @bp.route("/Groups", methods=["POST"])
 @csrf.exempt
 @require_oauth()
 def create_group():
+    req = ResponseParameters.model_validate(request.args.to_dict())
     request_group = Group.model_validate(
         request.json, scim_ctx=Context.RESOURCE_CREATION_REQUEST
     )
@@ -294,58 +331,69 @@ def create_group():
         f"SCIM created group {group.id} by client {current_token.client.client_id}"
     )
     response_group = group_from_canaille_to_scim_server(group)
-    payload = response_group.model_dump_json(
-        scim_ctx=Context.RESOURCE_CREATION_RESPONSE
+    return (
+        response_group.model_dump(
+            scim_ctx=Context.RESOURCE_CREATION_RESPONSE,
+            attributes=req.attributes,
+            excluded_attributes=req.excluded_attributes,
+        ),
+        HTTPStatus.CREATED,
     )
-    return Response(payload, status=HTTPStatus.CREATED)
 
 
 @bp.route("/Users/<user:user>", methods=["PUT"])
 @csrf.exempt
 @require_oauth()
 def replace_user(user):
+    req = ResponseParameters.model_validate(request.args.to_dict())
     original_scim_user = user_from_canaille_to_scim_server(user)
     request_scim_user = User[EnterpriseUser].model_validate(
         request.json,
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=original_scim_user,
     )
+    request_scim_user.replace(original_scim_user)
     updated_user = user_from_scim_to_canaille(request_scim_user, user)
     Backend.instance.save(updated_user)
     current_app.logger.security(
         f"SCIM replaced user {updated_user.id} by client {current_token.client.client_id}"
     )
     response_scim_user = user_from_canaille_to_scim_server(updated_user)
-    payload = response_scim_user.model_dump(
-        scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
+    return response_scim_user.model_dump(
+        scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE,
+        attributes=req.attributes,
+        excluded_attributes=req.excluded_attributes,
     )
-    return payload
 
 
 @bp.route("/Groups/<group:group>", methods=["PUT"])
 @csrf.exempt
 @require_oauth()
 def replace_group(group):
+    req = ResponseParameters.model_validate(request.args.to_dict())
     original_scim_group = group_from_canaille_to_scim_server(group)
     request_scim_group = Group.model_validate(
         request.json,
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=original_scim_group,
     )
+    request_scim_group.replace(original_scim_group)
     updated_group = group_from_scim_to_canaille(request_scim_group, group)
     Backend.instance.save(updated_group)
     current_app.logger.security(
         f"SCIM replaced group {updated_group.id} by client {current_token.client.client_id}"
     )
     response_group = group_from_canaille_to_scim_server(updated_group)
-    payload = response_group.model_dump(scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE)
-    return payload
+    return response_group.model_dump(
+        scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE,
+        attributes=req.attributes,
+        excluded_attributes=req.excluded_attributes,
+    )
 
 
 @bp.route("/Users/<user:user>", methods=["PATCH"])
 @csrf.exempt
 @require_oauth()
 def patch_user(user):
+    req = ResponseParameters.model_validate(request.args.to_dict())
     scim_user = user_from_canaille_to_scim_server(user)
     patch_op = PatchOp[User[EnterpriseUser]].model_validate(
         request.json, scim_ctx=Context.RESOURCE_PATCH_REQUEST
@@ -360,13 +408,18 @@ def patch_user(user):
         )
         scim_user = user_from_canaille_to_scim_server(updated_user)
 
-    return scim_user.model_dump(scim_ctx=Context.RESOURCE_PATCH_RESPONSE)
+    return scim_user.model_dump(
+        scim_ctx=Context.RESOURCE_PATCH_RESPONSE,
+        attributes=req.attributes,
+        excluded_attributes=req.excluded_attributes,
+    )
 
 
 @bp.route("/Groups/<group:group>", methods=["PATCH"])
 @csrf.exempt
 @require_oauth()
 def patch_group(group):
+    req = ResponseParameters.model_validate(request.args.to_dict())
     scim_group = group_from_canaille_to_scim_server(group)
     patch_op = PatchOp[Group].model_validate(
         request.json, scim_ctx=Context.RESOURCE_PATCH_REQUEST
@@ -381,7 +434,11 @@ def patch_group(group):
         )
         scim_group = group_from_canaille_to_scim_server(updated_group)
 
-    return scim_group.model_dump(scim_ctx=Context.RESOURCE_PATCH_RESPONSE)
+    return scim_group.model_dump(
+        scim_ctx=Context.RESOURCE_PATCH_RESPONSE,
+        attributes=req.attributes,
+        excluded_attributes=req.excluded_attributes,
+    )
 
 
 @bp.route("/Users/<user:user>", methods=["DELETE"])

canaille/scim/models.py

@@ -237,7 +237,7 @@ def get_service_provider_config():
         change_password=ChangePassword(supported=True),
         filter=Filter(supported=False, max_results=0),
         sort=Sort(supported=False),
-        etag=ETag(supported=False),
+        etag=ETag(supported=True),
         authentication_schemes=[
             AuthenticationScheme(
                 name="OAuth Bearer Token",

doc/development/specifications.rst

@@ -68,9 +68,9 @@ What's implemented
 Endpoints:
 
 - /Users (GET, POST)
-- /Users/<user_id> (GET, PUT, DELETE)
+- /Users/<user_id> (GET, PUT, PATCH, DELETE)
 - /Groups (GET, POST)
-- /Groups/<user_id> (GET, PUT, DELETE)
+- /Groups/<group_id> (GET, PUT, PATCH, DELETE)
 - /ServiceProviderConfig (GET)
 - /Schemas (GET)
 - /Schemas/<schema_id> (GET)
@@ -80,6 +80,8 @@ Endpoints:
 Features:
 
 - :rfc:`pagination <7644#section-3.4.2.4>`
+- :rfc:`ETags <7644#section-3.14>`
+- :rfc:`attributes selection <7644#section-3.4.2.5>`
 
 .. _scim_unimplemented:
 
@@ -96,5 +98,3 @@ Features
 
 - :rfc:`filtering <7644#section-3.4.2.2>`
 - :rfc:`sorting <7644#section-3.4.2.3>`
-- :rfc:`attributes selection <7644#section-3.4.2.5>`
-- :rfc:`ETags <7644#section-3.14>`

tests/scim/test_etag.py

@@ -0,0 +1,92 @@
+import json
+
+from werkzeug.test import Client
+
+from canaille.scim.casting import make_etag
+
+
+def _auth_headers(app, oidc_token):
+    return {
+        "Authorization": f"Bearer {oidc_token.access_token}",
+        "Host": app.config["SERVER_NAME"],
+        "Content-Type": "application/scim+json",
+    }
+
+
+def _get_user_payload(client, app, user, oidc_token):
+    """Fetch the SCIM representation of a user to use as PUT payload."""
+    response = client.get(
+        f"/scim/v2/Users/{user.id}",
+        headers=_auth_headers(app, oidc_token),
+    )
+    payload = response.get_json()
+    for key in ("id", "meta", "photos", "groups"):
+        payload.pop(key, None)
+    return payload
+
+
+def test_get_user_returns_etag_header(app, backend, user, oidc_token):
+    """GET on a user resource includes an ETag header in the response."""
+    client = Client(app)
+    headers = _auth_headers(app, oidc_token)
+    response = client.get(f"/scim/v2/Users/{user.id}", headers=headers)
+    assert response.status_code == 200
+    assert response.headers.get("ETag")
+    assert response.headers["ETag"] == make_etag(user)
+
+
+def test_put_user_with_matching_etag(app, backend, user, oidc_token):
+    """PUT with a correct If-Match ETag succeeds."""
+    client = Client(app)
+    headers = _auth_headers(app, oidc_token)
+    payload = _get_user_payload(client, app, user, oidc_token)
+    payload["displayName"] = "Updated Name"
+    headers["If-Match"] = make_etag(user)
+    response = client.put(
+        f"/scim/v2/Users/{user.id}",
+        data=json.dumps(payload),
+        headers=headers,
+    )
+    assert response.status_code == 200
+    assert response.get_json()["displayName"] == "Updated Name"
+
+
+def test_put_user_with_wildcard_if_match(app, backend, user, oidc_token):
+    """PUT with If-Match: * bypasses ETag comparison."""
+    client = Client(app)
+    headers = _auth_headers(app, oidc_token)
+    payload = _get_user_payload(client, app, user, oidc_token)
+    headers["If-Match"] = "*"
+    response = client.put(
+        f"/scim/v2/Users/{user.id}",
+        data=json.dumps(payload),
+        headers=headers,
+    )
+    assert response.status_code == 200
+
+
+def test_put_user_with_mismatched_etag(app, backend, user, oidc_token):
+    """PUT with an incorrect If-Match ETag returns 412 Precondition Failed."""
+    client = Client(app)
+    headers = _auth_headers(app, oidc_token)
+    payload = _get_user_payload(client, app, user, oidc_token)
+    headers["If-Match"] = 'W/"0000000000000000"'
+    response = client.put(
+        f"/scim/v2/Users/{user.id}",
+        data=json.dumps(payload),
+        headers=headers,
+    )
+    assert response.status_code == 412
+
+
+def test_put_user_without_if_match(app, backend, user, oidc_token):
+    """PUT without If-Match header proceeds without ETag verification."""
+    client = Client(app)
+    headers = _auth_headers(app, oidc_token)
+    payload = _get_user_payload(client, app, user, oidc_token)
+    response = client.put(
+        f"/scim/v2/Users/{user.id}",
+        data=json.dumps(payload),
+        headers=headers,
+    )
+    assert response.status_code == 200