Internet-Draft OIDC Cryptographic Agility November 2026
de Medeiros Expires 20 May 2027 [Page]
Workgroup:
OAuth Working Group
Internet-Draft:
draft-demedeiros-oidc-crypto-agility-00
Published:
Intended Status:
Standards Track
Expires:
Author:
B. de Medeiros
Google

Cryptographic Agility for OpenID Connect

Abstract

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.

Status of This Memo

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.

▲

Table of Contents

1. Introduction

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.

1.1. Rationale and Best Practices

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:

  1. 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.

  2. 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.

1.2. Requirements Notation and Conventions

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.

1.3. Terminology

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].

2. Authorization Server Metadata Extension

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"
  ]
}

3. The 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:

3.1. Usage in the Authorization Request

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_algorithm
OPTIONAL. The JWS alg 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:

  • If the 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.
  • If the 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.
  • If the 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:

GET /authorize?
  response_type=code
  &scope=openid%20profile
  &client_id=s6BhdRkqt3
  &state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
  &jwt_signing_algorithm=ML-DSA-44 HTTP/1.1
Host: server.example.com

3.2. Usage in the 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_algorithm
OPTIONAL. Query parameter added to the jwks_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:

  • When the 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.
  • When the 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.
  • When the 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:

GET /jwks.json?jwt_signing_algorithm=ML-DSA-44 HTTP/1.1
Host: server.example.com

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):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keys": [
    {
      "kty": "AKP",
      "use": "sig",
      "alg": "ML-DSA-44",
      "kid": "2026-mldsa44-key-1",
      "pub": "unH59k4Ru...DZgbTP07e7gEWzw4MFRrndjbDQ"
    }
  ]
}

4. Security Considerations

4.1. Preventing Algorithm Substitution and Downgrade Attacks

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:

  • The client SHOULD cryptographically bind the requested 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.
  • Upon receiving the authorization response (and any JWTs obtained from the authorization endpoint or token endpoint), the client MUST confirm that the 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.

4.2. Key Isolation Across Security Assurance Levels

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.

4.3. Transport-Layer Security

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.

5. IANA Considerations

5.1. OAuth Authorization Server Metadata Registration

This specification requests that IANA register the following value in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414]:

Metadata Name:
authorization_server_jwt_signing_algorithms_supported
Metadata Description:
JSON array containing a list of the JWS signing algorithms (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.
Change Controller:
IESG
Specification Document(s):
Section 2 of this specification

5.2. OAuth Parameters Registration

This specification requests that IANA register the following parameter in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] established by [RFC6749]:

Parameter name:
jwt_signing_algorithm
Parameter usage location:
authorization request, jwks_uri request
Change controller:
IESG
Specification document(s):
Section 3 of this specification
Related information:
None

6. References

6.1. Normative References

[BCP195]
Sheffer, Y., Saint-Andre, P., and T. Fossati, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, , <https://www.rfc-editor.org/info/bcp195>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC7515]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, , <https://www.rfc-editor.org/info/rfc7515>.
[RFC7517]
Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, , <https://www.rfc-editor.org/info/rfc7517>.
[RFC7518]
Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, , <https://www.rfc-editor.org/info/rfc7518>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.

6.2. Informative References

[IANA.OAuth.Parameters]
IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0", , <https://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
[RFC9964]
Prorock, M. and O. Steele, "ML-DSA for JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE)", RFC 9964, DOI 10.17487/RFC9964, , <https://www.rfc-editor.org/info/rfc9964>.

Author's Address

Breno de Medeiros
Google