Navigation :

JWT

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:

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.

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:

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.
- 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.

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.

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.

The guides in this JWT section provide several examples for configuring JWT policies.

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.

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

You might also use JWT policies in combination with other Gloo resources, such as the following:

Other policies: With a JWT policy, you can extract claims from the payload and add them as headers to the request. Then, you can use a transformation policy to customize these headers.
External authentication: Your external auth provider authenticates users and might provide a JWT back to store client-store. Then, you can use JWT policies to enforce access or route traffic based on claims in the JWT.
External services: You might run a JWT provider outside your Gloo environment, such as Auth0 for JSON Web Key Set (JWKS) key rotation or an OIDC provider. You can create an external endpoint and external service for the JWT provider, and then refer to this provider in the JWT policy.