From 1ae8180527e3b3516e6006bb0d183d0984f24fb0 Mon Sep 17 00:00:00 2001 From: Alex Fenlon Date: Wed, 8 Apr 2026 16:21:56 +0100 Subject: [PATCH] feat: Add ExternalAuth Policy for VirtualServer & Ingress --- content/nic/configuration/policy-resource.md | 67 ++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index 508d5a825..388f644a0 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -47,6 +47,7 @@ spec: |``waf`` | The WAF policy configures WAF and log configuration policies for [NGINX AppProtect]({{< ref "/nic/integrations/app-protect-waf/configuration.md" >}}) | [WAF](#waf) | Yes | Yes | |``cache`` | The cache policy configures proxy caching for serving cached content. | [cache](#cache) | Yes | No | |``cors`` | The CORS policy configures Cross-Origin Resource Sharing headers. | [cors](#cors) | Yes | Yes | +|``externalAuth`` | The External Auth policy configures NGINX to authenticate client requests using an external authentication server. | [externalAuth](#externalauth) | Yes | Yes | {{% /table %}} @@ -696,6 +697,72 @@ policies: In this example NGINX Ingress Controller will use the configuration from the first policy reference `egress-mtls-policy-one`, and ignores `egress-mtls-policy-two`. +### ExternalAuth + +The ExternalAuth policy configures NGINX to authenticate client requests using an external authentication server. You can use this policy with services such as [oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) or any custom authentication service that supports the `auth_request` pattern. + +When a client sends a request, NGINX makes an internal subrequest to the external authentication service. If the service returns a `2xx` response, the original request is forwarded to the upstream. If it returns `401` or `403`, access is denied. If `authSigninURI` is configured, unauthenticated clients are redirected to a sign-in page. + +For example, the following policy configures external authentication using an HTTP Basic Auth backend service: + +```yaml +externalAuth: + authURI: "/auth" + authServiceName: "default/basic-auth-svc" +``` + +The following policy uses OAuth2 Proxy with a sign-in redirect: + +```yaml +externalAuth: + authURI: "/oauth2/auth" + authSigninURI: "/oauth2/signin" + authServiceName: "default/oauth2-proxy-svc" + sslEnabled: true + sslVerify: true + sslVerifyDepth: 2 + sniName: "external-auth-tls" + trustedCertSecret: "external-auth-ca-secret" +``` + +An example of an ExternalAuth policy for VirtualServer resources is available in our GitHub repository for [basic auth](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/custom-resources/external-auth) and [OAuth2 with basic auth](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/custom-resources/external-auth-oauth2). Examples for Ingress resources are also available for [basic auth](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/ingress-resources/external-auth) and [OAuth2 with basic auth using Mergeable Ingresses](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/ingress-resources/external-auth-mergeable). + +{{% table %}} + +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``authURI`` | The URI of the external authentication server. NGINX sends an internal subrequest to this URI to verify the client. Must start with ``/``. For example, ``/auth`` or ``/oauth2/auth``. | ``string`` | Yes | +|``authServiceName`` | The name of the Kubernetes service for the external authentication server. Can include an optional namespace prefix in the format ``/``. For example, ``basic-auth-svc`` or ``auth-namespace/auth-service``. If no namespace is specified, the namespace of the Policy resource is used. | ``string`` | Yes | +|``authServicePorts`` | The ports of the Kubernetes service to which authentication requests are sent. If not specified, the first port from the service definition is used. | ``[]int`` | No | +|``authSigninURI`` | The URI to redirect unauthenticated clients to for sign-in. Used when the external authentication server requires redirection, such as with OAuth2 Proxy. Must start with ``/``. For example, ``/oauth2/signin``. | ``string`` | No | +|``authSnippets`` | Custom NGINX configuration snippets to add to the external authentication location block. For example, you can add extra headers or parameters for the ``auth_request`` module. The content must be valid NGINX configuration. Requires the [``-enable-snippets``]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-snippets" >}}) command-line argument. | ``string`` | No | +|``authSigninRedirectBasePath`` | The base path for the NGINX location block that handles sign-in redirect requests from the external authentication server. For example, OAuth2 Proxy expects ``/oauth2``. Defaults to ``/oauth2`` if not specified. | ``string`` | No | +|``sslEnabled`` | Enables HTTPS when proxying requests to the external authentication server. The default is ``false``. | ``bool`` | No | +|``sslVerify`` | Enables verification of the external authentication server's SSL certificate. The default is ``false``. | ``bool`` | No | +|``sslVerifyDepth`` | Sets the verification depth in the external authentication server certificates chain. The default is ``1``. | ``int`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate for external authentication server certificate verification. Can include an optional namespace prefix as ``/``. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored under the key ``ca.crt``. | ``string`` | No | +|``sniName`` | The server name used for SNI and certificate verification when connecting to the external authentication server over TLS. If not specified, defaults to ``..svc`` derived from ``authServiceName``. | ``string`` | No | + +{{% /table %}} + +#### ExternalAuth Merging Behavior + +A VirtualServer, VirtualServerRoute, Ingress, or Mergeable Ingress can reference only one ExternalAuth policy per route. Every subsequent reference will be ignored. This means you cannot combine different types of external authentication on the same route. For example, you cannot apply both an OAuth2 policy and a basic auth policy to the same route. + +```yaml +policies: +- name: external-auth-policy-one +- name: external-auth-policy-two +``` + +NGINX Ingress Controller will use the configuration from the first policy reference `external-auth-policy-one`, and ignores `external-auth-policy-two`. To use different authentication methods on different routes, apply each ExternalAuth policy to its own route. + +#### OAuth2 sign-in redirect location + +When you configure `authSigninURI`, NGINX Ingress Controller generates an internal location block to handle sign-in redirects (based on `authSigninRedirectBasePath`, which defaults to `/oauth2`). Because NGINX location blocks are defined at the server level, only one sign-in redirect location can exist per host. If multiple routes on the same VirtualServer, VirtualServerRoute, Ingress, or Mergeable Ingress host reference ExternalAuth policies with `authSigninURI`, NGINX Ingress Controller uses the sign-in redirect configuration from the first policy it processes. All routes that use `authSigninURI` share that single redirect location. + +This means all routes on the same host that require OAuth2 sign-in must use the same OAuth2 Proxy backend for the redirect flow. If you need different OAuth2 providers for different routes, use separate hosts. + ### OIDC {{< call-out "tip" >}}