Skip to content

Signing a token

JwtService::sign mints an RFC 9068 access token for this app and sign_for one for another — what each stamps, and what each refuses to mint.

A login or OAuth callback injects Arc<JwtService> and calls sign:

crates/features/src/authn/service.rs
let claims = Claims {
sub: Subject::User(user.id),
client_id: self.config.client_id.clone(),
org_id: user.org_id,
roles: user.roles.clone(),
};
let token = self.jwt.sign(&claims)?;

sign is Result<String, SignError>. A token this server cannot mint — a verify-only service, EdDSA with no private key or a JWK Set, is the one you will meet — is the server’s failure, never the caller’s: ? in a route answers the opaque 500 and files the chain at error, where a 401 would send a client off for another credential, and a handler returning it on another edge answers as opaquely. A handler has nothing to add. A service holds it as a #[from] variant of its own error, and a token endpoint’s TokenError already does. It does not convert into AuthError, whose every answer speaks of the credential: a login handler ?-ing both answers nest_rs::http::Result, into which each converts on its own status. ttl_secs() is the token’s lifetime, JwtOptions::expires_in (default one hour), so the issuer can return it alongside the token.

RFC 9068 §2.2 lists the claims every JWT access token carries, and sign writes the ones only the signer knows: iat, the time it signs; exp, its lifetime after that; jti, an identifier no other token shares; and the aud and iss you configured. Your claims name the rest — sub, and the client_id of the OAuth client the token is issued to — and a claim they already carry is kept as written: an exp of their own outlives or undercuts the signer’s.

sub is held by the type. sign and sign_for take a PrincipalIdentity, the derive your claims already carry for the guard, and a type without it does not compile. A claims type holding its subject under another name, or a sub that is blank, is stamped its #[principal(actor)] as sub; one naming no subject at all, its actor None or blank, mints nothing and answers the SignError above. So does a sub that is no string, since RFC 7519 §4.1.2 makes it one and a verifier reading one refuses anything else: an integer id is written as its decimal string, which #[principal(actor)] on a field of another name does for you. A test forging such a token, to prove your verifier refuses it, hands it to TestApp::bearer, which signs what it is given.

Every claim the specifications register is held the same way, the SignError naming it: iss, jti, client_id and acr are strings; exp, nbf, iat and auth_time are NumericDates, a JSON number of seconds since the epoch; aud is a string or an array of them, amr an array of strings, and scope the list RFC 6749 §3.3 writes, scope tokens each separated by one space, or empty when the token grants none. A registered claim your claims serialize as null is left out of the token.

client_id, which RFC 9068 §2.2 requires too, is your claims’ to name, and sign and sign_for refuse claims naming none — absent, null or blank — with the SignError naming the claim: nothing a claims type already says names its client, so the signer reads it off the token it is about to mint. Hold it as a String, as the demo’s claims and nestrs g auth’s do, and no literal leaves it out. A machine token names the client that authenticated at /token; a user’s, from /login or the social callback, names the first-party client the sign-in serves, <PREFIX>_SIGN_IN__CLIENT_ID (publish-web by default), which the boot refuses any registered client to hold. An authorization-code grant by that client (RFC 6749 §4.1, with PKCE) would have it identify itself, where the deployment names it here. The development token nestrs g auth serves names its own route, dev-token.

sign_handshake, for a flow’s short-lived token, stamps the same but exp: its claims name their lifetime with expiry_in(secs), and claims naming none are refused rather than given the access token’s.

sign mints a token for this app itself: its aud is this app’s own audience, the one its verifier requires. An issuer minting a token another app will verify names that app instead, with sign_for:

crates/features/src/sign_in/service.rs
let token = self.jwt.sign_for("https://api.example.com", &claims)?;

The resource becomes the token’s aud and nothing else does, so only the app serving it accepts the token — the one a client asked for in the RFC 8707 resource parameter of its token request (OAuth2). A token for one resource replayed at another is refused there. sign_for refuses a blank resource, and claims carrying an aud of their own.

  • JWT — the strategy verifying what this signs.
  • Token endpoint — the grant that names the resource sign_for mints for.
  • Split deployment — one issuer holding the private key, every API the public one.