Authenticating JWT Against the OPA Service

✅

Starting from OpenLegacy Hub Version 3.0.32 and OpenLegacy Core Version 5.1.14+

OpenLegacy supports two integration models for JWT-based request authorization. The platform can validate the JWT before forwarding the request, or it can pass the token to the customer's Open Policy Agent (OPA) service, where JWT verification and policy evaluation are performed.

Delegating Validation to OPA

When a customer prefers OPA to perform JWT validation, OpenLegacy can be configured to forward the incoming bearer token to the external OPA service. This configuration requires the following parameters:

• OPA URL: The base URL of the customer's OPA service.
• Decision Path: The specific OPA policy decision endpoint that OpenLegacy invokes for authorization.

In this model, OpenLegacy acts as the policy enforcement point and submits request context to OPA for evaluation. OPA is expected to validate the JWT, inspect the request attributes, and return an authorization decision.

📘

Supported Environment Variables

• JWT_VALIDATION_MODE - BUILT_IN or OPA
• OPA_URL - OPA base URL
• OPA_DECISION_PATH- Decision path
• OPA_TIMEOUT_MS - Timeout in ms (default 2000)

Request/Response Format

The OpenLegacy Flow Engine sends the authorization input to OPA in the following structure:

  {
    "input": {
      "encoded_jwt": "<raw bearer token, the part after 'Bearer '>",
      "method": "GET",
      "path": "/get-all-accounts",
      "headers": {
        "authorization": [
          "Bearer x.y.z"
        ],
        "accept": [
          "application/json"
        ]
      }
    }
  }

Field Description:

• encoded_jwt: The raw JWT value extracted from the Authorization header, without the Bearer prefix.
• method: The HTTP method of the inbound request.
• path: The request path being evaluated.
• headers: The complete inbound request headers as received by the Flow Engine.

Expected Response
OPA should return a JSON response containing the authorization result in the following format:

{
  "result": {
    "allow": true
  }
}

If result.allow is true, the request is authorized and processing may continue. If result.allow is false, OpenLegacy should treat the request as denied according to the configured security behavior.

Operational Notes

This approach is appropriate when the customer wants JWT trust and authorization logic to be centralized in their OPA environment. It also allows customers to apply their own token verification rules, claim inspection logic, and policy decisions without requiring OpenLegacy to manage JWT validation internally.