SCIM2 Server Prototype

0.1.9 · active · verified Fri Apr 17

scim2-server is a lightweight prototype implementation of a SCIM2 (System for Cross-domain Identity Management) server using FastAPI. It provides basic in-memory reference implementations for SCIM2 user and group management, primarily intended as a starting point or demonstration rather than a production-ready server. The current version is 0.1.9, with an irregular release cadence as a 'prototype'.

Common errors

```
ModuleNotFoundError: No module named 'scim2-server'
```
cause Attempted to import using the package name (`scim2-server` with a hyphen) instead of the correct module name (`scim2_server` with an underscore).

fix Change your import statement from `from scim2-server import ...` to `from scim2_server import ...`.
```
uvicorn.run(): No application object specified. Ensure your run command points to your FastAPI app.
```
cause Uvicorn was either not installed, or the command to start the server was incorrect, preventing it from finding the FastAPI application instance.

fix First, ensure `uvicorn` is installed (`pip install uvicorn`). Then, make sure your startup command correctly points to your FastAPI app, e.g., if your app is named `app` in `main.py`, run `uvicorn main:app --reload`.
```
PydanticValidationError: 1 validation error for SCIM2User
userName
  field required (type=value_error.missing)
```
cause When creating `SCIM2User` or `SCIM2Group` objects, a required field (like `userName` for users or `displayName` for groups) was omitted or provided with an invalid type.

fix Refer to the SCIM2 specification and the library's Pydantic models (e.g., `SCIM2User` definition) to ensure all required attributes are provided with valid data types upon instantiation.

Warnings

gotcha This library is explicitly a 'prototype' and 'in-memory reference implementation'. It is not designed for production use without significant modification for persistence, scalability, and security.
Fix: Understand its limitations. Consider it a starting point for a custom SCIM server implementation, not a ready-to-deploy solution. You will need to replace its in-memory storage with a proper database.
gotcha The package name for installation is `scim2-server` (with a hyphen), but the Python module name for imports is `scim2_server` (with an underscore).
Fix: Always use `from scim2_server import ...` in your Python code, never `from scim2-server import ...`.
gotcha Running the SCIM2 server requires FastAPI and an ASGI server like Uvicorn. While FastAPI is a direct dependency, Uvicorn (though listed) requires explicit installation and knowledge of how to start a FastAPI app.
Fix: Ensure `uvicorn` is installed (`pip install uvicorn`) and you use the correct command to run your FastAPI application, typically `uvicorn main:app --reload` (replace `main:app` with your module and app instance).

Install

pip install scim2-server Install core library
pip install uvicorn Install ASGI server for running

Imports

SCIM2Server
wrong:
```
from scim2-server import SCIM2Server
```
correct:
```
from scim2_server import SCIM2Server
```
The package name is 'scim2-server' (with a hyphen), but the importable module name is 'scim2_server' (with an underscore).
SCIM2User
wrong:
```
from scim2server.models import SCIM2User
```
correct:
```
from scim2_server import SCIM2User
```
SCIM2User and SCIM2Group are directly available at the top-level module.
SCIM2Group
```
from scim2_server import SCIM2Group
```
Directly available from the main module.

Quickstart

This quickstart sets up a basic FastAPI application embedding the `scim2-server` router. It initializes an in-memory SCIM2 server, adds a sample user and group, and then runs the FastAPI app using Uvicorn. Access SCIM endpoints at `/scim/v2`.

import uvicorn
from fastapi import FastAPI
from scim2_server import SCIM2Server, SCIM2User, SCIM2Group

# Initialize SCIM2 server with in-memory storage
scim_server = SCIM2Server()

# Optional: Add some initial data
scim_server.users.create(SCIM2User(id='user1', userName='john.doe', emails=[{'value': 'john.doe@example.com', 'primary': True}]))
scim_server.groups.create(SCIM2Group(id='group1', displayName='Developers'))

# Create a FastAPI app and include the SCIM2 router
app = FastAPI(title="SCIM2 Prototype API")
app.include_router(scim_server.router, prefix="/scim/v2")

@app.get("/")
async def root():
    return {"message": "SCIM2 server is running! Access /scim/v2"}

# To run this: save as main.py and execute 'uvicorn main:app --reload'
# The example below demonstrates running programmatically for convenience,
# but 'uvicorn main:app' is the typical way.
if __name__ == '__main__':
    # Note: For production, typically run with `uvicorn main:app` from terminal.
    # This programmatic run is for quick demonstration.
    print("\n--- Running SCIM2 Server Prototype ---")
    print("Access SCIM endpoints at: http://127.0.0.1:8000/scim/v2")
    print("Try: http://127.0.0.1:8000/scim/v2/Users")
    uvicorn.run(app, host="127.0.0.1", port=8000)

view raw JSON →