Policy resources

The Policy resource allows you to configure features like access control and rate-limiting, which you can add to your VirtualServer and VirtualServerRoute resources.

The resource is implemented as a Custom Resource.

This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our GitHub repository.

Prerequisites

Policies work together with VirtualServer and VirtualServerRoute resources, which you need to create separately.

Policy Specification

Below is an example of a policy that allows access for clients from the subnet 10.0.0.0/8 and denies access for any other clients:

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: allow-localhost
spec:
  accessControl:
    allow:
    - 10.0.0.0/8

* A policy must include exactly one policy.

AccessControl

The access control policy configures NGINX to deny or allow requests from clients with the specified IP addresses/subnets.

For example, the following policy allows access for clients from the subnet 10.0.0.0/8 and denies access for any other clients:

accessControl:
  allow:
  - 10.0.0.0/8

In contrast, the policy below does the opposite: denies access for clients from 10.0.0.0/8 and allows access for any other clients:

accessControl:
  deny:
  - 10.0.0.0/8

Note: The feature is implemented using the NGINX ngx_http_access_module. NGINX Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does).

AccessControl Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple access control policies. For example, here we reference two policies, each with configured allow lists:

policies:
- name: allow-policy-one
- name: allow-policy-two

When you reference more than one access control policy, NGINX Ingress Controller will merge the contents into a single allow list or a single deny list.

Referencing both allow and deny policies, as shown in the example below, is not supported. If both allow and deny lists are referenced, NGINX Ingress Controller uses just the allow list policies.

policies:
- name: deny-policy
- name: allow-policy-one
- name: allow-policy-two

RateLimit

The rate limit policy configures NGINX to limit the processing rate of requests.

For example, the following policy will limit all subsequent requests coming from a single IP address once a rate of 10 requests per second is exceeded:

rateLimit:
  rate: 10r/s
  zoneSize: 10M
  key: ${binary_remote_addr}

Note: The feature is implemented using the NGINX ngx_http_limit_req_module.

For each policy referenced in a VirtualServer and/or its VirtualServerRoutes, NGINX Ingress Controller will generate a single rate limiting zone defined by the limit_req_zone directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller will generate two different rate limiting zones, one zone per VirtualServer.

RateLimit Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple rate limit policies. For example, here we reference two policies:

policies:
- name: rate-limit-policy-one
- name: rate-limit-policy-two

When you reference more than one rate limit policy, NGINX Ingress Controller will configure NGINX to use all referenced rate limits. When you define multiple policies, each additional policy inherits the dryRun, logLevel, and rejectCode parameters from the first policy referenced (rate-limit-policy-one, in the example above).

APIKey

The API Key auth policy configures NGINX to authorize client requests based on the presence of a valid API Key in a header or query param specified in the policy.

Note: The feature is implemented using NGINX ngx_http_auth_request_module and NGINX JavaScript (NJS).

The policies’ API keys are securely stored using SHA-256 hashing. When a client sends an API Key, it is hashed by NJS and then compared to the hashed API Key in the NGINX config.

If the hashed keys match, the NGINX JavaScript (NJS) subrequest issues a 204 No Content response to the auth_request directive, indicating successful authorization. Conversely, if no API Key is provided in the specified header or query parameter, a 401 Unauthorized response is returned. Similarly, if an invalid key is presented in the expected header or query parameter, a 403 Forbidden response is issued, denying access.

It is possible to use the errorPages property on a route, to change the default behaviour of 401 or 403 errors.

At least one header or query param is required.

The policy below configures NGINX Ingress Controller to require the API Key password in the header “my-header”.

apiKey:
    suppliedIn:
      header:
      - "my-header"
    clientSecret: api-key-secret

apiVersion: v1
kind: Secret
metadata:
  name: api-key-secret
type: nginx.org/apikey
data:
    client1: cGFzc3dvcmQ= # password

APIKey Merging Behavior

A VirtualServer or VirtualServerRoute can be associated with only one API Key policy per route or subroute. However, it is possible to replace an API Key policy from a higher-level with a different policy defined on a more specific route.

