JWKS Auth

JWKS Auth signs JWT assertions using managed RSA keys and publishes the corresponding public keys via an org-scoped JWKS endpoint. The signed JWT is used directly as a Bearer token in your API requests. Keys rotate automatically, and the JWKS endpoint serves both the current and next keys during a configurable grace period to ensure seamless rollover.

How It Works

1. Generate a JWT using the configured claims and the org’s current private key.
2. Sign the JWT with the org’s current private key.
3. Use the signed JWT as Authorization: Bearer <jwt> in the request header.

Step 1: Org-Scoped JWKS Endpoint

Verifiers can fetch public keys from the org-scoped JWKS endpoint. The org is inferred from the first label of the Host header (org alias or mapped subdomain).

• Endpoint: GET /.well-known/jwks.json
• Host: https://{{tenant_name}}.moveworks.com (e.g. https://acme.moveworks.com)
• Success: 200 OK with { "keys": [ JWK, ... ] }
• Not found: 404 when no JWKS config exists for the org
• Bad request: 400 for missing/invalid host or org alias
• Rate limited: 429 when rate limit is exceeded

Example response:

1
{
2
  "keys": [
3
    {
4
      "kty": "RSA",
5
      "kid": "current-key-id",
6
      "n":   "...base64url modulus...",
7
      "e":   "AQAB",
8
      "x5c": ["...base64 DER certificate..."]
9
    },
10
    {
11
      "kty": "RSA",
12
      "kid": "next-key-id",
13
      "n":   "...",
14
      "e":   "AQAB",
15
      "x5c": ["..."]
16
    }
17
  ]
18
}

Step 2: How We Generate and Sign the JWT

• Key type: RSA 2048
• JWK fields: kty, kid, n, e, x5c (self-signed certificate, 1-year TTL)
• KID format: UUID, optionally prefixed when generated
• Claims: iss, sub, aud, iat, exp plus any additional claims
• Headers: Optional custom headers (e.g., typ) can be set

Example (Python) of how the system constructs and signs the JWT using the org’s current private key:

1
import jwt
2
import time
3
4
private_key_pem = secret_store.get("Jwks Auth Private Key")  # referenced by JwksSecret
5
algorithm = "RS256"
6
7
claims = {
8
    "iss": config["Jwks Auth Claims Issuer"],
9
    "iat": int(time.time()),
10
    "exp": int(time.time()) + int(config["Jwks Auth Claims Expiry Seconds"]),
11
    **config.get("Jwks Auth Additional Claims", {}),
12
    **config.addtional_claims
13
}
14
15
if config["Jwks Auth Claims Audience"]:
16
	claims["aud"] = config.audience
17
if config["Jwks Auth Claims Subject"]:
18
	claims["sub"] = config.subject
19
if config["Jwks Auth Claims Scopes"]:
20
	claims["scope"] = ' '.join(config=["JWKS Auth Claim scopes"])
21
22
# The server-managed jwks KID is injected automatically. Don't put another separate kid into header
23
headers = { **config.get("Jwks Auth Headers", {}), 'alg': algorithm, 'kid': config.get("kid") }
24
25
jwt_assertion = jwt.encode(claims, config.private_key, algorithm=algorithm, headers=headers)

Step 3: Use the Signed JWT in API Requests

$
curl -X GET "<https://api.example.com/data>" \\
>
     -H "Authorization: Bearer $JWT_ASSERTION"

Where $JWT_ASSERTION is the signed JWT from Step 2.

Key Management and Rotation

• Storage: A JwksSecret stores a reference to the private key (in the secret store), the JWK JSON, and the kid.
• Publication: The JWKS service serves the union of current and next JWKs for the org at /.well-known/jwks.json.
• Rotation inputs: rotation_interval (days) and rotation_grace_period (hours).
• Grace period: both current and next are served during the grace window; verifiers must accept tokens signed by either kid until the grace window ends.
• System fields: next_jwks (populated automatically), updated_at (last rotation), grade_period_ends_at (end of grace window).

Mermaid timeline illustrating rotation and grace:

Flow overview of key issuance and use:

Configuration Fields

To set this up:

1. Select Jwks Auth from the Auth Config dropdown.

2. Click the Generate JWKS button to generate the public and private key pair.

   

   
   

3. Fill in the required fields:

   Field	Description
   Jwks Auth Rotation Interval	In days; how often to rotate keys.
   Jwks Auth Rotation Grace Period	In hours; both keys are served during grace
   Jwks Auth Claims Expiry Seconds	This sets the exp claim at iat + expiry_seconds
   Jwks Auth Claims Issuer	Sent as iss claim
   Jwks Auth Claims Audience	Sent as aud claim
   Jwks Auth Claims Subject	Sent as sub claim
   Jwks Auth Headers	Optional JWT header claims such as typ.
   Jwks Auth Additional Claims	Optional JWT payload claims like scope, name, jti

   
   

Notes:

• If the grace period is configured as 0, the system adds a small propagation buffer internally.
• The JWKS endpoint rate limits excessive requests and returns 429 when over limit.

Implementation Notes

• JWKS endpoint: /.well-known/jwks.json (serves keys for the org derived from the Host header subdomain).
• Input config: org-scoped JWKS public keys are provided via a reloadable config; the endpoint parses and returns them in the standard JWKS format.
• Key format: RSA 2048 with x5c including a self-signed certificate (1-year TTL).
• Rotation: The platform maintains current and next keys in config and surfaces both during grace to support seamless rollover.

Verification Guidance

• Always select the verification key by the JWT kid header.
• Cache JWKS responses per your policy, but refresh on signature failures or at reasonable intervals.
• During rotation, accept tokens signed with either the current or next kid until the grace period ends.
• If you see 404 from the JWKS endpoint, verify that the org alias is correct and that JWKS is configured for the org.

Troubleshooting

• 400 invalid host or missing org alias: Ensure requests include a Host header like <org-alias>.moveworks.com.
• 404 no JWKS config: The org has no JWKS configured; configure JwksSecret and Jwks Auth first.
• 429 rate limit exceeded: Back off and retry with exponential backoff.
• Parsing errors in keys: Ensure JWK JSON follows spec (kty, kid, n, e, optional x5c).