jwe-decrypt

Decrypts a JWE token from the request and forwards its payload.

Category AuthenticationAdd it to Route, Service, Global rule, Plugin configEngine plugin jwe-decryptPriority 2509Needs a Consumer with a jwe-decrypt Credential

What it does

jwe-decrypt opens an encrypted token, a JWE, that the client sends in the request header named under Header, and hands its plain content to the route's backend in the header named under Forward header. The decryption key lives on a consumer, as a jwe-decrypt credential. Its Key is the key ID the token names in its own header, and its Secret the key itself.

A request whose token a credential decrypts reaches the backend with the plain token in X-Decoded-Token, in the examples. With Strict on, a request without a token is answered 403 with missing JWE token in request. Authentication shows how consumers and credentials fit together.

When to use it

• A sign-in service seals its tokens so that nobody on the way reads their content, and the backend expects the plain token.
• The mobile app seals its tokens with a key of its own, named mobile-app-2026, and every other client with a key of its own as well.
• A route that takes requests without a token too, as they came, with Strict off.

Not for signed tokens the gateway checks, not encrypted ones — see jwt-auth (Authenticates consumers with a JSON Web Token they present), tokens issued by an OpenID Connect identity provider — see openid-connect (Authenticates users against an OpenID Connect provider) or a fixed API key a client sends as it is — see key-auth (Authenticates consumers with an API key sent in a header or query parameter).

Set it up

Decrypt the bearer token and hand the plain token to the upstream

Leave Header at Authorization, set Forward header to X-Decoded-Token and turn on Strict.

jwe-decrypt · as the console saves it

{
  "header": "Authorization",
  "forward_header": "X-Decoded-Token",
  "strict": true
}

More scenarios

Give a consumer a key id and the decryption key its tokens are sealed withcredential

The secret is exactly 32 characters, or 32 bytes once base64 decoded.

Set Key to mobile-app-2026, set Secret to <secret> and turn off Base64 encoded.

jwe-decrypt credential · as the console saves it

{
  "key": "mobile-app-2026",
  "secret": "<secret>",
  "is_base64_encoded": false
}

Things to know

• Forward header — With X-Decoded-Token, the backend receives the decrypted token in that header and answers 200.
• Forward header — An empty name is saved without a warning, and every request that carries a token then answers 400.
• Strict — On, a request without a token is answered 403 with missing JWE token in request and does not reach the backend.
• Strict — Off, a request without a token is sent upstream as it came. On, it is answered 403.
• Header — An empty header name is refused when you save.
• Key — A token whose header names mobile-app-2026 is decrypted with the secret of the credential that carries that key ID, and passes.
• Key — Though not a secret, it is sealed with the secret, so readers without the permission see it masked.
• Secret — Must be 32 characters, or the base64url of 32 bytes with Base64 encoded on. Any other length is saved without a warning, and every token then answers 500.
• Secret — A credential without a secret is refused when you save.
• AdviceTurn Strict on for a route that should take only encrypted tokens, so that a request without one never reaches the backend.

Settings

The fields as the console shows them, section by section.

HeaderheaderstringRequireddefault Authorization

The request header the token arrives in, such as Authorization. The token may stand alone or follow Bearer.

at least 1 character

Forward headerforward_headerstringRequireddefault Authorization

Strictstrictbooleandefault true

Credential

What each consumer's credential for jwe-decrypt carries.

KeykeystringRequired

The key ID (kid) clients put in the token's header, such as alice-2026. Stored on the engine and shown only to roles that manage this object.

SecretsecretstringRequired

The 32-character key that decrypts this consumer's tokens. Stored on the engine and shown only to roles that manage this object.

Base64 encodedis_base64_encodedboolean

On, the secret above is read as base64.

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.