Why?
xtr-security-oauth2-server issues access tokens: a client that holds one may act for somebody, and learns nothing about who that somebody is. "Sign in with this server" is the other half, and this package is it — an add-on bundle that turns that server into an OpenID Connect provider for the authorization code flow, without changing how the server works.
- 🪪 An ID token — the token answer to a sign-in carries a signed
id_tokennaming the end-user:iss,sub,aud,exp,iat,auth_time, thenoncethe client sent, and anat_hashbinding the access token answered beside it. - 👤
/userinfo—GETandPOST; answers the subject plus the claims the token's scopes reveal, from the application's own users, and fails closed. - 🔎
/.well-known/openid-configuration— one document: the authorization server's own description, with the provider's fields contributed to it. - 🔁
promptandmax_age—noneanswerslogin_requiredrather than showing a page,loginand an expiredmax_agesend the end-user back through the login page and return to the request,consentis read by the application's consent listener. - 🔑 One key, one key set — the ID token is signed with the authorization server's own signer
and
kid, so a client verifies it from the/.well-known/jwks.jsonthat server already publishes.
It follows OpenID Connect Core 1.0 and Discovery 1.0 for the authorization code flow, checked by
tests/conformance/, whose README lists every requirement, every deliberate deviation and the
optional manual run of the OpenID Foundation suite. Running that suite is not a claim this
repository makes.
Out of scope on purpose: no logout of any kind, no implicit or hybrid flow, no pairwise subjects,
no claims parameter, no request objects, no dynamic client registration, and no ID token on a
refresh.
Install
uv add xtr-security-openid-connect-server # the provider, its bundle and its endpoints
Requires Python 3.11+. It brings xtr-security-oauth2-server and its protocol library along, with the security family, the key layer, the clock, the event dispatcher and the HTTP kernel.
Quick start
A deployment whose authorization server already runs the code flow, signing end-users in.
1. List both bundles
# app/config/bundles.py
from xtr_security_oauth2_server.bundle import OAuth2ServerBundle
from xtr_security_openid_connect_server.bundle import OpenIdConnectServerBundle
BUNDLES = {OAuth2ServerBundle: {"all": True}, OpenIdConnectServerBundle: {"all": True}}
Listing the provider alone is enough: it requires the authorization server's bundle. The provider
puts its own flow and token answer in place of the shipped ones, and adds openid to
scopes.available when that tuple names anything at all.
2. Say where the users are
# app/identity_provider.py
from __future__ import annotations
from typing import TYPE_CHECKING, final
from xtr_security_core.exception import UserNotFoundError
if TYPE_CHECKING:
from collections.abc import Mapping
from xtr_security_oauth2_server_core.entities.client_entity_interface import (
ClientEntityInterface,
)
from xtr_security_openid_connect_server.entities import UserClaimsEntityInterface
@final
class Person:
"""A resource owner the server knows by identifier, with the claims they hold."""
def __init__(self, identifier: str, claims: Mapping[str, object]) -> None:
self._identifier = identifier
self._claims = claims
def get_identifier(self) -> str:
return self._identifier
async def get_claims(self) -> Mapping[str, object]:
return self._claims
@final
class PeopleIdentityProvider:
"""Finds the end-user a token names, and the claims that describe them."""
async def get_user_entity_by_identifier(
self,
identifier: str,
client: ClientEntityInterface,
) -> UserClaimsEntityInterface:
del client # Every client is told the same about a person here.
if identifier != "alice":
raise UserNotFoundError(identifier)
return Person(
"alice",
{"name": "Alice", "email": "alice@example.com", "email_verified": True},
)
# app/config/packages/openid_connect_server.py
from xtr_dependency_injection import configure
from xtr_security_openid_connect_server.bundle import OpenIdConnectServerConfig
from app.identity_provider import PeopleIdentityProvider
__all__ = ["openid_connect_server"]
@configure
def openid_connect_server() -> OpenIdConnectServerConfig:
return OpenIdConnectServerConfig(
identity_provider=PeopleIdentityProvider,
login_path="/login",
login_firewall="main",
)
The bundle registers the class named here, so the container builds it from its constructor. Do not register it a second time. It is built per request, like the userinfo endpoint that asks it, so its constructor may take the request's services — a repository over the session of the request's unit of work.
3. Serve the endpoints and guard them
# app/config/routes/openid_connect_server.py
from __future__ import annotations
from typing import TYPE_CHECKING
from xtr_http_kernel.routing.decorator import as_routes
if TYPE_CHECKING:
from collections.abc import Mapping
from fastapi import APIRouter, FastAPI
__all__ = ["openid_connect_server"]
@as_routes
def openid_connect_server(app: FastAPI, resources: Mapping[str, APIRouter]) -> None:
app.include_router(resources["openid_connect_server"])
app.include_router(resources["openid_connect_server_well_known"])
# app/config/packages/security.py — the two firewalls this package needs
from xtr_dependency_injection import configure
from xtr_security.bundle import FirewallConfig, SecurityConfig
from xtr_security_jwt.bundle import JwtAuthenticatorConfig
from xtr_security_oauth2_server.bundle import OAuth2AuthenticatorConfig
from xtr_security_openid_connect_server.bundle import PROMPT_LISTENER
__all__ = ["security"]
@configure
def security() -> SecurityConfig:
return SecurityConfig(
providers={"people": ...},
firewalls={
"main": FirewallConfig(
pattern=r"^/(authorize|login)",
stateless=False,
provider="people",
authenticators=(JwtAuthenticatorConfig(),),
listeners=(PROMPT_LISTENER,),
),
"userinfo": FirewallConfig(
pattern=r"^/userinfo",
provider="people",
authenticators=(OAuth2AuthenticatorConfig(),),
),
},
)
PROMPT_LISTENER is the qualifier of the step that decides prompt and max_age. Only the
application knows which firewall signs end-users in, so only it can list the step there — and that
firewall must keep a session, because the authorization request waits in it while the end-user
signs in again.
4. Sign in
$ # the client sends the browser to:
$ # /authorize?response_type=code&client_id=dashboard&redirect_uri=https://dashboard.example.com/callback
$ # &scope=openid%20profile%20email&state=xyz&nonce=n-0S6_WzA2Mj&code_challenge=…&code_challenge_method=S256
$ curl -s -u dashboard:s3cret -d grant_type=authorization_code -d code=… \
-d redirect_uri=https://dashboard.example.com/callback -d code_verifier=… \
https://authorization.example.com/token
{"token_type":"Bearer","expires_in":3600,"access_token":"ey…","refresh_token":"def…","id_token":"ey…"}
$ curl -s -H "Authorization: Bearer ey…" https://authorization.example.com/userinfo
{"sub":"alice","name":"Alice","email":"alice@example.com","email_verified":true}
Configure
<app>/config/packages/openid_connect_server.py returns an OpenIdConnectServerConfig. Every
field has a default, so the bundle builds and boots with no configuration at all.
| Field | Default | What it does |
|---|---|---|
identity_provider |
None |
The application's class implementing IdentityProviderInterface. The bundle registers it, built per request, so its constructor may take the request's services. Unset, the provider still boots; /userinfo reports the setting by name |
claim_sets |
{} |
The claims a scope of the application's own reveals, by scope — {"company": ("company_id",)}. One of the protocol's four scopes is refused |
id_token_ttl |
None |
How long an ID token lasts. None has it expire with the access token answered beside it |
login_path |
"/login" |
Where an end-user asked to sign in again is sent |
login_firewall |
"main" |
The firewall signing them in there, whose session keeps the request to return to |
authorize_path |
"/authorize" |
Where this deployment serves the authorization endpoint, which is where the prompt step acts |
The authorization server's own settings decide the rest, in
<app>/config/packages/oauth2_server.py: authorization_server.issuer is the iss every ID token
claims (never the request's Host), and authorization_server.signature_algorithm is what the ID
token is signed with — the same key, signer and kid as an access token. EdDSA names no digest
for the at_hash, so the curve of that key decides it — SHA-512 over Ed25519, SHAKE256 over Ed448
— read off the key the first time it is needed, never while the application builds.
Three settings of that server this bundle puts in place itself, and refuses to be undone:
enable_auth_code_grant=False (this package registers the flow answering that grant type),
response_type_class=IdTokenResponse, and enable_metadata_endpoint left on. An application
@configure transform runs after a bundle's prepend, so one changing any of them fails the build
with a message naming the setting.
The four claim sets OpenID Connect Core defines ship held and cannot be changed: profile,
email, address and phone. An end-user granting email agrees to share what email means,
and a set redefining it would hand a client other claims under the name they agreed to. Add the
scopes a deployment answers for to scopes.available, or /authorize refuses a client asking for
them.
Endpoints
Two route resources, registered by <app>/config/routes/openid_connect_server.py:
| Resource | Route | Path | Methods |
|---|---|---|---|
openid_connect_server |
openid_connect_server_userinfo |
/userinfo |
GET, POST |
openid_connect_server_well_known |
openid_connect_server_configuration |
/.well-known/openid-configuration |
GET |
/userinforeads no credential of its own: it answers from the token the request's firewall settled on, which is why it fails closed — with no firewall in front of it, there is no token and every request is refused. A token that is not one of this server's, or one a client was issued for itself, is401 invalid_token; one not grantedopenidis403 insufficient_scope; each carries an RFC 6750Bearerchallenge. A success is200,application/json,cache-control: no-store,{"sub": …, **claims}—subfirst and never replaced by a claim of the identity provider's. APOSTcarriesContent-Type: application/x-www-form-urlencoded(parameters allowed), even with an empty body; any other content type, or none, is400 invalid_request. The access token is read from theAuthorizationheader only./.well-known/openid-configurationanswers the authorization server's description with the provider's fields contributed to it:userinfo_endpoint(the issuer plus the path this application mounts the endpoint at, so moving it under a prefix moves the published URL),subject_types_supported: ["public"],id_token_signing_alg_values_supported,claims_supported(claim names, never scope names), andclaims_parameter_supported,request_parameter_supportedandrequest_uri_parameter_supported, allfalse. The authorization server's own/.well-known/oauth-authorization-servercarries the same fields: it is one description, answered at two paths. The resource is kept apart from the movable one because Discovery 1.0 fixes the document at that path under the issuer./authorizeand/tokenstay the authorization server's own endpoints. This package changes what happens behind them: the authorization endpoint answersGETand a posted form, a request asking foropenidmust name itsredirect_uri(a request without it still may leave it out, as OAuth 2.0 allows a client registered with one URI),prompt=select_accountis refused rather than ignored, and the token answer to a sign-in carries theid_token. A refresh never does.
A deployment that keeps the authorization server's RS256 default publishes RS256 as its ID
token signature algorithm, which is what Discovery 1.0 § 3 requires of the document and Core § 15.1
of the provider. A deployment configured for another signature_algorithm publishes only that one:
the ID token is signed with the authorization server's key, and there is one of those.
Services
OpenIdConnectServerBundle registers, under the types an application injects:
| Service | Lifetime | What it does |
|---|---|---|
ClaimExtractor |
shared | Holds every claim set — the protocol's four, then the application's — and picks the claims a token's scopes reveal out of a user's |
IdTokenSettings |
shared | What an ID token is signed with and how long it lasts, read off the authorization server's settings — and, for EdDSA, the curve of its key |
IdentityProviderInterface |
shared | The class identity_provider names. Unset, a stand-in raises InvalidConfigurationError naming the setting the first time a user is needed |
OpenIdAuthCodeGrant |
shared, tagged GRANT_TAG |
The code flow carrying the sign-in: it seals the nonce and the sign-in time into the code, and hands them to the token answer when it is redeemed |
UserInfoController |
per request | Answers /userinfo, over the request's own token storage |
OpenIdMetadataContributor |
shared, tagged METADATA_TAG |
The provider's fields of the description |
OpenIdPromptListener |
per request, qualifier openid_connect_server#prompt_listener |
The firewall chain step deciding prompt and max_age, also aliased under FirewallListenerInterface |
IdTokenResponse is not registered here: the authorization server registers whichever class its
response_type_class names, which this bundle made this one. Inject the prompt step by the
qualifier PROMPT_LISTENER carries, never by building it: it takes the request's token storage.
The library stands on its own — ClaimExtractor, ClaimSetEntity, token_hash, parse_prompt,
consent_required, IdTokenResponse and OpenIdAuthCodeGrant are plain objects, built from their
constructors — and the bundle is the integration on top.
Events
This package hears and raises nothing of its own: it uses the authorization server's events.
| Name | Listener | Priority |
|---|---|---|
OAuth2Events.AUTHORIZATION_REQUEST_RESOLVE |
stamp_auth_time records on the request when the end-user last signed in, from the newest proof on the firewall's token, and decides nothing |
AUTH_TIME_LISTENER_PRIORITY, 2048 |
A consent listener of the application's runs below that priority — the default 0 does —
because resolving a request stops the listeners after it, and the sign-in time has to be recorded
first. Read what the client asked for through OpenIdAuthorizationRequest.get_prompt():
from xtr_event_dispatcher import as_event_listener
from xtr_security_oauth2_server.event.authorization_request_resolve_event import (
AuthorizationRequestResolveEvent,
)
from xtr_security_oauth2_server.oauth2_events import OAuth2Events
from xtr_security_openid_connect_server.prompt import consent_required
from xtr_security_openid_connect_server.request_types.open_id_authorization_request import (
OpenIdAuthorizationRequest,
)
@as_event_listener(OAuth2Events.AUTHORIZATION_REQUEST_RESOLVE)
async def ask_for_consent(event: AuthorizationRequestResolveEvent) -> None:
request = event.get_authorization_request()
asked = request.get_prompt() if isinstance(request, OpenIdAuthorizationRequest) else frozenset()
if "none" in asked and not consent_already_given(event):
# No page may be shown, so the client is told instead.
raise consent_required(event)
if "consent" in asked or not consent_already_given(event):
_ = event.set_response(await consent_page(event))
return
_ = event.resolve_authorization(AuthorizationRequestResolveEvent.APPROVED)
consent_required(event) builds the refusal, delivered to the validated redirect URI with the
state echoed back. A remembered sign-in that proved no credential leaves the sign-in time
unknown: the ID token then states none, and a max_age request treats it as stale.
Use in an application
Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.
- Install —
uv add xtr-security-openid-connect-server, beside an application already hosting xtr-security-oauth2-server. - Recipe —
uv run xtr-recipes recipes:syncdoes the Activate and Configure steps below, and no other: it listsOpenIdConnectServerBundle, writes a startingconfig/packages/openid_connect_server.pywith the login page, login firewall and authorization path, and writesconfig/routes/openid_connect_server.pyserving the userinfo endpoint at its default path and the configuration document at the root. It prints what a recipe cannot make for you: the identity provider class, listing the prompt step in the login firewall'slisteners, the firewall in front of/userinfo, the scopes, the issuer, and the consent listener. - Activate —
OpenIdConnectServerBundle: {"all": True}inBUNDLESin<app>/config/bundles.py, imported fromxtr_security_openid_connect_server.bundle. The authorization server's ownsetup(app, kernel)andconcurrent_scoped_access=Truealready apply; this package adds no step there. - Brings along — the OAuth 2.0 authorization server and, through it and on its own account, the security bundle, the clock, the event dispatcher and the HTTP kernel, because this bundle requires every one of them.
- Configure — with no configuration the bundle builds and boots, and answers no claims: a
config/packages/openid_connect_server.py@configurefunction returning anOpenIdConnectServerConfignames theidentity_provider, and the login page and firewall a re-login goes through — see Configure. In<app>/config/packages/security.py, listopenid_connect_server#prompt_listenerin thelistenersof that firewall and leave it stateful, and put a firewall carryingOAuth2AuthenticatorConfig()in front of/userinfo. In<app>/config/packages/oauth2_server.py, name the issuer and add the claim scopes this deployment answers for toscopes.available. A listener onOAuth2Events.AUTHORIZATION_REQUEST_RESOLVE, belowAUTH_TIME_LISTENER_PRIORITY, answers the consent question — see Events.config/routes/openid_connect_server.pyregisters both route resources; move the userinfo endpoint there, and leave the document at the root — see Endpoints. - Environment — nothing of its own. The ID token is signed with the authorization server's key,
so that server's
OAUTH2_SERVER_PRIVATE_KEY_PATHand its two other variables are all there are. - Ignore — nothing: this package writes no file into the project.
- Remove —
uv run xtr-recipes recipes:remove xtr-security-openid-connect-server, then undo the steps it printed: the identity provider, the prompt step in the firewall'slisteners, the userinfo firewall and the consent listener are the application's own. The authorization server goes back to its shipped code flow and bearer answer by itself, both having been this bundle's to prepend. - Check —
debug:bundleslistsopenid_connect_serveras active, withoauth2_serveramong the bundles it requires;debug:config openid_connect_servershows the resolved identity provider, claim sets, ID-token lifetime, login page and firewall; andGET /.well-known/openid-configurationanswers with this provider's description, naming the issuer and the userinfo endpoint.
Kernel / bundle
# app/config/bundles.py
from xtr_security_openid_connect_server.bundle import OpenIdConnectServerBundle
BUNDLES = {OpenIdConnectServerBundle: {"all": True}}
OpenIdConnectServerBundle (name openid_connect_server, config OpenIdConnectServerConfig)
requires the OAuth 2.0 authorization server,
security, clock, event dispatcher and
HTTP kernel bundles, so listing it alone brings every one of them along. No
other bundle requires it, so it only arrives by being listed. It:
- prepends onto the authorization server's configuration the flow and the answer a sign-in takes —
enable_auth_code_grant=False,response_type_class=IdTokenResponse— and appendsopenidtoscopes.availablewhen that tuple names anything, leaving an empty one empty so the authorization server's own error about it still fires; - registers the claim sets, the ID-token settings, the identity provider, the flow tagged
GRANT_TAG, the userinfo controller and its route resources, the metadata contributor taggedMETADATA_TAG, and the prompt step underopenid_connect_server#prompt_listener; - loads the listener recording the sign-in time on the authorization server's consent event;
- fails the build when the resolved authorization server runs the shipped redirect flow, answers with something that cannot carry an ID token, or does not describe itself — each named, because an application transform runs after this bundle's prepend and can undo it.
The authorization server knows nothing of this bundle: everything above goes through seams it publishes for an add-on. It reads no key, user or issuer while building, so it builds and boots with no configuration.
Errors
Everything this package raises derives from OpenIdConnectServerError, itself an OAuth2Error
(xtr_security_oauth2_server_core.exception), so one except OAuth2Error still catches the
authorization server and its identity layer together:
| Error | Base | Raised when |
|---|---|---|
OpenIdConnectServerError |
OAuth2Error |
The base of them all; nothing raises it directly |
InvalidConfigurationError |
OpenIdConnectServerError, ValueError |
A setting the provider cannot run with, or one missing where a service needs it — identity_provider unset, a login firewall that keeps no session — naming it and <app>/config/packages/openid_connect_server.py |
InvalidArgumentError |
OpenIdConnectServerError, ValueError |
One of this package's objects used wrongly: a claim set naming no scope, a negative max_age, a claim set for a scope the protocol defines, an unsigned ID token back from the signature provider |
UnsupportedAlgorithmError |
OpenIdConnectServerError |
A signature algorithm whose digest its name does not say, or an EdDSA key on neither Ed25519 nor Ed448, so no at_hash can be taken for it |
A refusal a client is owed is never one of these: it is the authorization server's OAuthServerError,
which the endpoints deliver. parse_prompt raises it as invalid_request, login_required and
consent_required build it for the two refusals a sign-in can end in, and the flow raises
server_error when the token answer cannot carry an ID token.
Layout
xtr_security_openid_connect_server/
├── _endpoint_paths.py where each endpoint lives by default, and its route name
├── routing/ the endpoints, and the two route resources routes files register
├── controller/ UserInfoController
├── grant/ OpenIdAuthCodeGrant
├── request_types/ OpenIdAuthorizationRequest: nonce, prompt, max_age, auth_time
├── response_types/ IdTokenResponse
├── firewall/ OpenIdPromptListener
├── event_listener/ the listener recording the sign-in time, and its priority
├── repositories/ IdentityProviderInterface
├── entities/ the claim set, and what a user with claims answers to
├── claim_extractor.py the claim sets, and picking a user's claims through them
├── id_token_settings.py what an ID token is signed with, and how long it lasts
├── token_hash.py at_hash
├── prompt.py parse_prompt, login_required, consent_required
├── open_id_metadata_contributor.py the provider's fields of the description
├── exception/ OpenIdConnectServerError and the three under it
├── recipe/ what recipes:sync applies
└── bundle/ OpenIdConnectServerBundle, its configuration and PROMPT_LISTENER
Development
Developed in the python-xtr monorepo, under
packages/xtr-security-openid-connect-server; run the commands below from there. The conformance
suite, one module per part of the protocol, is under
tests/conformance/.
uv sync --all-packages --all-extras
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest --cov
License
MIT — see LICENSE.
Metadata
Release files for xtr-security-openid-connect-server 6.8.1
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 |
|---|---|---|---|---|
| xtr_security_openid_connect_server-6.8.1.tar.gz | 65.3 kB | With provenance | Details for xtr_security_openid_connect_server-6.8.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_security_openid_connect_server-6.8.1-py3-none-any.whl | Python 3 | none | any | Details for xtr_security_openid_connect_server-6.8.1-py3-none-any.whl |
Total release size: 148.0 kB
Release files / xtr_security_openid_connect_server-6.8.1.tar.gz
| Download URL | xtr_security_openid_connect_server-6.8.1.tar.gz |
|---|---|
| Size | 65.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49b10a5562f27a3d628eff81aa3e1f5219267bd88406882cea754b54cd7f66d9
|
|
BLAKE2b-256 checksum How to use checksums |
7172ab0fc6f3c4a2b32c4f50803b51815a3bc62a319366161cf06aeb1c563eca
|
| 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 13, 2026.
Transparency logRelease files / xtr_security_openid_connect_server-6.8.1-py3-none-any.whl
| Download URL | xtr_security_openid_connect_server-6.8.1-py3-none-any.whl |
|---|---|
| Size | 82.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90fae8adbb8886cd58e62df46b9f96293c334cf5503b6f37ed9ac050d6607d26
|
|
BLAKE2b-256 checksum How to use checksums |
9c71c4ecca6d74972ec9ec8460436a6c767d9a40d0b6633fb776ae24e7679ccf
|
| 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 13, 2026.
Transparency logSecurity for xtr-security-openid-connect-server 6.8.1
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 xtr_security_openid_connect_server-6.8.1.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 13, 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.