For example, a VirtualServer can implement different API Key policies at various levels. In the configuration below, the server-wide api-key-policy-server applies to /backend1 for authorization, as it lacks a more specific policy. Meanwhile, /backend2 uses the api-key-policy-route defined at the route level.

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: virtual-server
spec:
  host: virtual-server.example.com
  policies:
  - name: api-key-policy-server
  upstreams:
  - name: backend2
    service: backend2-svc
    port: 80
  - name: backend1
    service: backend1-svc
    port: 80
  routes:
  - path: /backend1
    action:
      pass: backend1
  - path: /backend2
    action:
      pass: backend2
    policies:
      - name: api-key-policy-route

BasicAuth

The basic auth policy configures NGINX to authenticate client requests using the HTTP Basic authentication scheme.

For example, the following policy will reject all requests that do not include a valid username/password combination in the HTTP header Authentication

basicAuth:
  secret: htpasswd-secret
  realm: "My API"

Note: The feature is implemented using the NGINX ngx_http_auth_basic_module.

BasicAuth Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple basic auth policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: basic-auth-policy-one
- name: basic-auth-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference basic-auth-policy-one, and ignores basic-auth-policy-two.

JWT Using Local Kubernetes Secret

Note: This feature is only available in NGINX Plus.

The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens.

The following example policy will reject all requests that do not include a valid JWT in the HTTP header token:

jwt:
  secret: jwk-secret
  realm: "My API"
  token: $http_token

You can pass the JWT claims and JOSE headers to the upstream servers. For example:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: user
        value: ${jwt_claim_user}
      - name: alg
        value: ${jwt_header_alg}

We use the requestHeaders of the Action.Proxy to set the values of two headers that NGINX will pass to the upstream servers.

The value of the ${jwt_claim_user} variable is the user claim of a JWT. For other claims, use ${jwt_claim_name}, where name is the name of the claim. Note that nested claims and claims that include a period (.) are not supported. Similarly, use ${jwt_header_name} where name is the name of a header. In our example, we use the alg header.

Note: This feature is implemented using the NGINX Plus ngx_http_auth_jwt_module.

JWT Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple JWT policies. However, only one can be applied: every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: jwt-policy-one
- name: jwt-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference jwt-policy-one, and ignores jwt-policy-two.

JWT Using JWKS From Remote Location

Note: This feature is only available in NGINX Plus.

The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens, allowing import of the keys (JWKS) for JWT policy by means of a URL (for a remote server or an identity provider) as a result they don’t have to be copied and updated to the IC pod.

The following example policy will reject all requests that do not include a valid JWT in the HTTP header fetched from the identity provider:

jwt:
  realm: MyProductAPI
  token: $http_token
  jwksURI: <uri_to_remote_server_or_idp>
  keyCache: 1h

Note: This feature is implemented using the NGINX Plus directive auth_jwt_key_request under ngx_http_auth_jwt_module.

Note: Content caching is enabled by default for each JWT policy with a default time of 12 hours. This is done to ensure to improve resiliency by allowing the JWKS (JSON Web Key Set) to be retrieved from the cache even when it has expired.

JWT Merging Behavior

This behavior is similar to using a local Kubernetes secret where a VirtualServer/VirtualServerRoute can reference multiple JWT policies. However, only one can be applied: every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: jwt-policy-one
- name: jwt-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference jwt-policy-one, and ignores jwt-policy-two.

IngressMTLS

The IngressMTLS policy configures client certificate verification.

For example, the following policy will verify a client certificate using the CA certificate specified in the ingress-mtls-secret:

ingressMTLS:
  clientCertSecret: ingress-mtls-secret
  verifyClient: "on"
  verifyDepth: 1

Below is an example of the ingress-mtls-secret using the secret type nginx.org/ca

kind: Secret
metadata:
  name: ingress-mtls-secret
apiVersion: v1
type: nginx.org/ca
data:
  ca.crt: <base64encoded-certificate>

A VirtualServer that references an IngressMTLS policy must:

• Enable TLS termination.
• Reference the policy in the VirtualServer spec. It is not allowed to reference an IngressMTLS policy in a route or in a VirtualServerRoute subroute.

