| Internet-Draft | OIDC Cryptographic Agility | November 2026 |
| de Medeiros | Expires 20 May 2027 | [Page] |
This specification defines mechanisms to improve cryptographic
agility in OpenID Connect and OAuth 2.0 by enabling discovery and
negotiation of JSON Web Token (JWT) signing algorithms between a
client and an authorization server. It registers the
authorization_server_jwt_signing_algorithms_supported
metadata value in the IANA "OAuth Authorization Server Metadata"
registry established by RFC 8414, and registers the
jwt_signing_algorithm parameter in the IANA "OAuth
Parameters" registry established by RFC 6749 for use in both
authorization requests and jwks_uri retrieval requests.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 20 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
OpenID Connect [OpenID.Core] and OAuth 2.0 deployments rely on JSON Web Tokens (JWTs) [RFC7519] protected with JSON Web Signatures (JWS) [RFC7515] to convey identity assertions and security tokens. Over time, authorization servers and clients must transition between cryptographic signing algorithms to adopt stronger primitives or deprecate legacy algorithms.¶
In existing deployments using OAuth 2.0 Authorization Server
Metadata [RFC8414] and OpenID Connect Discovery
[OpenID.Discovery], transitioning an authorization
server's signing keys and algorithms presents operational and
security challenges. In particular, it can be problematic to publish
keys for multiple signing algorithms simultaneously in a single JSON
Web Key (JWK) Set [RFC7517] document at the
jwks_uri endpoint without an inline negotiation mechanism
per request.¶
This specification improves cryptographic agility by enabling explicit discovery and per-request negotiation of the cryptographic signing algorithm between a client and an authorization server. It upholds two best practices:¶
Separation of Keys by Security Assurance:
Keys associated with different signing algorithms often carry
varying levels of cryptographic strength, hardware protection,
or operational security assurance. Partitioning the JWK Set
response by the requested jwt_signing_algorithm
parameter ensures that keys with varying levels of security
assurance are not mixed within the same trust document. A
client requesting a specific signing algorithm retrieves only
the verification keys corresponding to that algorithm and
assurance level.¶
Safe Upgrades for Clients with Brittle JWK Set
Parsing: Historically, it has been observed that some
deployed clients implement brittle logic when retrieving and
parsing the JWK Set document from jwks_uri. For
example, some client implementations might fail to parse the
entire JWK Set if it contains an unrecognized key type (kty), curve (crv), or algorithm
(alg), while others assume that only a single signing
algorithm is present in the document. By establishing a
convention where a parameterized jwks_uri request
returns the key(s) matching the specified algorithm,
authorization servers can safely introduce new signing
algorithms without modifying the format of the default
jwks_uri document returned, and without breaking
existing clients.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This specification uses the terms "Authorization Endpoint", "Authorization Request", "Authorization Server", "Client", and "Token Endpoint" defined by OAuth 2.0 [RFC6749]; the terms "JSON Web Key (JWK)" and "JWK Set" defined by [RFC7517]; the term "JSON Web Signature (JWS)" defined by [RFC7515]; the term "JSON Web Token (JWT)" defined by [RFC7519]; and the term "ID Token" defined by OpenID Connect Core 1.0 [OpenID.Core].¶
This specification defines the following authorization server metadata parameter, which is registered in the IANA "OAuth Authorization Server Metadata" registry established in Section 7.1 of [RFC8414]:¶
authorization_server_jwt_signing_algorithms_supported
OPTIONAL. JSON array containing a list of the JWS
[RFC7515] signing algorithms (alg values)
supported by the authorization server for signing JWTs
[RFC7519] issued by the server (such as OpenID
Connect ID Tokens [OpenID.Core]). The values in
this list MUST be pre-registered algorithm names
from the IANA "JSON Web Signature and Encryption Algorithms"
registry established by JSON Web
Algorithms (JWA) [RFC7518] with an implementation requirement or
usage of digital signature or MAC. The algorithm value
none MUST NOT be included. If present,
this array MUST contain at least one element.¶
By convention, the first entry in the
authorization_server_jwt_signing_algorithms_supported
list is the default algorithm that the authorization server
MUST use when no jwt_signing_algorithm
parameter is specified by the client in the authorization
request, unless the client has registered a different preference
with the authorization server.¶
An authorization server MAY update the order of
the algorithms in
authorization_server_jwt_signing_algorithms_supported,
thereby updating the default signing algorithm. To allow for
smooth transitions, the authorization server
SHOULD NOT select as a new default an algorithm
that was previously unlisted, and SHOULD NOT drop
the former default algorithm completely when changing the
default, instead leaving it as an optional algorithm (i.e.,
listed not as the first option in the list) for some time after
it stops being the default. The duration of time between
publishing an algorithm and promoting it to the default, or to
deprecate support for a former default algorithm, is not
governed by this specification and should be guided by the
application's context.¶
The following is a non-normative example of an Authorization Server
Metadata document snippet advertising support for RS256 as
the default signing algorithm, along with ES256 and the
post-quantum signature algorithms ML-DSA-44 and
ML-DSA-87 [RFC9964] as additional negotiable
signing algorithms:¶
{
"issuer": "https://server.example.com",
"authorization_endpoint": "https://server.example.com/authorize",
"token_endpoint": "https://server.example.com/token",
"jwks_uri": "https://server.example.com/jwks.json",
"response_types_supported": ["code", "id_token", "code id_token"],
"authorization_server_jwt_signing_algorithms_supported": [
"RS256",
"ES256",
"ML-DSA-44",
"ML-DSA-87"
]
}
¶
jwt_signing_algorithm Parameter
This specification defines the jwt_signing_algorithm OAuth
parameter and registers it in the IANA "OAuth Parameters" registry
established by [RFC6749]. The parameter value
MUST be a single case-sensitive string selected from
the values advertised in the authorization server's
authorization_server_jwt_signing_algorithms_supported
metadata parameter.¶
The jwt_signing_algorithm parameter is available in two
protocol locations:¶
jwks_uri JWK Set retrieval request (see
Section 3.2).¶
When sending an authorization request to the authorization
endpoint, a client MAY include the
jwt_signing_algorithm parameter to request that the
authorization server sign resulting JWTs (such as the ID Token
returned from the authorization endpoint or token endpoint) using
the specified algorithm:¶
jwt_signing_algorithmalg algorithm value
that the client requests the authorization server to use when
signing JWTs resulting from this authorization request. The
value MUST be one of the values listed in the
authorization server's published
authorization_server_jwt_signing_algorithms_supported
metadata.¶
Authorization server processing rules for the
jwt_signing_algorithm parameter in an authorization
request are as follows:¶
jwt_signing_algorithm parameter is present and
its value is listed in
authorization_server_jwt_signing_algorithms_supported,
the authorization server MUST sign the JWT(s)
issued as a result of the authorization request (including any
JWTs issued at the authorization endpoint or at the token
endpoint when exchanging the resulting authorization code) using
the requested algorithm.¶
jwt_signing_algorithm parameter is omitted from
the authorization request, the authorization server
MUST use the first entry in
authorization_server_jwt_signing_algorithms_supported
as the default signing algorithm, unless another algorithm has
been configured for the client by out-of-band or dynamic
registration means.¶
jwt_signing_algorithm parameter is present more
than once, or contains a value that is not supported by the
authorization server (i.e., not present in
authorization_server_jwt_signing_algorithms_supported),
the authorization server MUST reject the request
and return an invalid_request error response as
specified in Section 4.1.2.1 of [RFC6749].¶
The following is a non-normative example of an authorization
request (with line breaks for display purposes only) in which the
client requests the ML-DSA-44 signing algorithm:¶
jwks_uri Retrieval Request
When retrieving the authorization server's JWK Set document from
the URL advertised in the jwks_uri metadata parameter, a
client MAY include the
jwt_signing_algorithm query parameter in the HTTP
GET request:¶
jwt_signing_algorithmjwks_uri URL indicating the signing algorithm for which
the client is requesting public verification keys. The value
MUST be selected from the values in the
authorization server's published
authorization_server_jwt_signing_algorithms_supported
metadata. If the jwks_uri already contains query
parameters, the client MUST append
jwt_signing_algorithm using standard
application/x-www-form-urlencoded query syntax per
[RFC3986].¶
Authorization server processing rules for jwks_uri
requests are as follows:¶
jwt_signing_algorithm query parameter is
omitted from the jwks_uri request, the authorization
server MUST return a JWK Set containing the
signing keys corresponding to the first entry in
authorization_server_jwt_signing_algorithms_supported
(the default signing algorithm), along with any applicable
encryption keys as permitted by [RFC8414]. It is
RECOMMENDED that the authorization server exclude
keys from signing algorithms other than the default, but it
MAY continue to include signing keys for multiple
signing algorithms if it previously did so. If including keys
from multiple signing algorithms, the server MAY
still exclude any signing algorithms other than the default.¶
jwt_signing_algorithm query parameter is
present and matches one of the values in
authorization_server_jwt_signing_algorithms_supported,
the authorization server MUST return a JWK Set
containing only the signing keys corresponding to the requested
algorithm. Keys for other signing algorithms
MUST NOT be included in the returned JWK Set.¶
jwt_signing_algorithm query parameter contains
an unsupported or unrecognized algorithm value, the
authorization server MUST respond with an HTTP
400 Bad Request status code.¶
The following is a non-normative example of a jwks_uri
request specifying jwt_signing_algorithm=ML-DSA-44:¶
The following is a non-normative example of the corresponding JWK
Set response containing only ML-DSA-44 signing keys (with
the pub value abbreviated for readability):¶
Because the jwt_signing_algorithm parameter in an
authorization request is typically transmitted via front-channel
browser redirection, an attacker capable of modifying URL query
parameters in transit (for example, via an open redirector, browser
history manipulation, or a malicious intermediary) might attempt to
substitute or remove the jwt_signing_algorithm parameter
to force the use of a weaker signing algorithm than the client
intended.¶
Clients specifying an algorithm during authorization requests SHOULD ensure that it cannot be substituted between the request and response via a URL modification by applying appropriate security measures.¶
Specifically, when a client includes jwt_signing_algorithm
in an authorization request:¶
jwt_signing_algorithm value to the user's
local session state associated with the request, or
cryptographically bind the selected algorithm to the
state parameter sent in the authorization request.¶
alg header
parameter of the received JWS matches the specific algorithm
bound to that session or state value, rather than
merely checking that the algorithm is in the server's supported
list. If the alg header does not match the bound
algorithm, the client MUST reject the JWT.¶
Mixing verification keys of different cryptographic strengths or security assurance levels within a single JWK Set document creates a risk that a compromise of a lower-assurance key or weaker algorithm could be used to forge tokens accepted by clients that intended to rely on a higher-assurance algorithm.¶
To mitigate this risk, authorization servers MUST
ensure that a jwks_uri response for a given
jwt_signing_algorithm contains only keys designated for
that algorithm. When authorization servers indicate support for
JWT algorithm selection via the metadata parameter
authorization_server_jwt_signing_algorithms_supported,
clients SHOULD indicate their preferred algorithm
during the authorization request (unless the preference is already
otherwise registered with the authorization server) and
SHOULD specify the jwt_signing_algorithm
during the jwks_uri retrieval.¶
All requests to retrieve authorization server metadata and JWK Set
documents from jwks_uri MUST use TLS in
accordance with Section 6.1 of [RFC8414] and
[BCP195] to protect the integrity and authenticity
of the discovered algorithms and public verification keys.¶
This specification requests that IANA register the following value in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414]:¶
authorization_server_jwt_signing_algorithms_supported¶
alg values) from [RFC7518] supported by
the authorization server for signing JWTs, where the first entry
is the default algorithm used by the server when no algorithm
parameter is specified.¶
This specification requests that IANA register the following parameter in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] established by [RFC6749]:¶