jwt/configuration

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

OAuth Provider Mode configuration

When making the system OAuth compliant (using OIDC or MCP plugins), disable the /token endpoint by adding '/token' to disabledPaths, and disable setting JWT header by setting disableSettingJwtHeader: true in the jwt() plugin configuration.

Remote JWKS URL configuration

Use the remoteUrl option in jwt plugin configuration to disable the /jwks endpoint and use an external JWKS endpoint instead. This is useful if JWKS are not at /jwks or if signed with a certificate on a CDN. Must specify the asymmetric algorithm used for signing via keyPairConfig.alg.

Custom JWKS path on server

Use the jwksPath option inside jwt() configuration to customize the JWKS endpoint path. Default path is /jwks. Example: jwt({ jwks: { jwksPath: '/.well-known/jwks.json' } })

Custom JWKS path on client

When using a custom jwksPath on the server, configure the client with the same path: jwtClient({ jwks: { jwksPath: '/.well-known/jwks.json' } }). The client configuration MUST match the server configuration or the client will not fetch JWKS.

Custom JWT signing with localized approach

Provide a sign function in jwt.sign option to implement custom JWT signing. The function receives jwtPayload and should return the signed JWT. When using localized approach, the server uses the latest private key when rotated and depending on deployment, the server may need to be restarted. remoteUrl must be defined.

Custom JWT signing with remote Key Management Service

Use a remote Key Management Service such as Google KMS, Amazon KMS, or Azure Key Vault for JWT signing. Provide a sign function in jwt.sign option that calls the remote service to sign the JWT. Include integrity validation like CRC32 or SHA256 checks to verify the payload is unchanged after transit. remoteUrl must be defined and set to store all active keys.

Key pair algorithm configuration

The algorithm used for key pair generation is configured via keyPairConfig. Default is EdDSA with Ed25519 curve. Available algorithms: EdDSA (with Ed25519 or Ed448 curve), ES256, RSA256, PS256, ECDH-ES (with P-256, P-384, or P-521 curve), ES512.

EdDSA algorithm configuration

EdDSA algorithm uses an optional 'crv' property with available options Ed25519 (default) or Ed448. Example: jwt({ jwks: { keyPairConfig: { alg: 'EdDSA', crv: 'Ed25519' } } })

RSA256 and PS256 algorithm configuration

RSA256 and PS256 algorithms support an optional 'modulusLength' property that expects a number with default value 2048. Example: jwt({ jwks: { keyPairConfig: { alg: 'RSA256', modulusLength: 2048 } } })

ECDH-ES algorithm configuration

ECDH-ES algorithm supports an optional 'crv' property with available options P-256 (default), P-384, or P-521. Example: jwt({ jwks: { keyPairConfig: { alg: 'ECDH-ES', crv: 'P-256' } } })

Disable private key encryption

By default, the private key is encrypted using AES256 GCM. Disable this by setting disablePrivateKeyEncryption: true in the jwks configuration. For security reasons, it is recommended to keep the private key encrypted.

Key rotation configuration

Enable key rotation by setting rotationInterval (in seconds) in the jwks configuration. Default is undefined (disabled). Also configure gracePeriod (in seconds, default 30 days) to keep the old key pair valid after rotation, allowing clients to verify tokens signed by the old key. Example: jwt({ jwks: { rotationInterval: 60 * 60 * 24 * 30, gracePeriod: 60 * 60 * 24 * 30 } })

Modify JWT payload

Customize the JWT payload by providing a definePayload function to the jwt configuration. The function receives the user object and should return an object with the desired payload fields. Example: jwt({ jwt: { definePayload: ({user}) => ({ id: user.id, email: user.email, role: user.role }) } })

JWT issuer and audience configuration

Configure issuer and audience in jwt configuration. Default is BASE_URL for both. Example: jwt({ jwt: { issuer: 'https://example.com', audience: 'https://example.com' } })

JWT expiration time configuration

Configure expirationTime in jwt configuration. Default is 15 minutes. Accepts time strings like '1h'. Example: jwt({ jwt: { expirationTime: '1h' } })

JWT subject configuration

Customize the JWT subject (sub claim) by providing a getSubject function to the jwt configuration. The function receives the session and should return the subject value. Default subject is the user ID. Example: jwt({ jwt: { getSubject: (session) => session.user.email } })

Custom JWT adapter

Provide a custom adapter to override the default JWKS storage behavior. The adapter can have getJwks and createJwk functions to implement custom storage in alternative locations like Redis or external services. Example: jwt({ adapter: { getJwks: async (ctx) => await yourCustomStorage.getAllKeys(), createJwk: async (ctx, webKey) => await yourCustomStorage.createKey(webKey) } })

Give your agent this brain