Skip to content

feat: add RFC 8414 issuer discovery - #946

Merged
jcmartinezdev merged 1 commit into
jsonwebtoken:masterfrom
panva:rfc8414-key-discovery
Jul 31, 2026
Merged

feat: add RFC 8414 issuer discovery#946
jcmartinezdev merged 1 commit into
jsonwebtoken:masterfrom
panva:rfc8414-key-discovery

Conversation

@panva

@panva panva commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

As per https://www.rfc-editor.org/info/rfc8414/

This extends the existing list of means the debugger has to resolve the public key from

Priority Mechanism Behavior
1 x5c header Uses the first certificate in the embedded chain and converts it to PEM.
2 x5u header Intended to fetch a remote certificate.
3 jku header Fetches the remote JWKS and lets jose select a key using the JWT header, including kid.
4 jwk header Uses the public JWK embedded directly in the JWT header.
5 iss payload claim Fetches {iss}/.well-known/openid-configuration, reads jwks_uri, then resolves the matching key from that JWKS.
6 Manual entry Accepts JWK or PEM: X.509 certificate, SPKI public key, or PKCS#1 RSA public key.

to

Priority Mechanism Behavior
1 x5c header Uses the first certificate in the embedded chain and converts it to PEM.
2 x5u header Intended to fetch a remote certificate.
3 jku header Fetches the remote JWKS and lets jose select a key using the JWT header, including kid.
4 jwk header Uses the public JWK embedded directly in the JWT header.
5 iss via RFC 8414 Fetches /.well-known/oauth-authorization-server, inserted before any issuer path. Validates the returned issuer, reads the HTTPS jwks_uri, and resolves the matching key.
6 iss via OpenID Discovery If RFC 8414 discovery fails, fetches {iss}/.well-known/openid-configuration. Applies the same issuer and jwks_uri validation, then resolves the matching key.
7 Manual entry Accepts JWK or PEM: X.509 certificate, SPKI public key, or PKCS#1 RSA public key.
diff
 | Priority | Mechanism | Behavior |
 |---|---|---|
 | 1 | `x5c` header | Uses the first certificate in the embedded chain and converts it to PEM. |
 | 2 | `x5u` header | Intended to fetch a remote certificate. |
 | 3 | `jku` header | Fetches the remote JWKS and lets `jose` select a key using the JWT header, including `kid`. |
 | 4 | `jwk` header | Uses the public JWK embedded directly in the JWT header. |
-| 5 | `iss` payload claim | Fetches `{iss}/.well-known/openid-configuration`, reads `jwks_uri`, then resolves the matching key from that JWKS. |
-| 6 | Manual entry | Accepts JWK or PEM: X.509 certificate, SPKI public key, or PKCS#1 RSA public key. |
+| 5 | `iss` via RFC 8414 | Fetches `/.well-known/oauth-authorization-server`, inserted before any issuer path. Validates the returned `issuer`, reads the HTTPS `jwks_uri`, and resolves the matching key. |
+| 6 | `iss` via OpenID Discovery | If RFC 8414 discovery fails, fetches `{iss}/.well-known/openid-configuration`. Applies the same issuer and `jwks_uri` validation, then resolves the matching key. |
+| 7 | Manual entry | Accepts JWK or PEM: X.509 certificate, SPKI public key, or PKCS#1 RSA public key. |

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
@panva
panva force-pushed the rfc8414-key-discovery branch from 41808aa to 1b9f1c0 Compare July 31, 2026 14:47
@jcmartinezdev
jcmartinezdev merged commit d88e970 into jsonwebtoken:master Jul 31, 2026
2 checks passed
@panva
panva deleted the rfc8414-key-discovery branch July 31, 2026 17:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants