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:

• RFC 7519, JWT specification
• Auth0 overview about JWT
• Gloo JWT policy API docs
• Istio docs for JWT tokens and JWT claim-based routing

Common use cases

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

• Authentication: Instead of storing user session information server-side which can lead to scalability issues, you set up a JWT issuer, such as an OpenID Connect (OIDC) or Single Sign-on (SSO) provider. After a user authenticates, the provider returns a JWT in the response that is stored client-side. Subsequent requests from the client include the JWT, which is faster to verify than performing the entire authentication and authorization process again.
• Authorization: JWTs can have custom claims that can define a user's scope, role, or other permissions. You can use these claims in combination with other policies to enfore fine-grained access control to your apps. By including the claim information within the JWT, the authorization process can happen faster and more scalably.
• Secure information exchange: Because the token is in JSON format, many otherwise incompatible systems and services can use the token to exchange information. The authentication and authorization features built into the token help these systems validate and trust the information.

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:

• A header with metadata, such as the signing algorithm.
• A payload of user information or “claims” that provide identity information, such as the following common claims:
  • The seven reserved claims per the RFC 7519 spec. The most common are:
    • iss: The entity that issued the token.
    • sub: The subject of the token, usually a user ID.
    • aud: The audience the token is issued for, important for security purposes so that the token is not used for other purposes.
  • Additional registered claims per the OpenID Connect Core to encourage interoperability, such as email, scope, or client_id. For more information, see IANA JSON Web Token Claims.
  • Nested claims are supported in the key name when you also include a nestedClaimDelimiter, such as a period (.). Then, JWTs that match the value you set for the child nested claim are allowed. For an example, see Nested claims.
  • Additional custom claims that you or your OIDC provider create. For an example, see the Auth0 docs.
• A signature that signs the header and payload

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.

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.

• applyToDestinations: Secure all traffic that goes to the selected destinations. This way, the destinations are protected by the same JWT policy no matter how the traffic gets routed.
• applyToRoutes: Secure traffic along the specified route paths. This way, you have more flexibility in how a destination is protected. For example, you might have several external and internal routes that go to the same backing destination. To secure these routes with different JWT policies, you can use applyToRoutes instead of applyToDestinations.

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.

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.

• For ingress traffic from external users: Create a route table that uses a virtual gateway. Then, configure the routes that can accept ingress requests. In the JWT policy, you use the same label of these routes in the applyToRoutes selector. Note that to apply policy to ingress routes, you must have a Gloo Mesh Gateway license.
• For east-west service mesh traffic from internal users: Create a route table that uses workloadSelectors to select the sidecar proxies of the destinations that you want to be able to send outbound requests through the route table. Then, configure the routes that can accept these east-west service mesh requests. The host to send requests to can be defined either in the route table or in the virtual destination that backs the routes. In the JWT policy, you use the same label of these routes in the applyToRoutes selector. Note that to apply policy to service mesh routes, you must have a Gloo Mesh Enterprise license.

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.

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.

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.

• Basic JWT example: Secure access to routes with a basic JWT example.

• Multiple JWT providers: Allow JWT credentials from multiple providers.

• Multiple JWT policies: Enforce gateway- or route-based JWT authentication by using multiple policies.

• JWT claim- and scope-based auth: Authorize requests based on claims or scopes in a JWT.

• JWT with external auth and transformation policies: Use JWT, external auth, and transformation policies together to secure access to your routes.

• More JWT examples: Review JWT policy configuration examples for other use cases.