ParseJwtToHeader plug-in - Alibaba Cloud Service Mesh - Alibaba Cloud Documentation Center

The ParseJwtToHeader plug-in extracts fields from a JSON Web Token (JWT) payload at the ingress gateway and forwards them as HTTP request headers to upstream services. Use this plug-in when backend services need user identity information from the JWT, such as a username or role.

Important

For ASM 1.24 and later, RequestAuthentication supports extracting JWT payloads and adding them to request headers. We recommend that you use RequestAuthentication to process the relevant request headers on ASM 1.24+.

Prerequisites

Before you begin, make sure that you have:

An ASM instance with an ingress gateway deployed
A JWT-based identity authentication or authorization policy configured at the ingress gateway
A test environment set up by completing steps 1 through 4 in Perform JWT request authentication for an ingress gateway in ASM

How it works

A client sends a request with a JWT Bearer token to the ingress gateway.
The plug-in extracts the fields specified in field_mapping from the JWT payload.
The extracted values are added as request headers before the request is forwarded upstream.

Note

Each key in field_mapping must exist in the JWT payload. Otherwise, this plug-in will not take effect.

Configuration fields

Field	Type	Required	Default	Description
`issuer`	string	Yes	-	The JWT issuer. Must match the `issuer` field in your request authentication configuration.
`field_mapping`	string map	No	`{}`	Maps JWT payload field names (keys) to request header names (values). For example, `name: x-custom-user` extracts the `name` field from the JWT payload and forwards it as the `x-custom-user` header.

Scope requirement

Set Plugin Effective Scope to Gateway Scope and select the target gateway (for example, ingressgateway). This plug-in operates at gateway scope only.

Configuration example

This example extracts the name field from the JWT payload and forwards it as the x-custom-user header:

issuer: testing@asm.test.io
field_mapping:
  name: x-custom-user

Save this configuration, then turn on the Plugin Switch to activate the plug-in.

Verify the result

Open the JWT tool and create a payload that includes the field defined in field_mapping. Keep the remaining fields consistent with step 4 of the prerequisite guide. Example payload:
```
   {
     "iss": "testing@asm.test.io",
     "name": "asm_test",
     "admin": true,
     "iat": 1516239022
   }
```
Export the generated JWT token to the $TOKEN variable and send a request to the gateway:
```
   curl -H "Authorization: Bearer $TOKEN" http://<your-asm-gateway-address>/headers
```
Replace the following placeholder with your actual value:
Placeholder Description Example
<your-asm-gateway-address> The public IP address or domain of your ASM ingress gateway 120.26.XX.XX

Placeholder	Description	Example
`<your-asm-gateway-address>`	The public IP address or domain of your ASM ingress gateway	`120.26.XX.XX`

Check that the response contains the mapped header. Expected output:

   {
     "headers": {
       "Accept": "*/*",
       "Host": "120.26.**.**",
       "User-Agent": "curl/7.79.1",
       "X-Custom-User": "asm_test",
       "X-Envoy-Attempt-Count": "1",
       "X-Envoy-Internal": "true",
       "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/default/sa/httpbin;Hash=***;Subject=\"\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
     }
   }

The X-Custom-User: asm_test header confirms that the plug-in extracted the name claim and forwarded it.

Note

httpbin capitalizes the first letter of header names in its response. The actual header sent to upstream services matches your configuration exactly (for example, x-custom-user).

What's next

To extract JWT payloads without a plug-in (ASM 1.24+), see RequestAuthentication.
To configure JWT authentication at the ingress gateway, see Perform JWT request authentication for an ingress gateway in ASM.