jots

The audiences (aud) accepted when verifying tokens.

- AcceptedAudiences.none rejects tokens with an audience, while tokens without an audience are accepted. This is the default. - AcceptedAudiences.any accepts tokens with any audience, and tokens without an audience. - AcceptedAudiences(audience, audiences*) accepts tokens with at least one of the audiences, while other tokens are rejected.

Rejecting tokens with an audience by default follows the JWT specification, which requires tokens to be rejected when the audience is not recognized (RFC 7519 section 4.1.3).

The issuers (iss) accepted when verifying tokens.

- AcceptedIssuers.any accepts tokens with any issuer, and tokens without an issuer. This is the default. - AcceptedIssuers(issuer, issuers*) accepts tokens with one of the issuers, while other tokens are rejected.

The subjects (sub) accepted when verifying tokens.

- AcceptedSubjects.any accepts tokens with any subject, and tokens without a subject. This is the default. - AcceptedSubjects(subject, subjects*) accepts tokens with one of the subjects, while other tokens are rejected.

The types (typ) accepted when verifying tokens.

- AcceptedTypes.any accepts tokens with any type, and tokens without a type. This is the default. - AcceptedTypes(type, types*) accepts tokens with one of the types, while other tokens are rejected.

Types are media types compared case-insensitively, where types without a / have an implied application/ prefix. This means JWT accepts the types JWT, jwt, and application/jwt.

The key identifier used to identify a specific key in a JwkSet.

Usually set as the kid parameter in a Jwk or JwtHeader.

The key type used to identify the type of key for a Jwk.

Required to be set as the kty parameter for a Jwk.

Decodes VerifiedJwts to instances of type A.

A common approach is to decode VerifiedJwt claims to type A. This can be done by defining a Decoder instance and using JwtDecoder.decodeClaims.

Encodes instances of type A to JwtBuilders.

A common approach is to encode instances of type A as the claims of a JwtBuilder. This can be done by defining an Encoder.AsObject instance and then using JwtEncoder.encodeClaims.

The bytes constituting the signature part of a SignedJwt.

JwtSignatures are usually created with JwtSignature.fromMac from jots.crypto.Macs, or using JwtSignature.fromSignature from jots.crypto.Signatures when creating tokens. When parsing existing signatures, JwtSignature.fromString is available.

The JwtSignature should generally not be trusted unless it is part of a VerifiedJwt, so the signature is verified.

Note it is possible for signatures to be empty. However, no default JwtSigning will emit empty signatures. Similarly, all default JwtVerifications will reject empty signatures.

Capability to sign JwtBuilders and return SignedJwts.

Signing JwtBuilders requires specifying the algorithm to use and a jots.crypto.PrivateKey or jots.crypto.SecretKey. The key requirements of the algorithm are checked by default, but this can be customized using JwtSigningBuilder.

The default JwtSigning instances will set the algorithm in the header of the JwtBuilder before signing, to ensure it matches with the actual signing algorithm.

It is possible to implement custom JwtSigning instances, for example for testing purposes. The bytes which should be signed are provided by JwtBuilder#signingBytes.

JwtSigning builder which allows customizing signing checks.

The default instance checks that the private or secret key meets the key requirements of the algorithm being used, as detailed by checkKeyRequirements.

Capability to verify SignedJwts and return VerifiedJwts.

Verifying SignedJwts requires specifying one or more algorithms, and either a jots.crypto.PublicKey or jots.crypto.SecretKey. Use JwtVerificationBuilder to create instances and customize the claims verification.

It is possible to create custom JwtVerification instances, but these will generally have to make use of a default implementation. This stems from the fact that VerifiedJwts can only be created by the default implementations. The notable exception is that the testing module allows verifying any SignedJwt.

JwtVerification builder that allows customizing verification.

The default instances perform the following verifications.

- Public and secret keys must meet the key requirement of the algorithm used, as detailed by JwtVerificationBuilder#checkKeyRequirements. - If the token has an audience (aud), then the token is rejected, since the default accepted audiences are AcceptedAudiences.none. Use the withAcceptedAudiences function to specify the accepted audiences. - The expiration (exp), when present, is verified to be in the future. - The not-before (nbf), when present, is verified to not be in the future. - If the token contains a crit header, then the token is rejected. The withCriticalHeaders function can be used to specify the set of accepted critical headers.

The expiration (exp) and not-before (nbf) claims are only verified when present. Their presence can additionally be required, in which case a token missing the claim is rejected.

The verifications above are in addition to verifying the signature and, while not recommended, can be explicitly disabled. It is also recommended to enable additional verifications when appropriate.

For even more verifications, resort to custom JwtVerifications.

A signed JSON Web Token (JWT) which has not been verified.

The String representation is either parsed or generated by using e.g. JwtBuilder#signWith. Unlike JwtBuilder, the SignedJwt does not allow for modifications.

The SignedJwt should generally not be trusted unless it is part of a VerifiedJwt. A SignedJwt can be verified by using the SignedJwt#verifyWith method.

A JwtClaims together with its String representation.

The String representation is either parsed or generated by using e.g. JwtClaims#toSigned. Unlike JwtClaims, the SignedJwtClaims does not allow for modifications.

The SignedJwtClaims should generally not be trusted unless it is part of a VerifiedJwt, so the signature is verified.

A JwtHeader together with its String representation.

The String representation is either parsed or generated by using e.g. JwtHeader#toSigned. Unlike JwtHeader, the SignedJwtHeader does not allow for modifications.

The SignedJwtHeader should generally not be trusted unless it is part of a VerifiedJwt, so the signature is verified.

A SignedJwt for which the signature has been verified as valid.

Token verification typically also includes verifying that claims are valid, although this is optional and depends on the use case.

VerifiedJwts can only be created by the default implementations of JwtVerification. The notable exception is the testing module which allows to create a VerifiedJwt from any SignedJwt.