OpenID Connect Token Hash Algorithm Implementer's Guide 1.0 - draft 00

Table of Contents

1. Introduction

OpenID Connect Core 1.0 [OpenID.Core] defines ID Token hash claims such as at_hash and c_hash as the base64url encoding of the left-most half of the hash of the ASCII representation of the value being bound to the ID Token. Core says that the hash algorithm is the hash algorithm specified in JWA [JWA] for the alg Header Parameter of the ID Token's JOSE Header.¶

Other OpenID specifications use the same construction. Financial-grade API Security Profile 1.0 - Part 2: Advanced [OpenID.FAPI.Advanced] defines s_hash for the state value. OpenID Connect CIBA Core 1.0 [OpenID.CIBA] uses at_hash in Push mode and applies the same method to Refresh Token hash values using the urn:openid:params:jwt:claim:rt_hash claim.¶

That rule is clear for algorithms such as RS256, ES384, and HS512, because their registered algorithm identifiers specify the hash algorithm directly. It is ambiguous for polymorphic algorithms such as EdDSA, because the hash algorithm depends on the EdDSA parameter set of the key used to validate the ID Token. Fully-specified algorithm identifiers, such as Ed25519 and Ed448, remove this ambiguity.¶

This guide clarifies the hash algorithm selection for current JWS algorithms used with OpenID Connect ID Tokens. It does not define new JWS algorithms, new ID Token claims, or new ID Token validation procedures.¶

2. Hash Claim Calculation

To calculate an ID Token hash claim, such as at_hash, c_hash, s_hash, urn:openid:params:jwt:claim:rt_hash, or any other OpenID Connect claim that uses the same construction, implementations MUST:¶

1. Select the digest function and, when applicable, its output length using Table 1.¶

2. Apply the digest function to the octets of the ASCII representation of the value being bound to the ID Token.¶

3. Take the left-most half of the resulting digest output.¶

4. Base64url-encode that left-most half without padding.¶

For extendable-output functions, the "resulting digest output" is the fixed-length output identified in Table 1. For instance, SHAKE256 with 114 bytes of output produces a 114-byte digest output, whose left-most half is 57 bytes.¶

When EdDSA is used, implementations MUST determine the EdDSA parameter set from the key used to validate the ID Token signature, such as the JWK crv value, and then use the corresponding entry in Table 1. The EdDSA algorithm identifier is deprecated by [RFC9864], and new deployments SHOULD use the fully-specified Ed25519 and Ed448 algorithm identifiers instead.¶

The algorithm identifiers in Table 1 are defined by [JWA], [RFC8037], [RFC8812], [RFC9864], [RFC9964], and [I-D.ietf-cose-sphincs-plus]. The EdDSA parameter sets are defined by [RFC8032]. The ML-DSA algorithms use the signing procedure defined by [FIPS204]. The SLH-DSA algorithms use parameter sets defined by [FIPS205]. The listed SLH-DSA rows are included to track current JOSE algorithm identifier registrations; this guide records a recommended resolution but leaves final selection of their hash claim digest functions and output lengths to the Working Group.¶

The SLH-DSA recommendation intentionally uses the public hash or extendable-output function family named by the JWS algorithm, rather than the SLH-DSA H_msg construction. [FIPS205] defines H_msg for SHA2 Category 1 parameter sets using MGF1-SHA-256 over values that include signature randomness and public-key material. Those inputs are not part of the OpenID Connect hash claim construction.¶

3. Examples

Given the access_token value YmJiZTAwYmYtMzgyOC00NzhkLTkyOTItNjJjNDM3MGYzOWIy9sFhvH8K_x8UIHj1osisS57f5DduL, Table 2 contains the resulting at_hash values for the hash algorithms listed in Table 1.¶

Every value in the alg value column is a literal JOSE alg identifier. Conditions that are not alg identifiers, such as an EdDSA key parameter set, are shown in the separate Key condition column. For algorithms whose claim digest function is still to be determined but has a recommendation, the examples use the recommended value.¶

The same procedure applies to other ID Token hash claims by replacing the input value with the ASCII representation of the value being bound to the ID Token.¶

4. Security Considerations

This guide does not change the security properties of the ID Token hash claims defined by OpenID Connect Core. It clarifies which hash or extendable-output function to use so that OpenID Providers and Relying Parties produce the same values.¶

For extendable-output functions, implementations MUST use the output length specified in Table 1 before taking the left-most half of the output. Using a different output length will produce different hash claim values.¶

For JWS algorithms whose row in Table 1 marks the claim digest function as to be determined, the listed recommendation is provisional implementation guidance rather than a final Working Group decision. Implementations using a different rule will produce different hash claim values.¶

For EdDSA, implementations MUST NOT infer the hash algorithm from the alg Header Parameter alone. They need the EdDSA parameter set of the key used to validate the ID Token signature.¶

5. Acknowledgements

The OpenID Connect Working Group discussed the EdDSA hash claim ambiguity in GitHub issue openid/connect#1124 and earlier Bitbucket issue 1125. The contributors to that discussion include Michael B. Jones, Vladimir Dzhuvinov, Nat Sakimura, Tim Moehlmann, Tangui, and Filip Skokan.¶

Appendix A. Notices

Copyright (c) 2026 The OpenID Foundation.¶

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy (found at openid.net) requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. OpenID invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶

Appendix B. Document History

[[ To be removed from the final document ]]¶

-00¶

• Initial Implementer's Guide defining the hash algorithms to use for OpenID Connect ID Token hash claims with EdDSA, fully-specified EdDSA, and ML-DSA JWS algorithms, and tracking SLH-DSA JWS algorithm identifiers pending Working Group consensus on hash claim digest functions, with recommended SLH-DSA digest functions for discussion.¶

• Included Financial-grade API s_hash and OpenID Connect CIBA profile hash claims in the stated scope.¶

• Split table columns so literal alg identifiers, key conditions, digest functions, and output lengths are clearly distinguishable.¶

Author's Address