Control access or route traffic based on verified claims in a JSON web token (JWT).

About JWTs

A JSON Web Token (JWT) is an open standard for securely sharing information between a client and your apps. JWTs are commonly used to support stateless, simple, scalable, and interoperable authentication and authorization flows.

For more information, refer to the following sources:

Common use cases

JSON Web Tokens (JWT) are commonly used to offload authentication and authorization code from your apps.

Keep in mind that JWT data is encoded but not encrypted. As such, consider using JWT policies with no personally identifiable information (PII) or sensitive data, and only on HTTPS traffic.

JWT structure

A JWT has three parts: header, payload, and signature. These three parts are base64 encoded, combined, and separated by the dot character (.) to form the final token. To review and decode JWTs, you can use a tool such as the jwt.io debugger. JWT parts are structured as follows:

Phase considerations for JWTs

You can apply a JWT policy before or after external authentication and authorization of a request. Where you place the JWT policy depends on many considerations that are unique to your environment, as compared in the following table. For more information about setting phases and priority, see the Phase API docs.

Consideration Before (Pre-AuthZ) After (Post-AuthZ)
Token source The JWT comes from a trusted source that the client already has before the request reaches the gateway. For example, the client might already be within your environment. The JWT comes from an external authentication provider, such as OIDC or SSO.
Authentication You want to filter out requests that do not already have a JWT. Or, you require external authentication only for requests with certain information that is within the JWT. You want to require authentication for all requests.
Security requirements You must validate a request's JWT claims before external authentication, such as if your apps receive requests from many untrusted or insecure sources. You must get a JWT from a certain OIDC provider before the request is validated.
Performance You want to filter out requests as soon as possibled based on the JWT. The JWT might have all the information to make authentication decisions and comes from a trusted source. This way, you do not need to perform an additional network hop to the external authentication provider. The JWT filtering happens within the gateway proxy. You might configure a request to authenticate with an external provider first. Aftewards, you use JWT validation to reduce the number of times that a request is sent for external authentication.
Filter order with other policies The JWT information is not needed for policies that happen before it in the pre-AuthZ filter order, such as transformation or rate limiting. The JWT information is used in complex authentication flows with policies that happen after it in the post-AuthZ filter order. For example, you might set up a complex flow to authenticate, extract, transform, and rate limit based on an appended claim to the JWT.

Route and destination selectors

You can apply a Gloo JwtPolicy to routes or destinations. For more information about how policy selectors works, see the Apply policies concept. Keep in mind that you cannot apply multiple JWT policies to the same route or destination.

Choose which selector to use

The type of selector that you use depends on what you want to secure with the JWT policy.

Because you cannot have multiple JWT policies apply to the same route or destination, you can also use both selectors in your JWT policies. This way, the JWT policy applies to all of the selected routes and destinations.

The following table describes different scenarios for configuring a JWT policy that uses both route and destination selectors, and the resulting selection in a workspace.

For example, consider Scenario 1 in the following table. You set the applyToRoutes selector either to {} (all routes) or omit it. You omit the applyToDestinations selector. As a result, the JWT policy applies to all of the routes in the workspace, but to none of the destinations. If the route table for the workspace uses only a virtual gateway, then all of its routes are ingress routes. As such, only ingress traffic is secured by the JWT policy. Any east-west service mesh traffic is not secured by the JWT policy.

Scenario applyToRoutes applyToDestinations Selected routes Selected destinations
1 {} or nil nil ✅ ALL ❌ NONE
2 {} {} ✅ ALL ✅ ALL
3 {} some value ✅ ALL 🟡 SOME
4 some value nil 🟡 SOME ❌ NONE
5 some value {} 🟡 SOME ✅ ALL
6 some value some value 🟡 SOME 🟡 SOME
7 nil some value ❌ NONE 🟡 SOME
8 nil {} ❌ NONE ✅ ALL

Routes for ingress or service mesh traffic

To apply policies to routes, you need to define the routes in a route table. The route table can use different gateway proxies to direct traffic, depending on how you configure the route table. For more information about route tables, see the Traffic management concept docs.

You can also use both types of virtual gateway and workload selectors in a route table. The following table describes different scenarios for configuring a route table with virtual gateway or workload selectors, and the resulting selection in a workspace.

For example, consider Scenario 1 in the following table. You define at least one virtual gateway but no workload selectors in a route table. As a result, at least one virtual gateway is selected, but no workload sidecar proxies are selected. If you use a JWT policy with an applyToRoutes selector, then the policy only protects ingress traffic through the selected virtual gateway. It does not apply to any routes for east-west service mesh traffic, because no workloads are selected.

Scenario virtualGateway (ingress) workloadSelectors (service mesh) Selected virtual gateways Selected workloads
1 some value nil or [] 🟡 SOME ❌ NONE
2 some value [{}] 🟡 SOME ✅ ALL
3 some value some value 🟡 SOME 🟡 SOME
4 nil nil or [] ❌ NONE ✅ ALL

JWTs in Gloo Platform

With Gloo policies, you can restrict and route traffic based on information that you find in the JWT. Routing based on user identity in the JWT is more secure than unauthenticated HTTP requests from a path or header.

You can use JWT policies in combination with the gatewayDefaultDenyAllHTTPRequests feature gate. This way, Gloo Mesh Gateway denies requests to your HTTP routes by default. For more information, see /gloo-gateway/latest/routing/deny-traffic-default/ .

This JWT section contains guides for the Gloo Mesh Gateway product. These guides have examples for applying JWT policies to ingress routes with the applyToRoutes selector. For examples that use the applyToDestinations selector or the applyToRoutes selector on service mesh routes for east-west use cases, see the Gloo Mesh Enterprise docs.