If the conditions above are not met, NGINX will send the 500 status code to clients.

You can pass the client certificate details, including the certificate, to the upstream servers. For example:

action:
  proxy:
    upstream: webapp
    requestHeaders:
      set:
      - name: client-cert-subj-dn
        value: ${ssl_client_s_dn} # subject DN
      - name: client-cert
        value: ${ssl_client_escaped_cert} # client certificate in the PEM format (urlencoded)

We use the requestHeaders of the Action.Proxy to set the values of the two headers that NGINX will pass to the upstream servers. See the list of embedded variables that are supported by the ngx_http_ssl_module, which you can use to pass the client certificate details.

Note: The feature is implemented using the NGINX ngx_http_ssl_module.

Using a Certificate Revocation List

The IngressMTLS policy supports configuring at CRL for your policy. This can be done in one of two ways.

Note: Only one of these configurations options can be used at a time.

1. Adding the ca.crl field to the nginx.org/ca secret type, which accepts a base64 encoded certificate revocation list (crl). Example YAML:

kind: Secret
metadata:
  name: ingress-mtls-secret
apiVersion: v1
type: nginx.org/ca
data:
  ca.crt: <base64encoded-certificate>
  ca.crl: <base64encoded-crl>

2. Adding the crlFileName field to your IngressMTLS policy spec with the name of the CRL file.

Note: This configuration option should only be used when using a CRL that is larger than 1MiB Otherwise we recommend using the nginx.org/ca secret type for managing your CRL.

Example YAML:

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: ingress-mtls-policy
spec:
ingressMTLS:
    clientCertSecret: ingress-mtls-secret
    crlFileName: webapp.crl
    verifyClient: "on"
    verifyDepth: 1

IMPORTANT NOTE When configuring a CRL with the ingressMTLS.crlFileName field, there is additional context to keep in mind:

1. NGINX Ingress Controller will expect the CRL, in this case webapp.crl, will be in /etc/nginx/secrets. A volume mount will need to be added to NGINX Ingress Controller deployment add your CRL to /etc/nginx/secrets
2. When updating the content of your CRL (e.g a new certificate has been revoked), NGINX will need to be reloaded to pick up the latest changes. Depending on your environment this may require updating the name of your CRL and applying this update to your ingress-mtls.yaml policy to ensure NGINX picks up the latest CRL.

Please refer to the Kubernetes documentation on volumes to find the best implementation for your environment.

IngressMTLS Merging Behavior

A VirtualServer can reference only a single IngressMTLS policy. Every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: ingress-mtls-policy-one
- name: ingress-mtls-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference ingress-mtls-policy-one, and ignores ingress-mtls-policy-two.

EgressMTLS

The EgressMTLS policy configures upstreams authentication and certificate verification.

For example, the following policy will use egress-mtls-secret to authenticate with the upstream application and egress-trusted-ca-secret to verify the certificate of the application:

egressMTLS:
  tlsSecret: egress-mtls-secret
  trustedCertSecret: egress-trusted-ca-secret
  verifyServer: on
  verifyDepth: 2

Note: The feature is implemented using the NGINX ngx_http_proxy_module.

EgressMTLS Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple EgressMTLS policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: egress-mtls-policy-one
- name: egress-mtls-policy-two

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.

OIDC

Feature Status: This feature is disabled by default. To enable it, set the enable-oidc command-line argument of NGINX Ingress Controller.

The OIDC policy configures NGINX Plus as a relying party for OpenID Connect authentication.

For example, the following policy will use the client ID nginx-plus and the client secret oidc-secret to authenticate with the OpenID Connect provider https://idp.example.com:

spec:
  oidc:
    clientID: nginx-plus
    clientSecret: oidc-secret
    authEndpoint: https://idp.example.com/openid-connect/auth
    tokenEndpoint: https://idp.example.com/openid-connect/token
    jwksURI: https://idp.example.com/openid-connect/certs
    accessTokenEnable: true

NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP header username.

Note: The feature is implemented using the reference implementation of NGINX Plus as a relying party for OpenID Connect authentication.

Prerequisites

