scim2-server 0.3.2__tar.gz → 0.4.0__tar.gz

{scim2_server-0.3.2 → scim2_server-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scim2-server
-Version: 0.3.2
+Version: 0.4.0
 Summary: Lightweight SCIM2 server prototype
 Keywords: scim,scim2,provisioning,rfc7643,rfc7644
 Author: Yaal Coop, Christian Friedrich Coors
@@ -240,11 +240,12 @@ they are lost once the process exits.
 - [x] HTTP PATCH (Add/Remove/Replace)
 - [x] Sorting
 - [x] Bulk operations
+- [x] Multi-tenancy with a URL prefix
 
 ## Usage
 
 ```shell
-$ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service-provider-config SERVICE_PROVIDER_CONFIG] [--bearer-token BEARER_TOKEN] [--hostname HOSTNAME] [--port PORT] [--reverse-proxy] [--dump-resources DUMP_RESOURCES] [--debug]
+$ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service-provider-config SERVICE_PROVIDER_CONFIG] [--bearer-token BEARER_TOKEN] [--hostname HOSTNAME] [--port PORT] [--reverse-proxy] [--dump-resources DUMP_RESOURCES] [--tenant TENANT] [--dynamic-tenants] [--debug]
 ```
 
 - `-h`/`--help`: Show help message
@@ -255,9 +256,31 @@ $ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service
 - `--bearer-token`: Registers a bearer token that can be used for accessing the service, and announces the bearer token authentication scheme. If no tokens are provided, anonymous access without authentication is allowed.
 - `--hostname`: The hostname to listen on. Defaults to `127.0.0.1`.
 - `--port`: The port to listen on. Defaults to `8080`.
-- `--dump-resources`: Dump a JSON document containing all resources when the provider exits normally.
+- `--dump-resources`: Dump a JSON document containing all resources when the provider exits normally. With tenants, the document has one entry per tenant.
+- `--tenant`: Serve a tenant under `/<tenant>`, for example `/<tenant>/v2/Users`. Can be repeated. See [Multi-tenancy](#multi-tenancy).
+- `--dynamic-tenants`: Create a tenant on the first request to `/<tenant>`. See [Multi-tenancy](#multi-tenancy).
 - `--debug`: Enable the interactive Werkzeug debugger, the reloader and the logging of the WSGI environment of each request. The debugger allows arbitrary code execution and the environment contains the bearer tokens, so never use this option on a server reachable by others.
 
+### Multi-tenancy
+
+With `--tenant` or `--dynamic-tenants`, the first segment of the URL path selects a tenant (RFC 7644 §6.1).
+Each tenant has its own resources: `/a/v2/Users` and `/b/v2/Users` are separate, and uniqueness, filters and pagination only consider the resources of the tenant.
+The schemas, the resource types and the service provider configuration are the same for every tenant, and so are the bearer tokens.
+A request without a known tenant gets a 404 answer, and `v2` cannot be a tenant name.
+
+```shell
+$ scim2-server --tenant a --tenant b
+$ curl http://localhost:8080/a/v2/Users
+```
+
+With `--dynamic-tenants`, the first request to an unknown tenant creates it with no resources.
+This is useful for tests: each test can pick a random tenant and get an empty server.
+Any client can then create tenants, even without a valid bearer token, and every tenant stays in memory until the server exits.
+Do not use this option on a server reachable by untrusted clients.
+
+In Python, `scim2_server.tenants.TenantDispatcher` builds one `SCIMApplication` per tenant from a factory.
+Override its `select_tenant` method to read the tenant from a header or a sub-domain instead.
+
 ### Container
 
 A container image is published on the GitHub container registry for each release.
@@ -277,7 +300,6 @@ This provider can be used as a starting point if you want to implement a SCIM pr
 - Implement your own Backend as a subclass of `scim2_server.backend.Backend`
 - Implement proper authorization with OAuth instead of public access or static bearer tokens
 - Support the `/Me` endpoint, if it applies in your use case
-- Add support for using either a static URL prefix or improve the support for usage behind a reverse proxy
 
 The provider in its current state has been tested successfully against a live
 [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)

{scim2_server-0.3.2 → scim2_server-0.4.0}/README.md

@@ -14,11 +14,12 @@ they are lost once the process exits.
 - [x] HTTP PATCH (Add/Remove/Replace)
 - [x] Sorting
 - [x] Bulk operations
+- [x] Multi-tenancy with a URL prefix
 
 ## Usage
 
 ```shell
-$ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service-provider-config SERVICE_PROVIDER_CONFIG] [--bearer-token BEARER_TOKEN] [--hostname HOSTNAME] [--port PORT] [--reverse-proxy] [--dump-resources DUMP_RESOURCES] [--debug]
+$ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service-provider-config SERVICE_PROVIDER_CONFIG] [--bearer-token BEARER_TOKEN] [--hostname HOSTNAME] [--port PORT] [--reverse-proxy] [--dump-resources DUMP_RESOURCES] [--tenant TENANT] [--dynamic-tenants] [--debug]
 ```
 
 - `-h`/`--help`: Show help message
@@ -29,9 +30,31 @@ $ scim2-server [-h] [--schema SCHEMA] [--resource-type RESOURCE_TYPE] [--service
 - `--bearer-token`: Registers a bearer token that can be used for accessing the service, and announces the bearer token authentication scheme. If no tokens are provided, anonymous access without authentication is allowed.
 - `--hostname`: The hostname to listen on. Defaults to `127.0.0.1`.
 - `--port`: The port to listen on. Defaults to `8080`.
-- `--dump-resources`: Dump a JSON document containing all resources when the provider exits normally.
+- `--dump-resources`: Dump a JSON document containing all resources when the provider exits normally. With tenants, the document has one entry per tenant.
+- `--tenant`: Serve a tenant under `/<tenant>`, for example `/<tenant>/v2/Users`. Can be repeated. See [Multi-tenancy](#multi-tenancy).
+- `--dynamic-tenants`: Create a tenant on the first request to `/<tenant>`. See [Multi-tenancy](#multi-tenancy).
 - `--debug`: Enable the interactive Werkzeug debugger, the reloader and the logging of the WSGI environment of each request. The debugger allows arbitrary code execution and the environment contains the bearer tokens, so never use this option on a server reachable by others.
 
+### Multi-tenancy
+
+With `--tenant` or `--dynamic-tenants`, the first segment of the URL path selects a tenant (RFC 7644 §6.1).
+Each tenant has its own resources: `/a/v2/Users` and `/b/v2/Users` are separate, and uniqueness, filters and pagination only consider the resources of the tenant.
+The schemas, the resource types and the service provider configuration are the same for every tenant, and so are the bearer tokens.
+A request without a known tenant gets a 404 answer, and `v2` cannot be a tenant name.
+
+```shell
+$ scim2-server --tenant a --tenant b
+$ curl http://localhost:8080/a/v2/Users
+```
+
+With `--dynamic-tenants`, the first request to an unknown tenant creates it with no resources.
+This is useful for tests: each test can pick a random tenant and get an empty server.
+Any client can then create tenants, even without a valid bearer token, and every tenant stays in memory until the server exits.
+Do not use this option on a server reachable by untrusted clients.
+
+In Python, `scim2_server.tenants.TenantDispatcher` builds one `SCIMApplication` per tenant from a factory.
+Override its `select_tenant` method to read the tenant from a header or a sub-domain instead.
+
 ### Container
 
 A container image is published on the GitHub container registry for each release.
@@ -51,7 +74,6 @@ This provider can be used as a starting point if you want to implement a SCIM pr
 - Implement your own Backend as a subclass of `scim2_server.backend.Backend`
 - Implement proper authorization with OAuth instead of public access or static bearer tokens
 - Support the `/Me` endpoint, if it applies in your use case
-- Add support for using either a static URL prefix or improve the support for usage behind a reverse proxy
 
 The provider in its current state has been tested successfully against a live
 [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)

{scim2_server-0.3.2 → scim2_server-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.3.2"
+version = "0.4.0"
 description = "Lightweight SCIM2 server prototype"
 readme = "README.md"
 keywords = [

{scim2_server-0.3.2 → scim2_server-0.4.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.3.2"
+version = "0.4.0"
 description = "Lightweight SCIM2 server prototype"
 authors = [
     {name="Yaal Coop", email="contact@yaal.coop"},

{scim2_server-0.3.2 → scim2_server-0.4.0}/scim2_server/backend.py

@@ -98,7 +98,8 @@ class Backend:
         :param resource: Resource to create.
         :return: The created resource. Creation should set system-
             defined attributes (ID, Metadata). May be the same object
-            that is passed in.
+            that is passed in. A relative ``meta.location`` is relative to
+            the root of the application.
         """
         raise NotImplementedError
 
@@ -230,7 +231,7 @@ class InMemoryBackend(Backend):
             resource_type=resource_type.name,
             created=utcnow,
             last_modified=utcnow,
-            location="/v2" + resource_type.endpoint + "/" + resource.id,
+            location=f"v2/{resource_type.endpoint.strip('/')}/{resource.id}",
         )
         self._touch_resource(resource, utcnow)
         self._check_uniqueness(resource)

{scim2_server-0.3.2 → scim2_server-0.4.0}/scim2_server/cli.py

@@ -4,6 +4,7 @@ import logging
 import pprint
 from collections.abc import Iterable
 from typing import TYPE_CHECKING
+from typing import Any
 
 from scim2_models import AuthenticationScheme
 from scim2_models import External
@@ -16,6 +17,7 @@ from werkzeug.middleware.proxy_fix import ProxyFix
 
 from scim2_server.backend import InMemoryBackend
 from scim2_server.provider import SCIMApplication
+from scim2_server.tenants import TenantDispatcher
 from scim2_server.utils import load_default_resource_types
 from scim2_server.utils import load_default_schemas
 from scim2_server.utils import load_default_service_provider_config
@@ -45,6 +47,11 @@ def log_environ(handler: "WSGIApplication") -> "WSGIApplication":
     return _inner
 
 
+def dump_resources(backend: InMemoryBackend) -> list[dict[str, Any]]:
+    """Return the JSON representation of the resources of a backend."""
+    return [r.model_dump() for r in backend.resources]
+
+
 def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument(
@@ -71,6 +78,17 @@ def main() -> None:
         type=argparse.FileType("w"),
         help="Dump resources to a JSON file on exit",
     )
+    parser.add_argument(
+        "--tenant",
+        action="append",
+        help="Serve a tenant under /TENANT, with its own resources",
+    )
+    parser.add_argument(
+        "--dynamic-tenants",
+        action="store_true",
+        help="Create a tenant on the first request to /TENANT. "
+        "Any client can then create tenants, and they stay in memory until exit",
+    )
     parser.add_argument(
         "--debug",
         action="store_true",
@@ -112,16 +130,26 @@ def main() -> None:
             BEARER_TOKEN_SCHEME,
         ]
 
-    backend = InMemoryBackend()
-    app = SCIMApplication(
-        backend, ScimProvider.from_discovery(schemas, resource_types, config=config)
-    )
+    provider = ScimProvider.from_discovery(schemas, resource_types, config=config)
 
-    if args.bearer_token is not None:
-        for bearer_token in args.bearer_token:
+    backends: dict[str | None, InMemoryBackend] = {}
+
+    def make_application(tenant: str | None = None) -> SCIMApplication:
+        backends[tenant] = InMemoryBackend()
+        app = SCIMApplication(backends[tenant], provider)
+        for bearer_token in args.bearer_token or []:
             app.register_bearer_token(bearer_token)
+        return app
+
+    use_tenants = bool(args.tenant or args.dynamic_tenants)
+    wsgi_app: WSGIApplication
+    if use_tenants:
+        wsgi_app = TenantDispatcher(
+            make_application, args.tenant or [], dynamic=args.dynamic_tenants
+        )
+    else:
+        wsgi_app = make_application()
 
-    wsgi_app: WSGIApplication = app
     if args.debug:
         wsgi_app = log_environ(wsgi_app)
     if args.reverse_proxy:
@@ -139,8 +167,13 @@ def main() -> None:
     )
 
     if args.dump_resources:
+        dump: Any = (
+            {tenant: dump_resources(backend) for tenant, backend in backends.items()}
+            if use_tenants
+            else dump_resources(backends[None])
+        )
         with args.dump_resources as f:
-            f.write(json.dumps([r.model_dump() for r in backend.resources], indent=2))
+            f.write(json.dumps(dump, indent=2))
 
 
 if __name__ == "__main__":

{scim2_server-0.3.2 → scim2_server-0.4.0}/scim2_server/provider.py

@@ -36,6 +36,7 @@ from werkzeug import Response
 from werkzeug.datastructures import ETags
 from werkzeug.exceptions import Forbidden
 from werkzeug.exceptions import HTTPException
+from werkzeug.exceptions import MethodNotAllowed
 from werkzeug.exceptions import NotFound
 from werkzeug.exceptions import NotImplemented as WerkzeugNotImplemented
 from werkzeug.exceptions import PreconditionFailed
@@ -43,6 +44,7 @@ from werkzeug.exceptions import RequestEntityTooLarge
 from werkzeug.exceptions import Unauthorized
 from werkzeug.http import parse_etags
 from werkzeug.http import unquote_etag
+from werkzeug.routing import BaseConverter
 from werkzeug.routing import Map
 from werkzeug.routing import Rule
 from werkzeug.routing.exceptions import RequestRedirect
@@ -79,6 +81,20 @@ BULK_SUCCESS_STATUS = {
 }
 
 
+class ResourceEndpointConverter(BaseConverter):
+    """Match a resource endpoint, but not the endpoints RFC 7644 reserves nor the version prefix.
+
+    A request with a method a reserved endpoint does not support then gets a
+    405 answer, instead of being routed to a resource type of that name.
+    """
+
+    # A reserved name followed by the end of the path segment is refused.
+    regex = (
+        r"(?!(?:ServiceProviderConfig|ResourceTypes|Schemas|Bulk|Me|v2)(?![^/]))[^/]+"
+    )
+    part_isolating = True
+
+
 class SCIMApplication:
     """A WSGI application implementing a SCIM provider (server)."""
 
@@ -123,17 +139,17 @@ class SCIMApplication:
                     methods=("GET", "POST", "PUT", "PATCH", "DELETE"),
                 ),
                 Rule(
-                    f"{prefix}/<string:resource_endpoint>",
+                    f"{prefix}/<resource_endpoint:resource_endpoint>",
                     endpoint="resource",
                     methods=("GET", "POST"),
                 ),
                 Rule(
-                    f"{prefix}/<string:resource_endpoint>/.search",
+                    f"{prefix}/<resource_endpoint:resource_endpoint>/.search",
                     endpoint="resource_search",
                     methods=("POST",),
                 ),
                 Rule(
-                    f"{prefix}/<string:resource_endpoint>/<string:resource_id>",
+                    f"{prefix}/<resource_endpoint:resource_endpoint>/<string:resource_id>",
                     endpoint="single_resource",
                     methods=("GET", "PUT", "PATCH", "DELETE"),
                 ),
@@ -148,7 +164,9 @@ class SCIMApplication:
             for prefix in ("", "/v2")
         )
 
-        self.url_map = Map(rules)
+        self.url_map = Map(
+            rules, converters={"resource_endpoint": ResourceEndpointConverter}
+        )
 
     def get_model(self, resource_type: ResourceType) -> type[Resource[Any]]:
         """Return the model of a resource type, its extensions included."""
@@ -178,12 +196,12 @@ class SCIMApplication:
     def publish(self, request: Request, resource: Resource[Any]) -> Resource[Any]:
         """Return a copy of a resource in the form sent to the client.
 
-        Its location is made absolute from the URL the client requested, and
+        Its location is made absolute from the root URL of the application, and
         its version is left out when the service does not support ETags.
         """
         assert resource.meta is not None
         update: dict[str, Any] = {
-            "location": urljoin(request.url + "/", resource.meta.location)
+            "location": urljoin(request.url_root, resource.meta.location)
         }
         if not self.etag_supported:
             update["version"] = None
@@ -811,7 +829,11 @@ class SCIMApplication:
             self.log.exception(e)
             return e.get_response(environ)
         except Exception as e:
-            return self.make_error(self.error_from(e))
+            response = self.make_error(self.error_from(e))
+            if isinstance(e, MethodNotAllowed) and e.valid_methods:
+                # RFC 9110 §15.5.6: a 405 answer lists the supported methods.
+                response.headers["Allow"] = ", ".join(sorted(e.valid_methods))
+            return response
 
     def __call__(
         self, environ: "WSGIEnvironment", start_response: "StartResponse"

scim2_server-0.4.0/scim2_server/tenants.py

@@ -0,0 +1,87 @@
+from collections.abc import Callable
+from collections.abc import Iterable
+from threading import Lock
+from typing import TYPE_CHECKING
+
+from scim2_models import Error
+
+from scim2_server.provider import SCIMApplication
+
+if TYPE_CHECKING:
+    from _typeshed.wsgi import StartResponse
+    from _typeshed.wsgi import WSGIEnvironment
+
+RESERVED_TENANTS = frozenset({"v2"})
+
+
+class TenantDispatcher:
+    """A WSGI application serving each tenant with its own SCIM application.
+
+    The tenant is the first segment of the request path, as in the URL prefix
+    method of RFC 7644 §6.1: a request to ``/<tenant>/v2/Users`` is served by
+    the application of ``<tenant>``, mounted under ``/<tenant>``.
+
+    :param factory: Build the application of a tenant from its name.
+    :param tenants: The tenants created at startup.
+    :param dynamic: Whether a request to an unknown tenant creates it. Any
+        client can then create tenants, and each one stays in memory.
+    """
+
+    def __init__(
+        self,
+        factory: Callable[[str], SCIMApplication],
+        tenants: Iterable[str] = (),
+        dynamic: bool = False,
+    ):
+        self.factory = factory
+        self.dynamic = dynamic
+        self.applications: dict[str, SCIMApplication] = {}
+        self.lock = Lock()
+        for tenant in tenants:
+            if not self.is_valid_tenant(tenant):
+                raise ValueError(f"Invalid tenant name: {tenant!r}")
+            self.applications[tenant] = factory(tenant)
+
+    @staticmethod
+    def is_valid_tenant(tenant: str) -> bool:
+        """Tell whether a name can identify a tenant.
+
+        The version segment is refused, so that a request without a tenant is
+        not served by a tenant named ``v2``.
+        """
+        return bool(tenant) and "/" not in tenant and tenant not in RESERVED_TENANTS
+
+    def select_tenant(self, environ: "WSGIEnvironment") -> str | None:
+        """Return the tenant of a request, and move it from the path to the mount prefix.
+
+        Override this method to read the tenant from somewhere else, such as
+        a header or a sub-domain (RFC 7644 §6.1).
+        """
+        path_info: str = environ.get("PATH_INFO", "")
+        _, _, path = path_info.partition("/")
+        tenant, separator, rest = path.partition("/")
+        if not self.is_valid_tenant(tenant):
+            return None
+        environ["SCRIPT_NAME"] = f"{environ.get('SCRIPT_NAME', '')}/{tenant}"
+        environ["PATH_INFO"] = separator + rest
+        return tenant
+
+    def get_application(self, tenant: str) -> SCIMApplication | None:
+        """Return the application of a tenant, creating it if tenants are dynamic."""
+        with self.lock:
+            if tenant not in self.applications and self.dynamic:
+                self.applications[tenant] = self.factory(tenant)
+            return self.applications.get(tenant)
+
+    def __call__(
+        self, environ: "WSGIEnvironment", start_response: "StartResponse"
+    ) -> Iterable[bytes]:
+        """Dispatch a request to the application of its tenant."""
+        tenant = self.select_tenant(environ)
+        application = self.get_application(tenant) if tenant is not None else None
+        if application is None:
+            response = SCIMApplication.make_response(
+                Error(status=404, detail="Unknown tenant").model_dump(), status=404
+            )
+            return response(environ, start_response)
+        return application(environ, start_response)