Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Security and mTLS

Request Authentication and JWTs

Validate end-user JSON Web Tokens in the mesh with RequestAuthentication and require them with AuthorizationPolicy, including claims-based rules and common mistakes.

mTLS authenticates workloads. But often the real question is about the end user: which person or app, behind this request, got here? Web and mobile clients usually carry that answer in a JSON Web Token (JWT) issued by an identity provider. Istio can validate tokens in the proxy so your services do not each reimplement it, and then use their claims in authorization rules.

YAML is read-only. The Python stand-ins decode and check token structure and claims only; they do not verify real signatures, so never use them for security.

The two-step pattern

Istio splits the job into two resources, and understanding the split avoids the most common mistake:

  1. RequestAuthentication says how to validate a token if one is present: which issuer, which keys.
  2. AuthorizationPolicy says whether a token is required, and what its claims must contain.

A RequestAuthentication alone does not reject requests without a token. It rejects requests with an invalid token (bad signature, expired, wrong issuer, wrong audience), and accepts requests with no token at all. To require a valid token you add an authorization policy.

YAML
apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-auth
  namespace: shop
spec:
  selector:
    matchLabels:
      app: web
  jwtRules:
    - issuer: "https://login.example.com/"
      jwksUri: "https://login.example.com/.well-known/jwks.json"
      audiences:
        - "shop-web"
      forwardOriginalToken: true
  • issuer must equal the token's iss claim.
  • jwksUri is where istiod fetches the public keys (JWKS); alternatively embed them with jwks.
  • audiences limits accepted aud values.
  • forwardOriginalToken passes the token on to the app so it can read claims, too.
  • fromHeaders and fromParams change where the token is read from; the default is the Authorization: Bearer ... header.

Now require it:

YAML
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: require-jwt
  namespace: shop
spec:
  selector:
    matchLabels:
      app: web
  action: ALLOW
  rules:
    - from:
        - source:
            requestPrincipals: ["https://login.example.com/*"]
      when:
        - key: request.auth.claims[groups]
          values: ["shoppers"]

requestPrincipals has the form issuer/subject. The wildcard here means "any subject from this issuer"; a request without a valid token has an empty request principal and cannot match, so it gets 403. The when clause demands that the groups claim contains shoppers.

You may combine the two security layers: principals for the calling workload (mTLS) and requestPrincipals for the user. At the edge gateway, the token check usually lives on the gateway; behind it, workloads may trust the gateway's identity and forward the token for claim checks.

Error responses

  • Invalid token: 401 Jwt verification fails (or Jwt is expired).
  • Missing token with a requiring policy: 403 RBAC: access denied.

This difference is a quick diagnostic: 401 means a token was presented and rejected; 403 means the token was fine (or absent) but policy denied.

Common mistakes

  • Expecting RequestAuthentication to require tokens. It does not.
  • issuer not matching iss exactly (a trailing slash makes it different).
  • Clock skew: a token with exp in the past on the proxy's clock is rejected; check node time.
  • JWKS unreachable: istiod must be able to fetch jwksUri. A failure may reject all tokens.
  • Putting secrets in claims. A JWT is signed, not encrypted; anyone can read the payload.

Stand-ins

Python Stand-in: look inside a token (no signature check)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: 401 versus 403

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A RequestAuthentication exists, and a request arrives with no token. What happens (no other policies)?

    To require a token you also need an AuthorizationPolicy, for example on requestPrincipals.
  2. 2. What does a 401 from the proxy usually mean?

    401 is an authentication failure; 403 is an authorization decision.
  3. 3. Which field of AuthorizationPolicy matches the end user's identity from a JWT?

    requestPrincipals uses the form issuer/subject; principals is the workload identity from mTLS.
  4. 4. Why shouldn't you place secrets in JWT claims?

    Signing protects integrity, not confidentiality.

Summary

  • RequestAuthentication validates tokens (issuer, keys, audience) but does not require them.
  • Pair it with an AuthorizationPolicy on requestPrincipals and request.auth.claims to enforce.
  • 401 means a presented token failed; 403 means policy denied.
  • Combine workload identity (mTLS principals) with end-user identity (JWT) for layered rules.
  • Watch issuer strings, clock skew and JWKS reachability.

Next: Istio Metrics and Prometheus: The Golden Signals for Free