In order to use OIDC, you need to enable zone synchronization. If you don’t set up zone synchronization, NGINX Plus will fail to reload. You also need to configure a resolver, which NGINX Plus will use to resolve the IDP authorization endpoint. You can find an example configuration in our GitHub repository.

Note: The configuration in the example doesn’t enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens.

Limitations

The OIDC policy defines a few internal locations that can’t be customized: /_jwks_uri, /_token, /_refresh, /_id_token_validation, /logout, /_logout. In addition, as explained below /_codexch is the default value for redirect URI, but can be customized. Specifying one of these locations as a route in the VirtualServer or VirtualServerRoute will result in a collision and NGINX Plus will fail to reload.

Note: Only one OIDC policy can be referenced in a VirtualServer and its VirtualServerRoutes. However, the same policy can still be applied to different routes in the VirtualServer and VirtualServerRoutes.

OIDC Merging Behavior

A VirtualServer/VirtualServerRoute can reference only a single OIDC policy. Every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: oidc-policy-one
- name: oidc-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference oidc-policy-one, and ignores oidc-policy-two.

Using Policy

You can use the usual kubectl commands to work with Policy resources, just as with built-in Kubernetes resources.

For example, the following command creates a Policy resource defined in access-control-policy-allow.yaml with the name webapp-policy:

kubectl apply -f access-control-policy-allow.yaml

policy.k8s.nginx.org/webapp-policy configured

You can get the resource by running:

kubectl get policy webapp-policy

NAME            AGE
webapp-policy   27m

For kubectl get and similar commands, you can also use the short name pol instead of policy.

WAF

Note: This feature is only available in NGINX Plus with AppProtect.

The WAF policy configures NGINX Plus to secure client requests using App Protect WAF policies.

For example, the following policy will enable the referenced APPolicy. You can configure multiple APLogConfs with log destinations:

waf:
  enable: true
  apPolicy: "default/dataguard-alarm"
  securityLogs:
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc.default:514"
  - enable: true
    apLogConf: "default/logconf"
    logDest: "syslog:server=syslog-svc-secondary.default:514"

Note: The field waf.securityLog is deprecated and will be removed in future releases.It will be ignored if waf.securityLogs is populated. Note: The feature is implemented using the NGINX Plus NGINX App Protect WAF Module.

WAF Merging Behavior

A VirtualServer/VirtualServerRoute can reference multiple WAF policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies:

policies:
- name: waf-policy-one
- name: waf-policy-two

In this example NGINX Ingress Controller will use the configuration from the first policy reference waf-policy-one, and ignores waf-policy-two.

Applying Policies

You can apply policies to both VirtualServer and VirtualServerRoute resources. For example:

