xtr_security_jwt.bundle ¶
The xtr-dependency-injection bundle for xtr-security-jwt.
EncoderConfig
dataclass
¶
The encoder a token is signed with, and the algorithm it signs with.
Attributes:
-
service(type | None) –A registered encoder to sign with instead of the default, or
Noneto sign with the joserfc encoder over the configured keys. -
signature_algorithm(str) –The signature algorithm the default encoder uses.
JwtAuthenticatorConfig
dataclass
¶
A firewall's jwt authenticator.
A firewall accepts self-issued tokens by listing one of these under its authenticators; there is nothing to set — the keys, the algorithm and the extractors all come from the bundle's own configuration, and the user is loaded through the firewall's own provider.
JwtBundle ¶
Registers the self-issued-token services and opens the firewall key jwt.
Requires the security, clock and event-dispatcher bundles: listing this one
brings the security family along, and the manager reads its times from the
clock and announces its events on the dispatcher. It prepends its jwt
authenticator and user-provider factories onto the security configuration.
prepend_extension ¶
Add the jwt authenticator and user-provider factories to security.
build ¶
Tag every registered payload enrichment so the manager collects them all.
load_extension ¶
Register the signing chain, the manager and the commands.
Nothing here reads a key: the JWS provider reads and measures it — an HMAC secret against its algorithm's floor included — the first time a token is signed or verified.
process ¶
Alias every tagged enrichment under a qualifier the manager gathers them by.
JwtConfig
dataclass
¶
JwtConfig(secret_key: str | None = None, issuer: str = '%kernel.name%', audience: Sequence[str] = (), public_key: str | None = None, additional_public_keys: tuple[str, ...] = (), pass_phrase: str = '', token_ttl: int = 3600, allow_no_expiration: bool = False, clock_skew: int = 0, encoder: EncoderConfig = EncoderConfig(), user_id_claim: str = 'username', token_extractors: TokenExtractorsConfig = TokenExtractorsConfig())
Everything the JWT bundle signs and verifies with, mirroring the reference options.
Buildable with no arguments, and the bundle builds and boots on it: a token
cannot be signed until secret_key — the private key or shared secret
that signs, as the key text or the path of a file holding it — names a key,
and the first attempt raises
:class:~xtr_security_jwt.exception.MissingKeyError saying so. issuer,
the name every minted token is stamped with and every presented token is
checked against, is the kernel's name unless set. The public key is derived
from the signing key when absent; additional_public_keys name files of
other keys tokens may also be verified against.
Attributes:
-
secret_key(str | None) –The private key or shared secret that signs, as text or a file path;
Noneuntil a deployment configures one. -
issuer(str) –The
issevery token is stamped with and checked against: the kernel's name (%kernel.name%) by default. -
audience(Sequence[str]) –The audiences a token is minted for; when set, every token carries them as
audand a presented token must name at least one. -
public_key(str | None) –The public key that verifies, or
Noneto derive it. -
additional_public_keys(tuple[str, ...]) –Files of extra public keys to also verify against.
-
pass_phrase(str) –The pass phrase the private key is encrypted with.
-
token_ttl(int) –How long a minted token lives, in seconds.
-
allow_no_expiration(bool) –Whether a token without an expiry is honoured.
-
clock_skew(int) –Seconds of clock skew tolerated on a verified token's times.
-
encoder(EncoderConfig) –How a token is signed — the algorithm, and any encoder override.
-
user_id_claim(str) –The claim the user's identifier is written into and read back from.
-
token_extractors(TokenExtractorsConfig) –Where a firewall reads a token from.
JwtUserProviderConfig
dataclass
¶
A stateless user provider that rebuilds a user from a token's claims.
A deployment that keeps no user store names one of these, and the bundle
registers a provider building user_class from each token's payload.
Attributes:
-
user_class(type) –The class the provider builds from a token's claims; it must be buildable from a payload, and defaults to the plain JWT user.
AuthorizationHeaderExtractorConfig
dataclass
¶
CookieExtractorConfig
dataclass
¶
QueryParameterExtractorConfig
dataclass
¶
SplitCookieExtractorConfig
dataclass
¶
TokenExtractorsConfig
dataclass
¶
TokenExtractorsConfig(authorization_header: AuthorizationHeaderExtractorConfig = AuthorizationHeaderExtractorConfig(), cookie: CookieExtractorConfig = CookieExtractorConfig(), query_parameter: QueryParameterExtractorConfig = QueryParameterExtractorConfig(), split_cookie: SplitCookieExtractorConfig = SplitCookieExtractorConfig())
The four places a firewall may read a token from, grouped.
Attributes:
-
authorization_header(AuthorizationHeaderExtractorConfig) –The header extractor, enabled by default.
-
cookie(CookieExtractorConfig) –The cookie extractor, off by default.
-
query_parameter(QueryParameterExtractorConfig) –The query-parameter extractor, off by default.
-
split_cookie(SplitCookieExtractorConfig) –The split-cookie extractor, off by default.