feat: support jwt signing keys for local auth by cemalkilic · Pull Request #3841 · supabase/cli

cemalkilic · 2025-07-10T19:44:58Z

What kind of change does this PR introduce?

command to generate jwt signing keys & spin up auth server with the configured JWK keys

Steps

Generate the jwt signing keys by supabase gen signing-key ES256
Enable signing_keys_path line in the config.toml.
Once the auth server is up and running, the configured JWK should be available in http://localhost:54321/auth/v1/.well-known/jwks.json

$ ./bin/supabase gen signing-key --help
Securely generate a private JWT signing key for use in the CLI or to import in the dashboard.

Supported algorithms:
	ES256 - ECDSA with P-256 curve and SHA-256 (recommended)
	RS256 - RSA with SHA-256

Usage:
  supabase gen signing-key [flags]

Examples:
  supabase gen signing-key --algorithm RS256
  supabase gen signing-key --algorithm ES256
  supabase gen signing-key --algorithm RS256 --append

Flags:
      --algorithm [ RS256 | ES256 ]   Algorithm for signing key generation. (default ES256)
      --append                        Append new key to existing keys file instead of overwriting.
  -h, --help                          help for signing-key

...

Command output

$ ./bin/supabase gen signing-key --algorithm RS256
/Users/cemalkilic/projects/cli/signing_keys.json
JWT signing keys saved to: /Users/cemalkilic/projects/cli/signing_keys.json
⚠️  IMPORTANT: Add this file to your .gitignore to prevent committing signing keys to version control

To enable JWT signing keys in your project:
1. Add the following to your config.toml file:
   signing_keys_path = "/Users/cemalkilic/projects/cli/signing_keys.json"
2. Restart your local development server:
   supabase start

Run with `--append` flag

$ ./bin/supabase gen signing-key --algorithm RS256 --append
/Users/user/projects/cli/signing_keys.json
JWT signing key appended to: /Users/user/projects/cli/signing_keys.json (now contains 2 keys)
⚠️  IMPORTANT: Add this file to your .gitignore to prevent committing signing keys to version control

To enable JWT signing keys in your project:
1. Add the following to your config.toml file:
   signing_keys_path = "/Users/cemalkilic/projects/cli/signing_keys.json"
2. Restart your local development server:
   supabase start

coveralls · 2025-07-10T19:50:50Z

Pull Request Test Coverage Report for Build 16416756141

Details

94 of 198 (47.47%) changed or added relevant lines in 4 files are covered.
5 unchanged lines in 1 file lost coverage.
Overall coverage decreased (-0.2%) to 55.325%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
internal/start/start.go	3	5	60.0%
cmd/gen.go	0	7	0.0%
internal/utils/misc.go	0	16	0.0%
internal/gen/signingkeys/signingkeys.go	91	170	53.53%

Files with Coverage Reduction	New Missed Lines	%
internal/gen/keys/keys.go	5	12.9%

Totals
Change from base Build 16410144347:	-0.2%
Covered Lines:	6171
Relevant Lines:	11154

💛 - Coveralls

hf

Looks OK to me, however you may want to explore a jwk library if you want.

hf · 2025-07-11T07:58:42Z

Maybe the default output format should be the key, while passing another parameter to give you the config.toml setting?

Reason being this command can be used for people who want to import a private key they control.

hf

LGTM!

sweatybridge · 2025-07-18T09:17:29Z

+		}
+		out = f
+	}
+	jwkArray = append(jwkArray, keyPair.PrivateKey)


@cemalkilic do we need to show or save the public key to user?

I think at this point, no.

sweatybridge · 2025-07-21T06:51:55Z

+
+		// Add JWT keys from file if configured
+		if keysData, err := utils.Config.Auth.GetSigningKeysData(fsys); err == nil && keysData != "" {
+			env = append(env, "GOTRUE_JWT_KEYS="+keysData)


@cemalkilic can we add the jwks parsed from line 148 directly here?

"GOTRUE_JWT_SECRET=" + utils.Config.Auth.JwtSecret.Value, "GOTRUE_JWT_KEYS=" + jwks,

No, that jwks is consumed by the other services (storage, realtime etc) to accept tokens from the third party auth (docs).
Supabase Auth server shouldn't serve the JWKS of the third party auth providers.

logemann · 2025-07-21T16:08:57Z

is there an easy way to track when this will be available as docker gotrue image? Happy to instantly use it ;-)

traviswimer · 2025-07-31T18:35:28Z

@logemann It seems to be working for me after installing the 2.33.8 beta version of the cli.

I'm now also getting an error when trying to use the js client with a "service role key", but JWTs are working well with the JWKs.

marcfrankel · 2025-08-10T00:45:08Z

@traviswimer Did you figure out a solution to the service role key not working? That's blocking me now. I keep getting "JWSError JWSInvalidSignature" errors when using it via the js-client

traviswimer · 2025-08-10T16:42:26Z

@marcfrankel yep, you can generate your own JWT and use it as the service role key, but hopefully Supabase eventually provides a more streamlined solution.

For now anyway, you can use supabase gen signing-key --algorithm ES256 to generate a JWK. Then you need to use a library to generate the JWT using that JWK.

In my case I used a node script with the jose library, so something like this:

import { importJWK, SignJWT } from 'jose';
import jwks from './signing_keys.json';

const jwk = jwks[0];

delete jwk.key_ops;
const privateKey = await importJWK(jwk);

const jwt = await new SignJWT({ role: "service_role" })
	.setProtectedHeader({ alg: "ES256", kid: jwks[0].kid })
	.setIssuedAt()
	.setIssuer("supabase")
	.setAudience("authenticated")
	.setExpirationTime("30d")
	.sign(privateKey);

I'm not sure why, but the key_ops property of the JWK caused an error for me, so I had to delete it to get it to work.

When signing the JWT, you can set the expiration to whatever you like, but the strings used for the other fields are what supabase expects in a service role key.

This is just the solution that worked for me. I have no idea if it is what the Supabase team would recommend, but since these are local JWTs that can't be used in production, I'm not too worried about it.

cemalkilic · 2025-08-12T06:10:57Z

Hey folks, sorry for the inconvenience. Working on the fix now to make it work with secret role keys.

BTW @traviswimer that's a nice approach and the root cause! With current implementation, we sign the anon/service role keys with JWT secret and auth server is failing to validate them as it doesn't know about the JWT secret anymore.

edit: solved in #3969, will be available soon with a version release. thanks for bearing with us!

cwooldridge1 · 2025-08-26T22:39:12Z

On cli v2.39.2 I am getting Error status 400: {"statusCode":"403","error":"Unauthorized","message":""alg" (Algorithm) Header Parameter value not allowed"}
Edit: Fixed by running supabase stop supabase start and then supabase db reset --local

cemalkilic requested a review from a team as a code owner July 10, 2025 19:44

hf approved these changes Jul 11, 2025

View reviewed changes

cemalkilic changed the title ~~feat: add generate-key cmd for generating jwt signing keys~~ feat: support jwt signing keys for local auth Jul 11, 2025

cemalkilic added 3 commits July 11, 2025 12:27

feat: add generate-key cmd for generating jwt signing keys

d421c9b

chore: default formatting as json

19ed885

feat: add jwt_keys env variable to auth if configured

edf8d7e

cemalkilic force-pushed the cemal/add-cmd-generate-jwt-signing-keys branch from e23950b to edf8d7e Compare July 11, 2025 10:28

chore: go generate

f1a6075

sweatybridge reviewed Jul 11, 2025

View reviewed changes

Comment thread cmd/gen.go Outdated

sweatybridge requested changes Jul 11, 2025

View reviewed changes

Comment thread pkg/config/templates/config.toml Outdated

sweatybridge reviewed Jul 11, 2025

View reviewed changes

Comment thread internal/start/start.go Outdated

cemalkilic and others added 5 commits July 11, 2025 13:26

chore: separate block for jwt config

3cfeed9

chore: rename cmd to signing-key

f852ac8

feat: include precomputed fields for rsa key

b43555a

Merge branch 'develop' into cemal/add-cmd-generate-jwt-signing-keys

c05df59

chore: gofmt

0cbcee0

cemalkilic force-pushed the cemal/add-cmd-generate-jwt-signing-keys branch from f6a01d7 to 0cbcee0 Compare July 15, 2025 12:31

hf approved these changes Jul 16, 2025

View reviewed changes

Comment thread cmd/gen.go Outdated

Comment thread cmd/gen.go

cemalkilic and others added 2 commits July 16, 2025 11:41

feat: use file-based approach for signing keys

ae69c22

Merge branch 'develop' into cemal/add-cmd-generate-jwt-signing-keys

abfcdb7

sweatybridge reviewed Jul 16, 2025

View reviewed changes

feat: use file-based approach for JWT signing keys

5823a50

sweatybridge reviewed Jul 18, 2025

View reviewed changes

Comment thread internal/gen/signingkeys/signingkeys.go Outdated

Comment thread internal/gen/signingkeys/signingkeys.go Outdated

Comment thread cmd/gen.go Outdated

Comment thread pkg/config/config.go Outdated

Comment thread internal/gen/signingkeys/signingkeys.go Outdated

chore: address PR comments

344fc1c

sweatybridge reviewed Jul 18, 2025

View reviewed changes

sweatybridge added 2 commits July 18, 2025 17:18

chore: update command short text

7d6368a

fix: unit tests

a4eb2da

sweatybridge reviewed Jul 21, 2025

View reviewed changes

sweatybridge added 5 commits July 21, 2025 15:09

Merge branch 'develop' into cemal/add-cmd-generate-jwt-signing-keys

8e963f7

fix: allow appending to new key

3530b38

chore: confirm before overwriting existing key

bafc175

chore: show suggestion only for stdout

254e601

chore: skip warning if file is already ignored

df6a75f

sweatybridge force-pushed the cemal/add-cmd-generate-jwt-signing-keys branch from 62c58f7 to df6a75f Compare July 21, 2025 10:33

sweatybridge added 2 commits July 21, 2025 20:05

chore: minor refactor

7fe1aa1

chore: add config to test template

a3ec242

sweatybridge approved these changes Jul 21, 2025

View reviewed changes

sweatybridge merged commit 63a8891 into develop Jul 21, 2025
14 checks passed

sweatybridge deleted the cemal/add-cmd-generate-jwt-signing-keys branch July 21, 2025 12:26

github-actions Bot mentioned this pull request Jul 22, 2025

Prod deploy #3896

Merged

github-actions Bot mentioned this pull request Aug 5, 2025

Prod deploy jimkoen/supabase-cli#1

Open

Uh oh!

Conversation

cemalkilic commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of change does this PR introduce?

Steps

Command output

Run with --append flag

Uh oh!

coveralls commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16416756141

Details

💛 - Coveralls

Uh oh!

hf left a comment

Choose a reason for hiding this comment

Uh oh!

hf commented Jul 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sweatybridge Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

cemalkilic Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

sweatybridge Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cemalkilic Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

logemann commented Jul 21, 2025

Uh oh!

traviswimer commented Jul 31, 2025

Uh oh!

marcfrankel commented Aug 10, 2025

Uh oh!

traviswimer commented Aug 10, 2025

Uh oh!

cemalkilic commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cwooldridge1 commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

cemalkilic commented Jul 10, 2025 •

edited

Loading

Run with `--append` flag

coveralls commented Jul 10, 2025 •

edited

Loading

sweatybridge Jul 21, 2025 •

edited

Loading

cemalkilic commented Aug 12, 2025 •

edited

Loading

cwooldridge1 commented Aug 26, 2025 •

edited

Loading