DocumentationAccess ControlDeployment

Gateway Integration

View as Markdown

In production, a gateway (reverse proxy, ingress controller, or service mesh) often sits in front of the NeMo Platform. This page explains how authorization works with and without gateway-level auth, what headers the gateway must set, and which paths skip authorization.

For the security architecture, see Security Model.

Overview

NeMo Platform’s authorization middleware runs inside each service. Every request is evaluated there unless auth is disabled or the request matches a bypass path. Optionally, the gateway can perform the authorization check (e.g., via Envoy ext_authz) and forward the request with a special header so that services trust the gateway’s decision and do not call the PDP again. That reduces latency and centralizes auth at the edge.

Two Authorization Models

Service-Level Auth (Default)

  • The gateway forwards requests unchanged (aside from routing/TLS).
  • Each service’s middleware validates the token (or principal headers) and calls the PDP.
  • No gateway auth configuration required. Easiest to set up.

Gateway-Level Auth

  • The gateway calls the PDP (e.g., via Envoy ext_authz) before forwarding.
  • If the PDP allows the request, the gateway adds headers and forwards; otherwise it returns 403.
  • Services see x-nmp-authorized: true and the principal headers, and skip their own PDP call.
  • Benefit: One auth check per request at the edge; lower latency and fewer PDP calls.

To use gateway-level auth you must configure your gateway to call the NeMo Platform PDP and set the headers described below on allowed requests.

Security Requirement: Your ingress/gateway must strip the following headers from all incoming external requests before forwarding to NeMo Platform:

  • X-NMP-Principal-Id, X-NMP-Principal-Email, X-NMP-Principal-Groups, X-NMP-Principal-On-Behalf-Of
  • X-NMP-Authorized, X-NMP-Scopes

If external clients can set these headers, they can forge any identity or bypass authorization entirely. The gateway should also block external access to /internal/* paths (used for service-to-service communication).

Required Headers (Gateway-Level Auth)

When the gateway has already authorized the request, it must set:

HeaderDescription
X-NMP-AuthorizedMust be true so services trust the gateway’s decision and skip PDP.
X-NMP-Principal-IdPrincipal identifier (e.g., user ID or email). Required.
X-NMP-Principal-EmailUser email (optional but recommended).
X-NMP-Principal-GroupsComma-separated group names (optional).

Header names are case-insensitive; services normalize them.

Bypass Paths

The following are not subject to authorization checks; they are always allowed:

  • Health and readiness: /health, /healthz, /ready, /readyz, /health/live, /health/ready, /metrics
  • Discovery: /apis/auth/discovery (for CLI/SDK OIDC discovery)
  • PDP endpoints: Paths under /apis/auth/v2/authz/ are restricted to service principals only. The middleware rejects external and regular-user requests automatically.
  • Studio: Paths under /studio (the Studio UI handles its own OIDC login)

Configure the gateway so these paths are not sent to the PDP (or are always allowed) when using gateway-level auth.

Gateway Configuration Examples

Envoy ext_authz

Replace placeholder values before applying this configuration.

1http_filters:
2  - name: envoy.filters.http.jwt_authn
3    typed_config:
4      "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication
5      providers:
6        <OIDC_PROVIDER_NAME>:
7          issuer: "<OIDC_ISSUER_URL>"
8          remote_jwks:
9            http_uri:
10              uri: "<OIDC_JWKS_URI>"
11              cluster: <OIDC_JWKS_CLUSTER>
12              timeout: 5s
13            cache_duration: 600s
14          claim_to_headers:
15            - header_name: "X-NMP-Principal-Id"
16              claim_name: "sub"
17            - header_name: "X-NMP-Principal-Email"
18              claim_name: "email"
19      rules:
20        - match:
21            prefix: "/"
22          requires:
23            provider_name: "<OIDC_PROVIDER_NAME>"
24  - name: envoy.filters.http.ext_authz
25    typed_config:
26      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
27      grpc_service:
28        envoy_grpc:
29          cluster_name: <OPA_PDP_GRPC_CLUSTER>
30        transport_api_version: V3
31      failure_mode_allow: false
32  - name: envoy.filters.http.router
33    typed_config:
34      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

Header Stripping

Configure your gateway to remove NeMo Platform auth headers from incoming external requests. This prevents clients from forging identities.

Add request_headers_to_remove to your route configuration:

1route_config:
2  virtual_hosts:
3    - name: nmp_service
4      domains: ["*"]
5      request_headers_to_remove:
6        - "x-nmp-principal-id"
7        - "x-nmp-principal-email"
8        - "x-nmp-principal-groups"
9        - "x-nmp-principal-on-behalf-of"
10        - "x-nmp-scopes"
11        - "x-nmp-authorized"
12      routes:
13        - match: { prefix: "/" }
14          route: { cluster: nmp_backend }

Testing Gateway Auth

After configuring gateway-level auth, verify:

  1. Headers are set correctly — Make a request through the gateway and check that X-NMP-Authorized and X-NMP-Principal-Id are present on the service side.
  2. Headers are stripped from external requests — Try sending X-NMP-Authorized: true from outside; verify it is stripped by the gateway.