goma-gateway/docs/middleware/jwt.md

title, layout, parent, nav_order

title	layout	parent	nav_order
JWT Middleware	default	Middleware	5

JWT Middleware

The JWT middleware restricts access to routes, similar to BasicAuth, by authorizing users based on JSON Web Tokens (JWTs).

---

How It Works

1. Authorization Logic
   The middleware determines access based on the HTTP response from an authentication service:

   • 200 (OK): Access is granted.
   • 401 (Unauthorized) or 403 (Forbidden): Access is denied with the corresponding error code.
   • Other Response Codes: Treated as errors.

2. Backend Dependency
   The middleware relies on a backend authentication service to validate requests.

3. Nginx Inspiration
   Its behavior is comparable to ngx_http_auth_request_module in Nginx.

Here's an example Nginx configuration:

   location /private/ {
       auth_request /auth;
       ...
   }

   location = /auth {
       proxy_pass ...;
       proxy_pass_request_body off;
       proxy_set_header Content-Length "";
       proxy_set_header X-Original-URI $request_uri;
   }

Header and Parameter Injection

The middleware supports extracting headers from the authentication response and injecting them into the next request’s headers or parameters.

1. Injecting Headers Add headers to the next request after a successful authorization:

headers:
  # Key: Auth request header key | Value: Next request header key
  userId: X-Auth-UserId
  userCountryId: X-Auth-UserCountryId

2. Injecting Parameters

Add parameters to the next request from the authentication response headers:

params:
  # Key: Auth request header key | Value: Next request parameter key
  userId: userId
  userCountryId: countryId

Example Configuration

Below is a complete example of JWT middleware configuration:

middlewares:
  - name: jwt-auth
    type: jwt
    # Paths to protect
    paths:
      - /protected-access
      - /example-of-jwt
      # - /* for wildcard paths
    rule:
      # URL of the backend authentication service
      url: https://www.example.com/auth/access
      # Headers required in the incoming request
      requiredHeaders:
        - Authorization
      # Headers to include in the next request
      headers:
        userId: X-Auth-UserId
        userCountryId: X-Auth-UserCountryId
      # Parameters to include in the next request
      params:
        userId: userId
        userCountryId: countryId

Notes

• Use this middleware to secure endpoints by delegating authorization to a backend service.
• Properly configure the rule section to match your authentication service requirements.