scim2-server 0.3.3__tar.gz → 0.5.0__tar.gz

{scim2_server-0.3.3 → scim2_server-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: scim2-server
-Version: 0.3.3
-Summary: Lightweight SCIM2 server prototype
+Version: 0.5.0
+Summary: SCIM server core for any storage and web framework
 Keywords: scim,scim2,provisioning,rfc7643,rfc7644
 Author: Yaal Coop, Christian Friedrich Coors
 Author-email: Yaal Coop <contact@yaal.coop>, Christian Friedrich Coors <me@ccoors.de>
@@ -217,73 +217,110 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Environment :: Web Environment
 Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
-Requires-Dist: scim2-models>=0.10.0
-Requires-Dist: werkzeug>=3.0.3
+Requires-Dist: scim2-models>=0.10.3
+Requires-Dist: pytest>=9.1.1 ; extra == 'testing'
 Requires-Python: >=3.11
 Project-URL: repository, https://github.com/python-scim/scim2-server
 Project-URL: funding, https://github.com/sponsors/python-scim
+Provides-Extra: testing
 Description-Content-Type: text/markdown
 
 # scim2-server
 
-This is an example WSGI-SCIM server using [scim2-models](https://github.com/python-scim/scim2-models).
-It utilizes [werkzeug](https://werkzeug.palletsprojects.com/) and keeps all resources in-memory,
-they are lost once the process exits.
+A Python library that serves the SCIM protocol over any storage, built upon
+[scim2-models](https://scim2-models.readthedocs.io), following the
+[RFC7643](https://datatracker.ietf.org/doc/html/rfc7643.html) and
+[RFC7644](https://datatracker.ietf.org/doc/html/rfc7644.html) specifications.
+It validates the requests, applies them to the resources and builds the responses.
+The application only reads and writes the resources.
+
+It comes with an in-memory storage, WSGI and ASGI applications with no dependency, and a
+`scim2-server` command that serves a test server.
+
+## Who is it for?
+
+scim2-server is for projects that need to:
+
+- serve a standalone SCIM server;
+- add SCIM to an existing application, with SCIM models that describe its data;
+- test a SCIM client against a working server, from the `scim2-server` command, a container, or
+  the [pytest-scim2-server](https://github.com/pytest-dev/pytest-scim2-server) fixture.
+
+## What's SCIM anyway?
+
+SCIM stands for System for Cross-domain Identity Management, and it is a provisioning protocol.
+Provisioning is the action of managing a set of resources across different services, usually users and groups.
+SCIM is often used between Identity Providers and applications in completion of standards like OAuth2 and OpenID Connect.
+It allows users and groups creations, modifications and deletions to be synchronized between applications.
 
 ## Features
 
-- [x] Discovery endpoints (`/v2/ServiceProviderConfig`, `/v2/ResourceTypes`, `/v2/Schemas`)
-- [x] Create/Read/Update/Delete resources (`POST`, `GET`, `PUT`, `DELETE`)
-- [x] Searching & Filtering
-- [x] Support for ETags
-- [x] Unique Constraints
-- [x] HTTP PATCH (Add/Remove/Replace)
-- [x] Sorting
-- [x] Bulk operations
+- **Resources**: creation, read, replacement, PATCH and deletion
+- **Search**: filters, sorting, paging and attribute selection, on a resource type or at the root
+- **Bulk requests**: with `bulkId` references and `failOnErrors`
+- **ETags**: conditional requests and protection against concurrent writes
+- **Discovery**: `ServiceProviderConfig`, `ResourceTypes` and `Schemas`
+- **Storages**: an interface to implement, an in-memory storage, and a test suite that checks a storage
+- **Sync & Async**: a synchronous and an asynchronous handler, over the same rules
+- **Multi-tenancy**: one set of resources per URL prefix
 
-## Usage
+## Installation
 
 ```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]
+pip install scim2-server
 ```
 
-- `-h`/`--help`: Show help message
-- `--reverse-proxy`: Allow using the provider behind a Reverse Proxy (required for URL rewriting).
-- `--schema`: Register schemas from specified JSON file. If not provided, loads the default schemas from RFC 7643.
-- `--resource-type`: Register resource types from specified JSON file. If not provided, loads the default resource types from RFC 7643.
-- `--service-provider-config`: Load the service provider configuration from specified JSON file. If not provided, loads the default configuration.
-- `--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.
-- `--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.
-
-### Container
+## Usage
 
-A container image is published on the GitHub container registry for each release.
-The server listens on `0.0.0.0:8080` inside the container, and the command line arguments are passed to `scim2-server`:
+Serve a test server from the command line:
 
 ```shell
-$ docker run --publish 8080:8080 ghcr.io/python-scim/scim2-server --bearer-token secret
+scim2-server --port 8080
 ```
 
-To build the image yourself, use `docker build --file Containerfile .` or `podman build .`.
+Or build the WSGI application in Python:
 
-## Notes
+```python
+from scim2_server.applications.wsgi import WSGIApplication
+from scim2_server.memory import InMemoryStorage
+from scim2_server.utils import load_default_provider
 
-This provider can be used as a starting point if you want to implement a SCIM provider. You should probably change the following things, if you want to use it in production:
+app = WSGIApplication(InMemoryStorage(), load_default_provider())
+```
 
-- Use a proper production WSGI server instead of the one provided by Werkzeug
-- 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
+A container image is published on the GitHub container registry for each release:
 
-The provider in its current state has been tested successfully against a live
+```shell
+docker run --publish 8080:8080 ghcr.io/python-scim/scim2-server --bearer-token secret
+```
+
+The server has been tested against a live
 [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)
-system as well as a live
+system and a live
 [Okta](https://developer.okta.com/docs/guides/scim-provisioning-integration-test/main/) system.
 
+## Documentation
+
+- [Overview](https://scim2-server.readthedocs.io/en/latest/overview.html) introduces the parts of
+  a SCIM server, from the description of the service to the test server.
+- [How-to guides](https://scim2-server.readthedocs.io/en/latest/how-to/index.html) cover focused
+  tasks, such as writing a storage or integrating a web framework.
+- [Explanation](https://scim2-server.readthedocs.io/en/latest/explanation/index.html) covers the
+  layers of the server, the writes of resources and the bulk requests.
+- [Reference](https://scim2-server.readthedocs.io/en/latest/reference.html) lists the public API
+  and the options of the `scim2-server` command.
+
+## Contributing
+
+The [contribution page](https://scim2-server.readthedocs.io/en/latest/contributing.html)
+describes how to run the tests, the style checks and the documentation build.
+
+scim2-server belongs in a collection of SCIM tools developed by [Yaal Coop](https://yaal.coop),
+with [scim2-models](https://github.com/python-scim/scim2-models),
+[scim2-client](https://github.com/python-scim/scim2-client),
+[scim2-tester](https://github.com/python-scim/scim2-tester) and
+[scim2-cli](https://github.com/python-scim/scim2-cli).
+
 ## Origins
 
 Parts of this software were initially developed at [CONTACT Software](https://www.contact-software.com/) ([GitHub](https://github.com/cslab)) and subsequently made available under the Apache License Version 2.0.

scim2_server-0.5.0/README.md

@@ -0,0 +1,99 @@
+# scim2-server
+
+A Python library that serves the SCIM protocol over any storage, built upon
+[scim2-models](https://scim2-models.readthedocs.io), following the
+[RFC7643](https://datatracker.ietf.org/doc/html/rfc7643.html) and
+[RFC7644](https://datatracker.ietf.org/doc/html/rfc7644.html) specifications.
+It validates the requests, applies them to the resources and builds the responses.
+The application only reads and writes the resources.
+
+It comes with an in-memory storage, WSGI and ASGI applications with no dependency, and a
+`scim2-server` command that serves a test server.
+
+## Who is it for?
+
+scim2-server is for projects that need to:
+
+- serve a standalone SCIM server;
+- add SCIM to an existing application, with SCIM models that describe its data;
+- test a SCIM client against a working server, from the `scim2-server` command, a container, or
+  the [pytest-scim2-server](https://github.com/pytest-dev/pytest-scim2-server) fixture.
+
+## What's SCIM anyway?
+
+SCIM stands for System for Cross-domain Identity Management, and it is a provisioning protocol.
+Provisioning is the action of managing a set of resources across different services, usually users and groups.
+SCIM is often used between Identity Providers and applications in completion of standards like OAuth2 and OpenID Connect.
+It allows users and groups creations, modifications and deletions to be synchronized between applications.
+
+## Features
+
+- **Resources**: creation, read, replacement, PATCH and deletion
+- **Search**: filters, sorting, paging and attribute selection, on a resource type or at the root
+- **Bulk requests**: with `bulkId` references and `failOnErrors`
+- **ETags**: conditional requests and protection against concurrent writes
+- **Discovery**: `ServiceProviderConfig`, `ResourceTypes` and `Schemas`
+- **Storages**: an interface to implement, an in-memory storage, and a test suite that checks a storage
+- **Sync & Async**: a synchronous and an asynchronous handler, over the same rules
+- **Multi-tenancy**: one set of resources per URL prefix
+
+## Installation
+
+```shell
+pip install scim2-server
+```
+
+## Usage
+
+Serve a test server from the command line:
+
+```shell
+scim2-server --port 8080
+```
+
+Or build the WSGI application in Python:
+
+```python
+from scim2_server.applications.wsgi import WSGIApplication
+from scim2_server.memory import InMemoryStorage
+from scim2_server.utils import load_default_provider
+
+app = WSGIApplication(InMemoryStorage(), load_default_provider())
+```
+
+A container image is published on the GitHub container registry for each release:
+
+```shell
+docker run --publish 8080:8080 ghcr.io/python-scim/scim2-server --bearer-token secret
+```
+
+The server has been tested against a live
+[Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/scim-validator-tutorial)
+system and a live
+[Okta](https://developer.okta.com/docs/guides/scim-provisioning-integration-test/main/) system.
+
+## Documentation
+
+- [Overview](https://scim2-server.readthedocs.io/en/latest/overview.html) introduces the parts of
+  a SCIM server, from the description of the service to the test server.
+- [How-to guides](https://scim2-server.readthedocs.io/en/latest/how-to/index.html) cover focused
+  tasks, such as writing a storage or integrating a web framework.
+- [Explanation](https://scim2-server.readthedocs.io/en/latest/explanation/index.html) covers the
+  layers of the server, the writes of resources and the bulk requests.
+- [Reference](https://scim2-server.readthedocs.io/en/latest/reference.html) lists the public API
+  and the options of the `scim2-server` command.
+
+## Contributing
+
+The [contribution page](https://scim2-server.readthedocs.io/en/latest/contributing.html)
+describes how to run the tests, the style checks and the documentation build.
+
+scim2-server belongs in a collection of SCIM tools developed by [Yaal Coop](https://yaal.coop),
+with [scim2-models](https://github.com/python-scim/scim2-models),
+[scim2-client](https://github.com/python-scim/scim2-client),
+[scim2-tester](https://github.com/python-scim/scim2-tester) and
+[scim2-cli](https://github.com/python-scim/scim2-cli).
+
+## Origins
+
+Parts of this software were initially developed at [CONTACT Software](https://www.contact-software.com/) ([GitHub](https://github.com/cslab)) and subsequently made available under the Apache License Version 2.0.

{scim2_server-0.3.3 → scim2_server-0.5.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.3.3"
-description = "Lightweight SCIM2 server prototype"
+version = "0.5.0"
+description = "SCIM server core for any storage and web framework"
 readme = "README.md"
 keywords = [
     "scim",
@@ -28,10 +28,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 requires-python = ">= 3.11"
-dependencies = [
-    "scim2-models>=0.10.0",
-    "werkzeug>=3.0.3",
-]
+dependencies = ["scim2-models>=0.10.3"]
 
 [[project.authors]]
 name = "Yaal Coop"
@@ -44,12 +41,15 @@ email = "me@ccoors.de"
 [project.license]
 file = "LICENSE"
 
+[project.optional-dependencies]
+testing = ["pytest>=9.1.1"]
+
 [project.urls]
 repository = "https://github.com/python-scim/scim2-server"
 funding = "https://github.com/sponsors/python-scim"
 
 [project.scripts]
-scim2-server = "scim2_server.cli:main"
+scim2-server = "scim2_server.testserver.cli:main"
 
 [dependency-groups]
 dev = [
@@ -59,7 +59,18 @@ dev = [
     "prek>=0.1.0",
     "time-machine>=2.14.2",
     "tox-uv>=1.16.0",
+    "aiosqlite>=0.22.1",
     "mypy>=2.3.1",
+    "scim2-client[werkzeug]>=0.11.2",
+    "scim2-tester>=0.5.1",
+    "werkzeug>=3.0.3",
+]
+doc = [
+    "shibuya>=2024.5.15",
+    "sphinx>=7.3.7",
+    "sphinx-argparse>=0.6.1",
+    "sphinx-design>=0.6.1",
+    "sphinx-issues>=5.0.0",
 ]
 
 [tool.uv]
@@ -93,7 +104,7 @@ source = [
 omit = [
     ".tox/*",
     "examples/*",
-    "scim2_server/cli.py",
+    "scim2_server/testserver/cli.py",
 ]
 branch = true
 
@@ -138,7 +149,8 @@ force-single-line = true
 docstring-code-format = true
 
 [tool.pytest.ini_options]
-addopts = "--doctest-modules --doctest-glob='*.rst'"
+addopts = "--doctest-modules --doctest-glob='*.rst' --ignore=doc/conf.py"
+pythonpath = ["doc/_examples"]
 doctest_optionflags = "ALLOW_UNICODE IGNORE_EXCEPTION_DETAIL ELLIPSIS"
 
 [tool.tox]
@@ -150,6 +162,7 @@ env_list = [
     "py313",
     "py314",
     "minversions",
+    "doc",
     "coverage",
 ]
 
@@ -176,6 +189,18 @@ commands = [[
 runner = "uv-venv-runner"
 uv_resolution = "lowest-direct"
 
+[tool.tox.env.doc]
+dependency_groups = ["doc"]
+commands = [[
+    "sphinx-build",
+    "-W",
+    "--keep-going",
+    "--builder",
+    "html",
+    "doc",
+    "build/sphinx/html",
+]]
+
 [tool.tox.env.coverage]
 commands = [
     [

{scim2_server-0.3.3 → scim2_server-0.5.0}/pyproject.toml.orig

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 
 [project]
 name = "scim2-server"
-version = "0.3.3"
-description = "Lightweight SCIM2 server prototype"
+version = "0.5.0"
+description = "SCIM server core for any storage and web framework"
 authors = [
     {name="Yaal Coop", email="contact@yaal.coop"},
     {name="Christian Friedrich Coors", email="me@ccoors.de"},
@@ -29,8 +29,12 @@ classifiers = [
 
 requires-python = ">= 3.11"
 dependencies = [
-    "scim2-models>=0.10.0",
-    "werkzeug>=3.0.3",
+    "scim2-models>=0.10.3",
+]
+
+[project.optional-dependencies]
+testing = [
+    "pytest>=9.1.1",
 ]
 
 [project.urls]
@@ -38,7 +42,7 @@ repository = "https://github.com/python-scim/scim2-server"
 funding = "https://github.com/sponsors/python-scim"
 
 [project.scripts]
-scim2-server = "scim2_server.cli:main"
+scim2-server = "scim2_server.testserver.cli:main"
 
 [dependency-groups]
 dev = [
@@ -48,7 +52,18 @@ dev = [
     "prek>=0.1.0",
     "time-machine>=2.14.2",
     "tox-uv>=1.16.0",
+    "aiosqlite>=0.22.1",
     "mypy>=2.3.1",
+    "scim2-client[werkzeug]>=0.11.2",
+    "scim2-tester>=0.5.1",
+    "werkzeug>=3.0.3",
+]
+doc = [
+    "shibuya>=2024.5.15",
+    "sphinx>=7.3.7",
+    "sphinx-argparse>=0.6.1",
+    "sphinx-design>=0.6.1",
+    "sphinx-issues>=5.0.0",
 ]
 
 [tool.uv]
@@ -74,7 +89,7 @@ source = [
     "scim2_server",
     "tests",
 ]
-omit = [".tox/*", "examples/*", "scim2_server/cli.py"]
+omit = [".tox/*", "examples/*", "scim2_server/testserver/cli.py"]
 branch = true
 
 [tool.coverage.report]
@@ -119,7 +134,8 @@ docstring-code-format = true
 
 
 [tool.pytest.ini_options]
-addopts = "--doctest-modules --doctest-glob='*.rst'"
+addopts = "--doctest-modules --doctest-glob='*.rst' --ignore=doc/conf.py"
+pythonpath = ["doc/_examples"]
 doctest_optionflags= "ALLOW_UNICODE IGNORE_EXCEPTION_DETAIL ELLIPSIS"
 
 [tool.tox]
@@ -131,6 +147,7 @@ env_list = [
     "py313",
     "py314",
     "minversions",
+    "doc",
     "coverage",
 ]
 
@@ -151,6 +168,12 @@ commands = [
 runner = "uv-venv-runner"
 uv_resolution = "lowest-direct"
 
+[tool.tox.env.doc]
+dependency_groups = ["doc"]
+commands = [
+    ["sphinx-build", "-W", "--keep-going", "--builder", "html", "doc", "build/sphinx/html"],
+]
+
 [tool.tox.env.coverage]
 commands = [
     ["pytest", "--cov", "--cov-fail-under=100", "--cov-report", "term:skip-covered", "{posargs}"],

scim2_server-0.5.0/scim2_server/applications/__init__.py

@@ -0,0 +1 @@
+"""The WSGI and ASGI applications of the SCIM server."""

scim2_server-0.5.0/scim2_server/applications/asgi.py

@@ -0,0 +1,147 @@
+"""The ASGI application of the SCIM server, with no dependency."""
+
+import json
+from collections.abc import Awaitable
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import parse_qsl
+
+from scim2_models import SCIMException
+from scim2_models import ScimProvider
+
+from scim2_server.applications.base import VERSION_PREFIX
+from scim2_server.applications.base import BaseApplication
+from scim2_server.handler import AsyncScimHandler
+from scim2_server.requests import ScimRequest
+from scim2_server.responses import ScimResponse
+from scim2_server.service import ScimService
+from scim2_server.storage import AsyncScimStorage
+
+Scope = dict[str, Any]
+Message = dict[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+
+class ASGIApplication(BaseApplication):
+    """An ASGI application serving the SCIM protocol over an asynchronous storage.
+
+    It reads the ASGI requests, serves them with an
+    :class:`~scim2_server.handler.AsyncScimHandler`, and writes the responses.
+    It answers the ``lifespan`` messages of the server.
+
+    :param storage: The storage of the resources.
+    :param provider: The description of the service.
+    :param service: The service serving the requests, built upon ``provider``.
+    """
+
+    def __init__(
+        self,
+        storage: AsyncScimStorage,
+        provider: ScimProvider,
+        service: ScimService | None = None,
+    ):
+        super().__init__(provider, service)
+        self.storage = storage
+        self.handler = AsyncScimHandler(self.service, storage)
+
+    @staticmethod
+    def get_base_url(scope: Scope) -> str:
+        """Return the root URL of the SCIM endpoints, as the client sees it."""
+        headers = dict(scope["headers"])
+        host = headers.get(b"host", b"").decode()
+        if not host and scope.get("server"):
+            host = "{}:{}".format(*scope["server"])
+        return f"{scope['scheme']}://{host}{scope.get('root_path', '')}{VERSION_PREFIX}"
+
+    @staticmethod
+    def get_path(scope: Scope) -> str:
+        """Return the path of a request, without the root path of the application.
+
+        The ``path`` of an ASGI scope includes its ``root_path``.
+        """
+        path: str = scope["path"]
+        root_path: str = scope.get("root_path", "")
+        return path.removeprefix(root_path) if root_path else path
+
+    async def read_request(self, scope: Scope, receive: Receive) -> ScimRequest:
+        """Return the SCIM request of an ASGI request.
+
+        The body is read up to one byte more than the service accepts, so that
+        the service answers 413 to a larger body.
+        """
+        request = ScimRequest(
+            method=scope["method"],
+            base_url=self.get_base_url(scope),
+            path=self.split_path(self.get_path(scope)),
+            query=dict(parse_qsl(scope["query_string"].decode())),
+            headers=[
+                (name.decode(), value.decode()) for name, value in scope["headers"]
+            ],
+        )
+        try:
+            limit = self.service.max_body_size(request)
+        except SCIMException:
+            limit = None
+        body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            if limit is None or len(body) <= limit:
+                body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+        request.body = body if limit is None else body[: limit + 1]
+        return request
+
+    async def dispatch_request(self, request: ScimRequest) -> ScimResponse:
+        """Authenticate a request and serve it.
+
+        Override this method to act before or after a request is served.
+        """
+        if self.needs_auth(request):
+            self.check_auth(request)
+        request.subject = self.get_subject(request)
+        return await self.handler.handle(request)
+
+    async def serve(self, request: ScimRequest) -> ScimResponse:
+        """Serve a request and return the response sent to the client."""
+        try:
+            response = await self.dispatch_request(request)
+        except Exception as exception:
+            response = self.handle_exception(request, exception)
+        return self.finalize_response(request, response)
+
+    @staticmethod
+    async def send_response(response: ScimResponse, send: Send) -> None:
+        """Send a SCIM response as an ASGI response."""
+        body = b"" if response.body is None else json.dumps(response.body).encode()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": int(response.status),
+                "headers": [
+                    (name.encode(), value.encode())
+                    for name, value in response.headers.items()
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    @staticmethod
+    async def serve_lifespan(receive: Receive, send: Send) -> None:
+        """Answer the startup and the shutdown of the server."""
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            else:  # lifespan.shutdown
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Serve an ASGI request."""
+        if scope["type"] == "lifespan":
+            await self.serve_lifespan(receive, send)
+            return
+        request = await self.read_request(scope, receive)
+        await self.send_response(await self.serve(request), send)