JWT Subject Claim Validation (Preview)

Attention

This behavior change is in the 2025_06 bundle.

For the current status of the bundle, refer to Bundle History.

Overview

This document describes an upcoming change to the validation process for JSON Web Tokens (JWTs) used with key-pair authentication for Snowflake REST APIs. To enhance security, we are deprecating a legacy flow that accepted JWTs with an empty sub (subject) claim.

Action Required: If your application uses key-pair authentication, you must update your JWT generation logic to ensure the sub claim is properly formatted to avoid authentication failures.

What’s Changing

Note

When this change bundle is enabled by default, JWTs with an empty sub claim will be rejected, regardless of the iss claim format.

Before the change:

JWTs were accepted even if the sub claim was empty, provided the iss (issuer) claim was formatted correctly for this case.

After the change:

The system will now strictly enforce that the sub claim must contain a valid value. If the sub claim is empty, the JWT will be rejected and authentication will fail.

Impact

Any application or script that relies on the old behavior of sending a JWT with an empty sub claim will begin to fail authentication requests. This will result in an immediate interruption of service for these applications.

Required Actions

To avoid any service interruption, take the following steps:

  1. Review your applications and scripts that use key-pair authentication to connect to Snowflake REST APIs.

  2. Ensure that the logic for generating your JWT includes both a properly formatted iss (issuer) claim and a valid sub (subject) claim.

  3. The correct format for the claims are:

    • iss: Must be formatted as <account_identifier>.<user>.SHA256:<public_key_fingerprint>

    • sub: Must be formatted as <account_identifier>.<user>

For detailed instructions and examples on how to correctly format and generate your JWT, see Using key pair authentication.

Ref: 2077

Language: English