ruscker-sso (Python)
Sign people in to a Python backend through a Ruscker portal ("Sign in with …"). A thin wrapper over PyJWT and httpx pre-set for the provider's profile: authorization code + PKCE, ID tokens signed with ES256 only. It follows the contract shared by every client package.
Two calls do the work: start_sign_in() builds the URL to send the
browser to, and finish_sign_in() checks the callback, redeems the code
and verifies the ID token, in that order. The package does not keep
sessions: after a sign-in, the application issues its own.
Install
Python 3.10 or later. The package is not on PyPI; install it from this directory:
pip install ./clients/python # or: uv add ./clients/python
Example: FastAPI
The three pending values live in Starlette's signed session cookie for
the few minutes between the two routes (pip install fastapi uvicorn itsdangerous).
import os
from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse
from starlette.middleware.sessions import SessionMiddleware
from ruscker_sso import PendingSignIn, RusckerSSO, SignInError
sso = RusckerSSO(
issuer="https://portal.example.org",
client_id="my-system",
client_secret=os.environ["RUSCKER_CLIENT_SECRET"],
redirect_uri="https://app.example.org/auth/callback",
)
app = FastAPI()
# Signed (not encrypted) cookie, HttpOnly; https_only in production.
app.add_middleware(SessionMiddleware, secret_key=os.environ["APP_SESSION_KEY"],
https_only=True, same_site="lax")
@app.get("/auth/login")
def login(request: Request):
sign_in = sso.start_sign_in()
request.session["ruscker_pending"] = sign_in.pending.to_json()
return RedirectResponse(sign_in.url)
@app.get("/auth/callback")
def callback(request: Request):
stored = request.session.pop("ruscker_pending", None) # single use
if stored is None:
return RedirectResponse("/auth/login")
try:
person = sso.finish_sign_in(request.query_params, PendingSignIn.from_json(stored))
except SignInError as exc:
return RedirectResponse(f"/?signin_failed={type(exc).__name__}")
# The application's own session from here on. Key the account by `sub`.
request.session["user"] = {"sub": person.sub, "name": person.name,
"is_manager": person.has_role("fiscal", "gestor")}
return RedirectResponse("/")
The calls are synchronous (they make two short HTTP requests on the
first sign-in, then one); FastAPI runs a plain def route in a thread
pool. The same two calls work in Flask (session, request.args) and
Django (request.session, request.GET): store pending.to_json(),
then pass the query and PendingSignIn.from_json(...) back.
Create one RusckerSSO at start-up and share it: it caches the
discovery document and the keys, and is thread-safe. Pass
http_client=httpx.Client(...) for proxies or a custom CA bundle.
The identity
| Attribute | Claim | Notes |
|---|---|---|
sub |
sub |
permanent id. The key to store |
username |
preferred_username |
None without the profile scope |
name |
name |
full name, or the username |
email |
email |
may be None |
setor |
setor |
department; may be None |
groups |
groups |
list; only the groups that give access to this system when it is restricted |
group_roles |
group_roles |
dict group → list of roles; {} when none |
claims |
— | every claim of the verified token |
Helpers: has_group(g), has_role(group, role), roles(group).
Default scopes: openid profile email groups roles setor; pass
scopes=[...] to ask for less (openid is always added).
Errors
All are SignInError; catch that one for "sign-in failed".
| Exception | When | Useful attributes |
|---|---|---|
ProviderError |
the callback carries error= (e.g. access_denied: not in the system's groups) |
code, description |
StateMismatchError |
state differs from the stored one; nothing was sent to the provider |
|
IssuerMismatchError |
the callback's iss, or the discovery document's issuer, is not the configured issuer |
expected, got, where |
TokenExchangeError |
the token endpoint refused the code (invalid_grant: used, expired, other verifier; invalid_client: wrong secret) |
status, error, description |
InvalidIDTokenError |
the ID token failed verification | reason: signature, algorithm, audience, issuer, expired, not_yet_valid, nonce, missing_claim, unknown_key, malformed, claims |
SignInError itself |
provider unreachable, malformed response, no code, unreadable stored values |
A code works once. Whatever the outcome, start a new sign-in rather than retrying.
Tests
cd clients/python
uv run --with pytest --with-editable . pytest # unit tests, no network
The end-to-end test runs against a real provider started with
clients/testing/provider.sh (see the testing notes)
and is skipped when RUSCKER_ISSUER is unset:
source /tmp/sso-dev/env
uv run --with pytest --with-editable . pytest -v tests/test_e2e.py
Metadata
Release files for ruscker-sso 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ruscker_sso-0.1.0.tar.gz | 19.4 kB | With provenance | Details for ruscker_sso-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ruscker_sso-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ruscker_sso-0.1.0-py3-none-any.whl |
Total release size: 36.2 kB
Release files / ruscker_sso-0.1.0.tar.gz
| Download URL | ruscker_sso-0.1.0.tar.gz |
|---|---|
| Size | 19.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e12b52c24ed67b4417b94bacf816410ad6b4fa87dde778bd07651325459acea6
|
|
BLAKE2b-256 checksum How to use checksums |
80ccbf409fe9428d4509064a8dc8f337f2b2ade0233690f3d739dec1f0aa6f19
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / ruscker_sso-0.1.0-py3-none-any.whl
| Download URL | ruscker_sso-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e85cb3ec534e4b860ecb248764eef8e4f9aa2dbc45d6b77193660f019867b4b1
|
|
BLAKE2b-256 checksum How to use checksums |
d0910a5a71e5cf8123da8428b1aaf8d244c64c66ce9ffa4a5b7d86e4606f98d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for ruscker-sso 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ruscker_sso-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.