JSON Web Tokens (Effect's effect/jose/Jwt): claims described by a
schema, signed as a JWS or encrypted as a JWE::
token = yield from jwt.sign(Claims, {"sub": "user_1", "role": "admin"}, key)
verified = yield from jwt.verify(Claims, token, key, issuer="https://issuer.example")Verifying checks the registered claims (iss, sub, aud,
exp, nbf, iat, jti) before the application schema decodes
the claims: each must have its registered type, and the options say which
are required and what they must be. exp and nbf are always checked
against the Clock, within clock_tolerance; max_token_age
bounds the age iat gives.
Re-exports#
Values#
| Attribute | Type | Description |
|---|---|---|
RegisteredClaimsSchema | StructSchema[RegisteredClaims, Never, Never] |
Types#
| Type | Definition | Description |
|---|---|---|
RegisteredClaim | type RegisteredClaim = Literal['iss', 'sub', 'aud', 'exp', 'nbf', 'iat', 'jti'] | |
JwtError | type JwtError = JoseError | SchemaError |
Classes#
Functions#
sign#
sign[A, R](schema: Exact[A, Any, R], claims: A, key: HmacKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Mac]
sign[A, R](schema: Exact[A, Any, R], claims: A, key: PrivateKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Signature]
sign[A, R](schema: Exact[A, Any, R], claims: A, key: SigningKey, header: Header | None = None) -> Effect[Redacted[str], JwtError, R | Mac | Signature]The claims, encoded by schema, as a signed JWT. claims has the
schema's Type, and their encoding must be a JSON object whose registered
claims have their types.
| Parameter | Type | Description |
|---|---|---|
schema | ||
claims | ||
key | ||
header | = None |
@overload
def sign[A, R](
schema: Exact[A, Any, R], claims: A, key: HmacKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Mac]: ...
@overload
def sign[A, R](
schema: Exact[A, Any, R], claims: A, key: PrivateKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Signature]: ...
@overload
def sign[A, R](
schema: Exact[A, Any, R], claims: A, key: SigningKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Mac | Signature]: ...
def sign(
schema: Exact[Any, Any, Any], claims: Any, key: SigningKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, Any]:
"""The claims, encoded by ``schema``, as a signed JWT. ``claims`` has the
schema's Type, and their encoding must be a JSON object whose registered
claims have their types."""
return _encode_claims(schema, claims).flat_map(lambda payload: jws.sign(payload, key, header))verify#
verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: HmacKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Mac]
verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: PublicKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Signature]
verify[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: VerificationKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Verified[A], JwtError, R | Mac | Signature]The claims of a JWT signed with key, checked against options
and decoded by schema.
| Parameter | Type | Description |
|---|---|---|
schema | ||
token | ||
key | ||
options | = {} |
@overload
def verify[A, R](
schema: S.Codec[A, Any, R, Any], token: Token, key: HmacKey, **options: Unpack[VerifyOptions]
) -> Effect[Verified[A], JwtError, R | Mac]: ...
@overload
def verify[A, R](
schema: S.Codec[A, Any, R, Any], token: Token, key: PublicKey, **options: Unpack[VerifyOptions]
) -> Effect[Verified[A], JwtError, R | Signature]: ...
@overload
def verify[A, R](
schema: S.Codec[A, Any, R, Any],
token: Token,
key: VerificationKey,
**options: Unpack[VerifyOptions],
) -> Effect[Verified[A], JwtError, R | Mac | Signature]: ...
def verify(
schema: S.Codec[Any, Any, Any, Any],
token: Token,
key: VerificationKey,
**options: Unpack[VerifyOptions],
) -> Effect[Verified[Any], JwtError, Any]:
"""The claims of a JWT signed with ``key``, checked against ``options``
and decoded by ``schema``."""
@gen
def body():
policy = yield from _read_policy(options)
verified = yield from jws.verify(token, key)
claims, registered = yield from _decode_claims(
schema,
verified.payload,
cast("Mapping[str, object]", verified.protected_header),
policy,
)
return Verified(claims, registered, verified.protected_header)
return bodyverify_with_key_set#
verify_with_key_set[A, R](schema, token, *, algorithms, **options) -> Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]verify with the Jwks key the header selects, for an alg in
algorithms.
| Parameter | Type | Description |
|---|---|---|
schema | S.Codec[A, Any, R, Any] | |
token | Token | |
algorithms | Sequence[AsymmetricAlgorithm] | |
options | Unpack[VerifyOptions] = {} |
Returns Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]
def verify_with_key_set[A, R](
schema: S.Codec[A, Any, R, Any],
token: Token,
*,
algorithms: Sequence[AsymmetricAlgorithm],
**options: Unpack[VerifyOptions],
) -> Effect[VerifiedWithKey[A], JwtError, R | Jwks | Signature]:
"""``verify`` with the ``Jwks`` key the header selects, for an ``alg`` in
``algorithms``."""
@gen
def body():
policy = yield from _read_policy(options)
verified = yield from jws.verify_with_key_set(token, algorithms=algorithms)
claims, registered = yield from _decode_claims(
schema,
verified.payload,
cast("Mapping[str, object]", verified.protected_header),
policy,
)
return VerifiedWithKey(claims, registered, verified.protected_header, verified.key)
return bodyencrypt#
encrypt[A, R](schema, claims, key, header=None) -> Effect[Redacted[str], JwtError, R | Aead | SecureRandom]The claims, encoded by schema, as an encrypted JWT. claims has
the schema's Type.
| Parameter | Type | Description |
|---|---|---|
schema | Exact[A, Any, R] | |
claims | A | |
key | DirKey | |
header | Header | None = None |
Returns Effect[Redacted[str], JwtError, R | Aead | SecureRandom]
def encrypt[A, R](
schema: Exact[A, Any, R], claims: A, key: DirKey, header: Header | None = None
) -> Effect[Redacted[str], JwtError, R | Aead | SecureRandom]:
"""The claims, encoded by ``schema``, as an encrypted JWT. ``claims`` has
the schema's Type."""
return _encode_claims(schema, claims).flat_map(
lambda payload: jwe.encrypt(payload, key, header)
)decrypt#
decrypt[A, R](schema: S.Codec[A, Any, R, Any], token: Token, key: DirKey, **options: Unpack[VerifyOptions] = {}) -> Effect[Decrypted[A], JwtError, R | Aead]
decrypt[A, R, E = Never, R2 = Never](schema: S.Codec[A, Any, R, Any], token: Token, key: Callable[[jwe.ProtectedHeader], Effect[DirKey, E, R2]], **options: Unpack[VerifyOptions] = {}) -> Effect[Decrypted[A], JwtError | E, R | Aead | R2]The claims of an encrypted JWT, checked against options and
decoded by schema.
| Parameter | Type | Description |
|---|---|---|
schema | ||
token | ||
key | ||
options | = {} |
@overload
def decrypt[A, R](
schema: S.Codec[A, Any, R, Any], token: Token, key: DirKey, **options: Unpack[VerifyOptions]
) -> Effect[Decrypted[A], JwtError, R | Aead]: ...
@overload
def decrypt[A, R, E = Never, R2 = Never](
schema: S.Codec[A, Any, R, Any],
token: Token,
key: Callable[[jwe.ProtectedHeader], Effect[DirKey, E, R2]],
**options: Unpack[VerifyOptions],
) -> Effect[Decrypted[A], JwtError | E, R | Aead | R2]: ...
def decrypt(
schema: S.Codec[Any, Any, Any, Any],
token: Token,
key: DirKey | Callable[[jwe.ProtectedHeader], Effect[DirKey, Any, Any]],
**options: Unpack[VerifyOptions],
) -> Effect[Decrypted[Any], Any, Any]:
"""The claims of an encrypted JWT, checked against ``options`` and
decoded by ``schema``."""
@gen
def body():
policy = yield from _read_policy(options)
decrypted = yield from jwe.decrypt(token, key)
claims, registered = yield from _decode_claims(
schema,
decrypted.plaintext,
cast("Mapping[str, object]", decrypted.protected_header),
policy,
)
return Decrypted(claims, registered, decrypted.protected_header, decrypted.key)
return bodydecode_unverified#
decode_unverified(token) -> Effect[Unverified, JoseError]A signed JWT's header and claims, without verifying anything.
| Parameter | Type | Description |
|---|---|---|
token | Token |
Returns Effect[Unverified, JoseError]
def decode_unverified(token: Token) -> Effect[Unverified, JoseError]:
"""A signed JWT's header and claims, without verifying anything."""
@gen
def body():
parsed = yield from jws.parse(token)
claims = parse_json_object(parsed.payload)
if claims is None:
return (yield from invalid_token("The JWT payload is not a JSON object"))
return Unverified(parsed.protected_header, claims)
return body