• VirtualServer:

  apiVersion: k8s.nginx.org/v1
  kind: VirtualServer
  metadata:
    name: cafe
    namespace: cafe
  spec:
    host: cafe.example.com
    tls:
      secret: cafe-secret
    policies: # spec policies
    - name: policy1
    upstreams:
    - name: coffee
      service: coffee-svc
      port: 80
    routes:
    - path: /tea
      policies: # route policies
      - name: policy2
        namespace: cafe
      route: tea/tea
    - path: /coffee
      policies: # route policies
      - name: policy3
        namespace: cafe
      action:
        pass: coffee
    ```
  
    For VirtualServer, you can apply a policy:
  * to all routes (spec policies)
  * to a specific route (route policies)
  
    Route policies of the *same type* override spec policies. In the example above, if the type of the policies `policy-1` and `policy-3` is `accessControl`, then for requests to `cafe.example.com/coffee`, NGINX will apply `policy-3`.
  
    The overriding is enforced by NGINX: the spec policies are implemented in the `server` context of the config, and the route policies are implemented in the `location` context. As a result, the route policies of the same type win.
  

• VirtualServerRoute, which is referenced by the VirtualServer above:

  apiVersion: k8s.nginx.org/v1
  kind: VirtualServerRoute
  metadata:
    name: tea
    namespace: tea
  spec:
    host: cafe.example.com
    upstreams:
    - name: tea
      service: tea-svc
      port: 80
    subroutes: # subroute policies
    - path: /tea
      policies:
      - name: policy4
        namespace: tea
      action:
        pass: tea
  

  For VirtualServerRoute, you can apply a policy to a subroute (subroute policies).

  Subroute policies of the same type override spec policies. In the example above, if the type of the policies policy-1 (in the VirtualServer) and policy-4 is accessControl, then for requests to cafe.example.com/tea, NGINX will apply policy-4. As with the VirtualServer, the overriding is enforced by NGINX.

  Subroute policies always override route policies no matter the types. For example, the policy policy-2 in the VirtualServer route will be ignored for the subroute /tea, because the subroute has its own policies (in our case, only one policy policy4). If the subroute didn’t have any policies, then the policy-2 would be applied. This overriding is enforced by NGINX Ingress Controller – the location context for the subroute will either have route policies or subroute policies, but not both.

Invalid Policies

NGINX will treat a policy as invalid if one of the following conditions is met:

• The policy doesn’t pass the comprehensive validation.
• The policy isn’t present in the cluster.
• The policy doesn’t meet its type-specific requirements. For example, an ingressMTLS policy requires TLS termination enabled in the VirtualServer.

For an invalid policy, NGINX returns the 500 status code for client requests with the following rules:

• If a policy is referenced in a VirtualServer route or a VirtualServerRoute subroute, then NGINX will return the 500 status code for requests for the URIs of that route/subroute.
• If a policy is referenced in the VirtualServer spec, then NGINX will return the 500 status code for requests for all URIs of that VirtualServer.

If a policy is invalid, the VirtualServer or VirtualServerRoute will have the status with the state Warning and the message explaining why the policy wasn’t considered invalid.

Validation

Two types of validation are available for the Policy resource:

• Structural validation, done by kubectl and the Kubernetes API server.
• Comprehensive validation, done by NGINX Ingress Controller.

Structural Validation

The custom resource definition for the Policy includes a structural OpenAPI schema, which describes the type of every field of the resource.

If you try to create (or update) a resource that violates the structural schema – for example, the resource uses a string value instead of an array of strings in the allow field – kubectl and the Kubernetes API server will reject the resource.

• Example of kubectl validation:

  kubectl apply -f access-control-policy-allow.yaml
  
  error: error validating "access-control-policy-allow.yaml": error validating data: ValidationError(Policy.spec.accessControl.allow): invalid type for org.nginx.k8s.v1.Policy.spec.accessControl.allow: got "string", expected "array"; if you choose to ignore these errors, turn validation off with --validate=false
  

• Example of Kubernetes API server validation:

  kubectl apply -f access-control-policy-allow.yaml --validate=false
  
  The Policy "webapp-policy" is invalid: spec.accessControl.allow: Invalid value: "string": spec.accessControl.allow in body must be of type array: "string"
  

If a resource passes structural validation, then NGINX Ingress Controller’s comprehensive validation runs.

Comprehensive Validation

NGINX Ingress Controller validates the fields of a Policy resource. If a resource is invalid, NGINX Ingress Controller will reject it. The resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it.

You can use kubectl to check whether or not NGINX Ingress Controller successfully applied a Policy configuration. For our example webapp-policy Policy, we can run:

kubectl describe pol webapp-policy

. . .
Events:
  Type    Reason          Age   From                      Message
  ----    ------          ----  ----                      -------
  Normal  AddedOrUpdated  11s   nginx-ingress-controller  Policy default/webapp-policy was added or updated

Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied.

If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a Policy webapp-policy with an invalid IP 10.0.0. in the allow field, you will get:

kubectl describe policy webapp-policy

. . .
Events:
  Type     Reason    Age   From                      Message
  ----     ------    ----  ----                      -------
  Warning  Rejected  7s    nginx-ingress-controller  Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP

Note how the events section includes a Warning event with the Rejected reason.

Additionally, this information is also available in the status field of the Policy resource. Note the Status section of the Policy:

kubectl describe pol webapp-policy

. . .
Status:
  Message:  Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP
  Reason:   Rejected
  State:    Invalid

Note: If you make an existing resource invalid, NGINX Ingress Controller will reject it.