Skip to content

xtr_security_jwt.bundle

The xtr-dependency-injection bundle for xtr-security-jwt.

EncoderConfig dataclass

EncoderConfig(service: type | None = None, signature_algorithm: str = 'RS256')

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 None to sign with the joserfc encoder over the configured keys.

  • signature_algorithm (str) –

    The signature algorithm the default encoder uses.

JwtAuthenticatorConfig dataclass

JwtAuthenticatorConfig()

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

Bases: Bundle[JwtConfig]

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

prepend_extension(builder: ContainerBuilder) -> None

Add the jwt authenticator and user-provider factories to security.

build

build(builder: ContainerBuilder) -> None

Tag every registered payload enrichment so the manager collects them all.

load_extension

load_extension(config: JwtConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

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

process(builder: ContainerBuilder) -> None

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; None until a deployment configures one.

  • issuer (str) –

    The iss every 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 aud and a presented token must name at least one.

  • public_key (str | None) –

    The public key that verifies, or None to 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

JwtUserProviderConfig(user_class: type = _default_user_class())

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

AuthorizationHeaderExtractorConfig(enabled: bool = True, prefix: str = 'Bearer', name: str = 'Authorization')

Read a token from a request header after a scheme prefix.

Attributes:

  • enabled (bool) –

    Whether the firewall reads a token from the header.

  • prefix (str) –

    The scheme word before the token, or empty for the whole value.

  • name (str) –

    The header the token travels in.

CookieExtractorConfig dataclass

CookieExtractorConfig(enabled: bool = False, name: str = 'BEARER')

Read a token from a named cookie.

Attributes:

  • enabled (bool) –

    Whether the firewall reads a token from the cookie.

  • name (str) –

    The cookie the token travels in.

QueryParameterExtractorConfig dataclass

QueryParameterExtractorConfig(enabled: bool = False, name: str = 'bearer')

Read a token from a named query parameter.

Attributes:

  • enabled (bool) –

    Whether the firewall reads a token from the query string.

  • name (str) –

    The query parameter the token travels in.

SplitCookieExtractorConfig dataclass

SplitCookieExtractorConfig(enabled: bool = False, cookies: Sequence[str] = ())

Read a token spread across several named cookies and rejoin it.

Attributes:

  • enabled (bool) –

    Whether the firewall reads a token split across cookies.

  • cookies (Sequence[str]) –

    The cookies the token is rebuilt from, in order.

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: