Signet
Sign in

Guide

ECDH for encrypted return

Optional hardening: instead of putting a raw JWT in the browser query string, the client generates an ephemeral ECDH key pair and sends the public key with login. The server derives a shared secret, encrypts the session token payload, and returns ciphertext the browser decrypts locally—reducing exposure to shoulder-surfing, referrer leaks, and intermediate proxies that log full URLs.

Standard redirect flow without ECDH remains supported. When you are ready to exercise the full OAuth-shaped path, use OAuth Playground alongside the /ecdh key tool.

When it helps

  • Callbacks land on shared or less-trusted devices where URL history matters
  • You want defense-in-depth on top of HTTPS and short-lived tokens
  • You already run the OAuth login form that negotiates client keys (same mechanics as /login with ECDH enabled)

Generate & store

  1. Open /ecdh and generate a server key pair (PEM)
  2. Set ECDH_SERVER_PRIVATE_KEY to the server private PEM. In env files, keep newlines escaped or quoted so the value parses as one line—your platform's secret UI usually handles multiline PEM cleanly.
  3. Optional ECDH_SERVER_PUBLIC_KEY for local debugging only; production browsers should fetch the current public key from /api/oauth/public-key so rotation can be centralized
Open ECDH tool

Runtime flow

  1. Browser creates an ephemeral ECDH key pair for the login attempt
  2. Client public key is attached to the login (or OAuth) request alongside username, password, and second factor
  3. Server validates credentials, derives a shared secret from its static private key and the client public key, then encrypts the issued session material
  4. Response carries encrypted payload; only the browser holding the ephemeral private key can decrypt and obtain the JWT

Key rotation and overlap windows are described under Advanced in Environment variables when you enable KV-backed rotation.

Operations

  • Never commit the server private key; inject via your host secret manager
  • Public keys alone cannot decrypt past traffic without also capturing ciphertext and breaking ECDH
  • Plan rotation: provision a new pair, update env, deploy, then retire the old private key after clients have picked up the new public key
ECDH Setup - Getting Started