docs: document the JWT bearer authorization grant

dhensby · claude · dhensby · commit 1e506f236a5d · 2026-06-24T14:47:56.000+01:00
Add a grant-types guide section and model-function notes for the JWT bearer
authorization grant, and regenerate the API reference.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -62,6 +62,7 @@ export default defineConfig({
                             { text: 'Client Credentials', link: '/api/grant-types/client-credentials-grant-type' },
                             { text: 'Password', link: '/api/grant-types/password-grant-type' },
                             { text: 'Refresh Token', link: '/api/grant-types/refresh-token-grant-type' },
+                            { text: 'JWT Bearer', link: '/api/grant-types/jwt-bearer-grant-type' },
                         ]
                     },
                     {
diff --git a/docs/api/grant-types/jwt-bearer-grant-type.md b/docs/api/grant-types/jwt-bearer-grant-type.md
@@ -0,0 +1,128 @@
+## Classes
+
+<dl>
+<dt><a href="#JwtBearerGrantType">JwtBearerGrantType</a> ⇐ <code>AbstractGrantType</code></dt>
+<dd><p>The JWT bearer authorization grant (RFC 7521 §4.1, RFC 7523 §2.1/§3): a signed
+JWT <em>is</em> the authorization grant. The assertion&#39;s <code>iss</code> identifies a trusted
+issuer (whose key verifies the assertion) and <code>sub</code> identifies the principal
+the access token is issued for. Unlike JWT <em>client authentication</em>, <code>sub</code> is
+the user/principal — not the client — and <code>iss</code>/<code>sub</code> are not bound to the
+client id.</p>
+<p>This is an extension grant; register it via <code>extendedGrantTypes</code>. The
+requested <code>scope</code> is taken from the body parameter (RFC 7521 §4.1), and no
+refresh token is issued (RFC 7521 §5.2).</p>
+<p>The model must implement:</p>
+<ul>
+<li><code>getJWTBearerIssuer(issuer)</code> → <code>{ audience, jwks | jwksUri | secret }</code> (or
+falsy for an untrusted issuer) — the verification key material and the
+expected <code>aud</code>.</li>
+<li><code>getJWTBearerUser({ issuer, subject, client, scope, jti, assertionId, exp })</code> → the
+authorized user (or falsy to deny). Replay (<code>jti</code>) can be enforced here.</li>
+</ul>
+</dd>
+</dl>
+
+## Constants
+
+<dl>
+<dt><a href="#GRANT_TYPE">GRANT_TYPE</a></dt>
+<dd><p>The <code>grant_type</code> value for the JWT bearer authorization grant.</p>
+</dd>
+</dl>
+
+<a name="JwtBearerGrantType"></a>
+
+## JwtBearerGrantType ⇐ <code>AbstractGrantType</code>
+The JWT bearer authorization grant (RFC 7521 §4.1, RFC 7523 §2.1/§3): a signed
+JWT *is* the authorization grant. The assertion's `iss` identifies a trusted
+issuer (whose key verifies the assertion) and `sub` identifies the principal
+the access token is issued for. Unlike JWT *client authentication*, `sub` is
+the user/principal — not the client — and `iss`/`sub` are not bound to the
+client id.
+
+This is an extension grant; register it via `extendedGrantTypes`. The
+requested `scope` is taken from the body parameter (RFC 7521 §4.1), and no
+refresh token is issued (RFC 7521 §5.2).
+
+The model must implement:
+  - `getJWTBearerIssuer(issuer)` → `{ audience, jwks | jwksUri | secret }` (or
+    falsy for an untrusted issuer) — the verification key material and the
+    expected `aud`.
+  - `getJWTBearerUser({ issuer, subject, client, scope, jti, assertionId, exp })` → the
+    authorized user (or falsy to deny). Replay (`jti`) can be enforced here.
+
+**Kind**: global class  
+**Extends**: <code>AbstractGrantType</code>  
+**See**
+
+- https://datatracker.ietf.org/doc/html/rfc7521#section-4.1
+- https://datatracker.ietf.org/doc/html/rfc7523#section-2.1
+- https://datatracker.ietf.org/doc/html/rfc7523#section-3
+
+
+* [JwtBearerGrantType](#JwtBearerGrantType) ⇐ <code>AbstractGrantType</code>
+    * [new JwtBearerGrantType()](#new_JwtBearerGrantType_new)
+    * [.handle(request, client)](#JwtBearerGrantType+handle)
+    * [.verifyAssertion()](#JwtBearerGrantType+verifyAssertion)
+    * [.getKey()](#JwtBearerGrantType+getKey)
+    * [.getUser()](#JwtBearerGrantType+getUser)
+    * [.saveToken()](#JwtBearerGrantType+saveToken)
+
+<a name="new_JwtBearerGrantType_new"></a>
+
+### new JwtBearerGrantType()
+**Example**  
+```js
+new OAuth2Server({
+  model,
+  extendedGrantTypes: {
+    'urn:ietf:params:oauth:grant-type:jwt-bearer': JwtBearerGrantType
+  },
+  // typically a public requester; identify it with `client_id`:
+  requireClientAuthentication: { 'urn:ietf:params:oauth:grant-type:jwt-bearer': false }
+});
+```
+<a name="JwtBearerGrantType+handle"></a>
+
+### jwtBearerGrantType.handle(request, client)
+Handle the JWT bearer grant.
+
+**Kind**: instance method of [<code>JwtBearerGrantType</code>](#JwtBearerGrantType)  
+**See**: https://datatracker.ietf.org/doc/html/rfc7523#section-2.1  
+
+| Param | Type |
+| --- | --- |
+| request | <code>Request</code> | 
+| client | <code>ClientData</code> | 
+
+<a name="JwtBearerGrantType+verifyAssertion"></a>
+
+### jwtBearerGrantType.verifyAssertion()
+Verify the `assertion` and return its (trusted) claims.
+
+**Kind**: instance method of [<code>JwtBearerGrantType</code>](#JwtBearerGrantType)  
+<a name="JwtBearerGrantType+getKey"></a>
+
+### jwtBearerGrantType.getKey()
+Resolve the verification key for the issuer (HMAC secret or asymmetric JWKS).
+
+**Kind**: instance method of [<code>JwtBearerGrantType</code>](#JwtBearerGrantType)  
+<a name="JwtBearerGrantType+getUser"></a>
+
+### jwtBearerGrantType.getUser()
+Resolve and authorize the principal (`sub`) the token is issued for.
+
+**Kind**: instance method of [<code>JwtBearerGrantType</code>](#JwtBearerGrantType)  
+<a name="JwtBearerGrantType+saveToken"></a>
+
+### jwtBearerGrantType.saveToken()
+Save and return the access token. No refresh token is issued (RFC 7521 §5.2).
+
+**Kind**: instance method of [<code>JwtBearerGrantType</code>](#JwtBearerGrantType)  
+<a name="GRANT_TYPE"></a>
+
+## GRANT\_TYPE
+The `grant_type` value for the JWT bearer authorization grant.
+
+**Kind**: global constant  
+**See**: https://datatracker.ietf.org/doc/html/rfc7523#section-2.1  
diff --git a/docs/api/model.md b/docs/api/model.md
@@ -62,6 +62,8 @@ as well as generators, are supported.
         * [.validateRedirectUri(redirectUri, client)](#Model+validateRedirectUri) ⇒ <code>Promise.&lt;boolean&gt;</code>
         * [.isClientAssertionJtiUsed(jti)](#Model+isClientAssertionJtiUsed) ⇒ <code>Promise.&lt;boolean&gt;</code>
         * [.saveClientAssertionJti(jti, exp)](#Model+saveClientAssertionJti) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [.getJWTBearerIssuer(issuer)](#Model+getJWTBearerIssuer) ⇒ <code>Promise.&lt;object&gt;</code>
+        * [.getJWTBearerUser(params)](#Model+getJWTBearerUser) ⇒ <code>Promise.&lt;object&gt;</code>
     * _static_
         * [.from(impl)](#Model.from) ⇒ [<code>Model</code>](#Model)
 
@@ -648,6 +650,41 @@ both this and `isClientAssertionJtiUsed` are implemented.
 | jti | <code>string</code> | The `jti` claim of the client assertion. |
 | exp | <code>number</code> | The assertion's `exp` (epoch seconds), for use as a TTL. |
 
+<a name="Model+getJWTBearerIssuer"></a>
+
+### model.getJWTBearerIssuer(issuer) ⇒ <code>Promise.&lt;object&gt;</code>
+Invoked to resolve a trusted issuer for the JWT bearer authorization grant.
+**Required** when the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant is enabled.
+
+**Invoked during:**
+- JWT bearer authorization grant (`JwtBearerGrantType`)
+
+**Kind**: instance method of [<code>Model</code>](#Model)  
+**Returns**: <code>Promise.&lt;object&gt;</code> - Resolves to the issuer's verification key material and the
+  expected audience: `{ audience, jwks | jwksUri | secret }`. Resolve to a falsy value
+  to reject the issuer as untrusted (`invalid_grant`).  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| issuer | <code>string</code> | The assertion's `iss` claim. |
+
+<a name="Model+getJWTBearerUser"></a>
+
+### model.getJWTBearerUser(params) ⇒ <code>Promise.&lt;object&gt;</code>
+Invoked to resolve and authorize the principal a JWT bearer assertion is issued for.
+**Required** when the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant is enabled.
+
+**Invoked during:**
+- JWT bearer authorization grant (`JwtBearerGrantType`)
+
+**Kind**: instance method of [<code>Model</code>](#Model)  
+**Returns**: <code>Promise.&lt;object&gt;</code> - Resolves to the authorized user, or a falsy value to deny the
+  grant (`invalid_grant`). Single-use (`jti`) replay protection can be enforced here.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| params | <code>object</code> | `{ issuer, subject, client, scope, jti, assertionId, exp }` from the verified assertion. `assertionId` is the `jti`, or a fingerprint of the assertion's signing input when it has no `jti` — use it for single-use replay protection. |
+
 <a name="Model.from"></a>
 
 ### Model.from(impl) ⇒ [<code>Model</code>](#Model)
diff --git a/docs/guide/grant-types.md b/docs/guide/grant-types.md
@@ -51,6 +51,95 @@ The client can request an access token using only its client credentials (or oth
 when requesting access to the protected resources under its control.
 The client credentials grant type **must** only be used by confidential clients.
 
+## JWT Bearer Grant Type
+
+**Defined in:** [RFC 7523 §2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1) (a profile of the [assertion framework, RFC 7521](https://datatracker.ietf.org/doc/html/rfc7521)).
+
+A signed JWT *is* the authorization grant: the assertion's `iss` identifies a trusted issuer
+and `sub` the principal the access token is issued for. This is the flow used for service-account
+and trusted-IdP token exchange. It ships as an opt-in extension grant, `JwtBearerGrantType`,
+registered through `extendedGrantTypes`:
+
+``` js
+const OAuth2Server = require('@node-oauth/oauth2-server');
+const { JwtBearerGrantType } = OAuth2Server;
+
+const server = new OAuth2Server({
+  model,
+  extendedGrantTypes: {
+    'urn:ietf:params:oauth:grant-type:jwt-bearer': JwtBearerGrantType
+  },
+  // the requester MUST be identified by a registered `client_id` (see note below):
+  requireClientAuthentication: { 'urn:ietf:params:oauth:grant-type:jwt-bearer': false }
+});
+```
+
+The client sends the assertion as a normal token request; `scope` is a body parameter (it is not
+read from the assertion):
+
+```
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
+&assertion=eyJhbGciOiJSUzI1Ni...
+&client_id=client-1
+&scope=read
+```
+
+**Model requirements:** in addition to `getClient` and `saveToken`, the model must implement:
+
+- `getJWTBearerIssuer(issuer)` — resolve a trusted issuer's verification key material and expected
+  audience (`{ audience, jwks | jwksUri | secret }`); return a falsy value to reject an untrusted issuer.
+- `getJWTBearerUser({ issuer, subject, client, scope, jti, assertionId, exp })` — resolve and
+  authorize the principal the token is for; return a falsy value to deny. Enforce single-use replay
+  protection here if required, keyed on `assertionId` (the `jti`, or a signing-input fingerprint when
+  the assertion has no `jti`).
+
+``` js
+const model = {
+  async getJWTBearerIssuer (issuer) {
+    const trusted = await db.findTrustedIssuer(issuer)
+    if (!trusted) return false
+    return { audience: 'https://as.example.com/oauth/token', jwks: trusted.jwks }
+  },
+  async getJWTBearerUser ({ issuer, subject, assertionId, exp }) {
+    // MUST verify this issuer is permitted to assert this subject, otherwise any
+    // trusted issuer could obtain a token for any user:
+    if (!await db.issuerMayAssert(issuer, subject)) return false
+    // Enforce single-use to prevent replay. `assertionId` is the `jti`, or a
+    // signing-input fingerprint when the assertion carries no `jti`:
+    if (await db.assertionIdUsed(assertionId)) return false
+    await db.saveAssertionId(assertionId, exp)
+    return db.findUser(subject)
+  }
+}
+```
+
+The assertion is verified per [RFC 7523 §3](https://datatracker.ietf.org/doc/html/rfc7523#section-3)
+(signature against the issuer's key, required `iss`/`sub`/`aud`/`exp`, audience and algorithm
+checks); a failed assertion is rejected with `invalid_grant`. No refresh token is issued
+([RFC 7521 §5.2](https://datatracker.ietf.org/doc/html/rfc7521#section-5.2)).
+
+> [!WARNING]
+> **Replay:** the library does not track used assertions itself. Unless `getJWTBearerUser` enforces
+> single-use on `assertionId` (and/or you keep `exp` short), a captured assertion is replayable
+> until it expires — and each replay yields a fresh access token. `assertionId` is stable whether or
+> not the assertion carries a `jti`, so track it and prefer short-lived assertions.
+
+> [!WARNING]
+> **Issuer/subject authorization:** `getJWTBearerUser` MUST verify that the `issuer` is permitted to
+> assert the given `subject`. If it merely resolves the subject to a user, any trusted issuer can
+> obtain a token for any user.
+
+> [!NOTE]
+> This grant requires a registered `client_id` (resolved via `getClient`); it does not support the
+> assertion-only request (no `client_id`) used by some providers, because the client is resolved
+> before the grant runs. It asserts *who is authorized* and is distinct from
+> [JWT client authentication](./client-authentication.md#jwt-client-authentication), where the JWT
+> proves the *client's own* identity (`iss == sub == client_id`). The two are separable and may be
+> combined.
+
 ## Extension Grants
 
 **Defined in:** [Section 4.5 of RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-4.4).
diff --git a/docs/guide/model.md b/docs/guide/model.md
@@ -103,6 +103,16 @@ Model functions used by the [password grant](grant-types.md#password-grant-type)
 - [saveToken](../api/model.md#modelsavetokentoken-client-user--codepromiseobjectcode)
 - [validateScope](../api/model.md#modelvalidatescopeuser-client-scope--codepromisebooleancode)
 
+### JWT Bearer Grant
+
+Model functions used by the [JWT bearer authorization grant](grant-types.md#jwt-bearer-grant-type)
+(`JwtBearerGrantType`, registered via `extendedGrantTypes`):
+
+- [getClient](../api/model.md#modelgetclientclientid-clientsecret--code-promiseclientdata-code)
+- [saveToken](../api/model.md#modelsavetokentoken-client-user--codepromiseobjectcode)
+- `getJWTBearerIssuer` — resolve a trusted issuer's verification keys and expected audience
+- `getJWTBearerUser` — resolve and authorize the assertion subject (and optionally enforce `jti` single-use)
+
 ### Extension Grants
 
 The authorization server may also implement custom grant types to issue access (and optionally refresh) tokens.

Original file line number	Diff line number	Diff line change
`@@ -62,6 +62,7 @@ export default defineConfig({`
`62`	`62`	`{ text: 'Client Credentials', link: '/api/grant-types/client-credentials-grant-type' },`
`63`	`63`	`{ text: 'Password', link: '/api/grant-types/password-grant-type' },`
`64`	`64`	`{ text: 'Refresh Token', link: '/api/grant-types/refresh-token-grant-type' },`
	`65`	`+ { text: 'JWT Bearer', link: '/api/grant-types/jwt-bearer-grant-type' },`
`65`	`66`	`]`
`66`	`67`	`},`
`67`	`68`	`{`