🔧 Supabase Auth Itroduces Asymmetric JWTs

Asymmetric JWTs in Q4 2024

In the beginning of October 2024 Supabase has announced the details on upcomming introduction of asymetric JWTs.

The news is that Supabse has decided to push back the launch from 7th October 2024 to Q4 2024 to roll this out meticulously; they want to perform exhaustive security checks and spend more time dogfooding internally.

Very simply speaking this is good old days public - private keys encription flow. Your one private key used in a backend and publicly shareable key to read.

Changes

To use asymetric JWTs in your Supabase project you will need to include these following changes:

• Get an asymmetric key through the Supabase dashboard.
• Include new public JWKs endpoint for retrieving the public JWK to verify JWTs. This will be exposed through the https://<project_ref>.supabase.co/auth/v1/.well-known/jwks.json endpoint. The symmetric secret will not be exposed through this endpoint for security reasons.
• Use a new method called getClaims() , which handles verifying the JWT and returning the claims in it.
• Use the public key in matter, you will be able to download the public keys in different formats through the dashboard (e.g. PEM, JWKs).
• Ensure that you are using the new API keys (publishable key: sb_publishable_123abc and secret key: sb_secret_123abc instead of old anon key: eyJhbGciOiJIUzI1...FDsBGn0iqSmL28Zeg8f0 and service_role key: eyJhbGciOiJIUzI1...SEVEyZQNhffCoSj4P5A.
• Update all your clients to use at least supabase-js version x.x.x (the version number will be updated closer to the release date) which will inroduce the new getClaims method.

getClaims() method

getClaims will be able to handle verifying both asymmetric JWTs as well as symmetric JWTs.

To use getClaims() to verify the JWT your code will probably look like this:

import { createClient } from 'supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

// previously, using getUser() requires making an 
// additional network request to Supabase Auth to verify the JWT
// 
// const { data, error } = await supabase.auth.getUser()

// getClaims() will always return the JWT payload if the JWT is verified
// If it's an asymmetric JWT, getClaims() will verify using the JWKs endpoint.
// If it's a symmetric JWT, getClaims() calls getUser() to verify the JWT. 
const { data, error } = await supabase.auth.getClaims(jwks)

Calling getClaims() without passing in the JWKs will still require a network request to the /auth/v1/.well-known/jwks.json endpoint, however Supabase will be able to cache the JWKs in-memory so that subsequent calls to getClaims() don't have to make a request. getClaims() without argumentd will still require a network request. But getClaims(jwks) will avoid a network request.

Advantages

• Usage of asymmetric key cryptography rather than a shared symmetric secret. Since asymmetric keys don’t use a shared secret, there is less risk of the secret being leaked.
• Reducing extra network requests due to faster JWT verification times since there’s no need to make a network call to Supabase Auth via getUser().
• Zero-downtime key rotation. Public keys can be exposed and any one of them may be used for verification.

Migration

New projects that are created after 1st May 2025 will be created with an RSA asymmetric key by default. Existing projects can choose to start using asymmetric keys as mentioned above.