Supported features

NGINX Control plane support

NGINX Declarative API has been tested with the following NGINX control plane releases:

Control plane	API v5.0	API v5.1	API v5.2	Notes
NGINX Instance Manager	2.14+	2.16+	2.18+
NGINX One Console	Early access	General Availability	General availability

NGINX `http` and `stream` servers

Feature	API v5.0	API v5.1	API v5.2	Notes
Upstreams	X	X	X	Snippets supported: static and from source of truth
HTTP servers	X	X	X	Snippets supported (`http`, `servers`, `locations`): static and from source of truth
TCP/UDP servers	X	X	X	Snippets supported (`streams`, `servers`): static and from source of truth
TLS	X	X	X	Certificates and keys can be dynamically fetched from source of truth (currently supported for NGINX Instance Manager)
Client authentication	X	X	X	See client authentication
Upstream authentication	X	X	X	See upstream and Source of truth authentication
Rate limiting	X	X	X
Active healthchecks	X	X	X
Cookie-based stickiness	X	X	X
HTTP headers manipulation	X	X	X	To server: set, delete To client: add, delete, replace
Maps	X	X	X
NGINX Plus REST API access	X	X	X
NGINX App Protect WAF	X	X	X	NOTE: For NGINX Instance Manager only Per-policy CRUD at `server` and `location` level Support for dataplane-based bundle compilation Security policies can be fetched from source of truth

HTTP Locations

Locations .declaration.http.servers[].locations[].uri match modifiers in .declaration.http.servers[].locations[].urimatch can be:

prefix - prefix URI matching
exact - exact URI matching
regex - case sensitive regex matching
iregex - case insensitive regex matching
best - case sensitive regex matching that halts any other location matching once a match is made

NGINX API Gateway use case

Feature	API v5.0	API v5.1	API v5.2	Notes
Configuration generation from OpenAPI schema	X	X	X
HTTP methods enforcement	X	X	X
per-URI rate limiting	X	X	X
per-URI client authentication	X	Static JWT key JWT key fetched from URL Bearer token	Static JWT key JWT key fetched from URL Bearer token
per-URI client authorization	X	JWT claims	JWT claims
Developer portal	Redocly Backstage	Redocly Backstage	Redocly Backstage	Supported through 3rd party integration
API visibility		Moesif	Moesif	Supported through 3rd party integration

Swagger files and OpenAPI schemas can be used to automatically configure NGINX as an API Gateway

Declaration path .declaration.http.servers[].locations[].apigateway defines the API Gateway configuration:

openapi_schema - the base64-encoded schema, or the schema URL. YAML and JSON are supported
api_gateway.enabled - enable/disable API Gateway provisioning
api_gateway.strip_uri - removes the .declaration.http.servers[].locations[].uri part of the URI before forwarding requests to the upstream
api_gateway.server_url - the base URL of the upstream server
developer_portal.enabled - enable/disable Developer portal provisioning
developer_portal.type - developer portal type. redocly and backstage are currently supported
developer_portal.redocly.* - Redocly-based developer portal parameters. See the Postman collection
developer_portal.backstage.* - Backstage-based developer portal parameters. See the Postman collection
visibility[] - API Gateway visibility
- visibility[].enabled - enable/disable API gateway visibility
- visibility[].type - visibility integration type. moesif is currently supported
- visibility[].moesif.* - Moesif visibility parameters. See the Postman collection
authentication - optional, used to enforce authentication at the API Gateway level
authentication.client[] - authentication profile names
authentication.enforceOnPaths - if set to true authentication is enforced on all API endpoints listed under authentication.paths. if set to false authentication is enforced on all API endpoints but those listed under authentication.paths
authentication.paths - paths to enforce authentication
authorization[] - optional, used to enforce authorization
authorization[].profile - authorization profile name
authorization[].enforceOnPaths - if set to true authorization is enforced on all API endpoints listed under authorization.paths. if set to false authorization is enforced on all API endpoints but those listed under authorization[].paths
authorization[].paths - paths to enforce authorization
rate_limit - optional, used to enforce rate limiting at the API Gateway level
rate_limit.enforceOnPaths - if set to true rate limiting is enforced on all API endpoints listed under rate_limit.paths. if set to false rate limiting is enforced on all API endpoints but those listed under rate_limit.paths

See the Postman collection for usage examples

NGINX API Gateway use case - Developer Portal

Type	API v5.0	API v5.1	API v5.2	Notes
Redocly	X	X	X	Developer portal published by NGINX Plus
Backstage.io	X	X	X	Backstage YAML manifest generated

NGINX API Gateway use case - Visibility

Type	API v5.0	API v5.1	API v5.2	Notes
Moesif		X	X	Integration with Moesif - see https://www.moesif.com/docs/server-integration/nginx-openresty/

Client authentication

Type	Description	API v5.0	API v5.1	API v5.2	Notes
jwt	Java Web Token (JWT)	X	X	X
mtls	Mutual TLS	X	X	X	Supported for HTTP servers

Examples

Client-side authentication profiles to be defined under .declaration.http.authentication.client[]

jwt client authentication profile

{
   "name": "<PROFILE_NAME>",
   "type": "jwt",
   "jwt": {
       "realm": "<JWT_AUTHENTICATION_REALM>",
       "key": "<JWT_KEY>|<JWT_KEY_URL>",
       "cachetime": <OPTIONAL_JWT_KEY_CACHETIME_IN_SECONDS>,
       "token_location": "<OPTIONAL_TOKEN_LOCATION_AS_NGINX_VARIABLE>"
   }
}

mTLS client authentication profile

{
   "name": "<PROFILE_NAME>",
   "type": "mtls",
   "mtls": {
       "enabled": "<on|off|optional|optional_no_ca>",
       "client_certificates": "<CLIENT_CERTIFICATES_OBJECT_NAME>",
       "trusted_ca_certificates": "<TRUSTED_CERTIFICATES_OBJECT_NAME>",
       "ocsp": {
           "enabled": "<on|off|leaf>",
           "responder": "<OCSP_RESPONDER_URL>"
       },
       "stapling": {
           "enabled": <true|false>,
           "verify": <true|false>,
           "responder": "<OCSP_RESPONDER_URL>"
       }
   }
}

Client authorization

Type	Description	API v5.0	API v5.1	API v5.2	Notes
jwt	Java Web Token (JWT)	X	X	X	Based on JWT claims. Supported under .declaration.http.servers[] .declaration.http.servers[].location[] .declaration.http.servers[].location[].apigateway

Examples

Client-side authorization profiles to be defined under .declaration.http.authorization

jwt client authorization profile

{
 "name": "<PROFILE_NAME>",
 "type": "jwt",
 "jwt": {
   "claims": [
     {
       "name": "<CLAIM_NAME>",
       "value": [
         "<AUTHORIZED_VALUE_OR_REGEXP>"
       ],
       "errorcode": <OPTIONAL_ERROR_CODE_401_OR_403>
     }
   ]
 }
}

Upstream and Source of truth authentication

Type	Description	API v5.0	API v5.1	API v5.2	Notes
Bearer token	Authentication token as Authorization Bearer	X	X	X	`Bearer` Authorization header is injected in requests to upstreams and source of truth
Basic Auth	Authentication token as Authorization Basic	X	X	X	`Basic` Authorization header is injected in requests to upstreams and source of truth
HTTP header	Authentication token in custom HTTP header	X	X	X	HTTP header is injected in requests to upstreams and source of truth
mTLS	Mutual TLS	X	X	X	Client certificate is sent to upstream / source of truth

Examples

Server-side authentication profiles to be defined under .declaration.http.authentication.client[]

Bearer token authentication profile

{
   "name": "<PROFILE_NAME>",
   "type": "token",
   "token": {
       "type": "bearer",
       "token": "<AUTHENTICATION_TOKEN>"
   }
}

Basic authentication profile

{
   "name": "<PROFILE_NAME>",
   "type": "token",
   "token": {
       "type": "basic",
       "username": "<AUTHENTICATION_USERNAME>",
       "password": "<BASE64_ENCODED_PASSWORD>"
   }
}

HTTP header authentication profile

{
   "name": "<PROFILE_NAME>",
   "type": "token",
   "token": {
       "type": "header",
       "token": "<AUTHENTICATION_TOKEN>",
       "location": "<HTTP_HEADER_NAME>"
   }
}

mTLS authentication profile

"server": [
    {
        "name": "<PROFILE_NAME>",
        "type": "mtls",
        "mtls": {
            "certificate": "<CLIENT_CERTIFICATE>",
            "key": "<CLIENT_KEY>"
        }
    }

HTTP Headers manipulation

Type	API v5.0	API v5.1	API v5.2	Notes
Request (client to server)	X	X	X	`set` - new header injection `delete` - client header removal
Response (server to client)	X	X	X	`add` - new header injection `delete` - server header removal `replace` - server header replacement

Examples

To be defined under .declaration.http.servers[].headers and/or .declaration.http.servers[].location[]

 "headers": {
    "to_server": {
        "set": [
            {
                "name": "<HTTP_HEADER_NAME>",
                "value": "<VALUE_OR_NGINX_VARIABLE>"
            },
            ...
        ],
        "delete": [
          "<HTTP_HEADER_NAME>",
          ...
        ]
    },
    "to_client": {
        "add": [
            {
                "name": "<HTTP_HEADER_NAME>",
                "value": "<VALUE_OR_NGINX_VARIABLE>"
            },
            ...
        ],
        "delete": [
            "<HTTP_HEADER_NAME>",
            ...
        ],
        "replace": [
            {
                "name": "<HTTP_HEADER_NAME>",
                "value": "<VALUE_OR_NGINX_VARIABLE>"
            },
            ...
        ]
    }
}

NGINX Javascript

Hook type	API v5.0	API v5.1	API v5.2	Notes
js_body_filter	X	X	X	Available in `declaration.http.servers[].location[]`
js_content	X	X	X	Available in `declaration.http.servers[].location[]`
js_header_filter	X	X	X	Available in `declaration.http.servers[].location[]`
js_periodic	X	X	X	Available in `declaration.http.servers[].location[]`
js_preload_object	X	X	X	Available in `.declaration.http` `declaration.http.servers[]` `declaration.http.servers[].location[]`
js_set	X	X	X	Available in `.declaration.http` `declaration.http.servers[]` `declaration.http.servers[].location[]`

Note: njs profiles can be included in base64-encoded format under .declaration.http.njs[] of fetched from an external source of truth For detailed examples see the Postman collection

Examples

njs profile example:

{
  ...
  "declaration": {
    "http": {
      ...
      "njs_profiles": [
        {
          "name": "<NJS_PROFILE_NAME>",
          "file": {
            "content": "<BASE64_ENCODED_JAVASCRIPT_CODE|JAVASCRIPT_FILE_URL>",
            "authentication": [
              {
                "profile": "<SERVER_AUTHENTICATION_PROFILE>"
              }
            ]
          }
        }
      ]
    }
  }
}

njs hook examples (under .declaration.http, .declaration.http.servers[], .declaration.http.servers[].location[]):

"njs": [
    {
        "hook": {
            "type": "<HOOK_TYPE>"
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

Example hooks:

js_body_filter - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_body_filter

"njs": [
    {
        "hook": {
            "type": "js_body_filter",
            "js_body_filter": {
              "buffer_type": "<STRING_OR_BUFFER>"
            }
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

js_content - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_content

"njs": [
    {
        "hook": {
            "type": "js_content"
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

js_header_filter - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_header_filter

"njs": [
    {
        "hook": {
            "type": "js_header_filter"
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

js_periodic - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_periodic

"njs": [
    {
        "hook": {
            "type": "js_periodic",
            "js_periodic": {
                "interval": "<INTERVAL_TIME>",
                "jitter": "<NUMBER>",
                "worker_affinity": "<MASK>"
            }       
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

js_preload_object - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_preload_object

"njs": [
    {
        "hook": {
            "type": "js_preload_object"
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

js_set - see https://nginx.org/en/docs/http/ngx_http_js_module.html#js_set

"njs": [
    {
        "hook": {
            "type": "js_set",
            "js_set": {
              "variable": "<VARIABLE_NAME>"
            }
        },
        "profile": "<NJS_PROFILE_NAME>",
        "function": "<JAVASCRIPT_FUNCTION>"
    }
]

DNS resolvers

	API v5.0	API v5.1	API v5.2	Notes
DNS resolver profiles		X	X	Available in `declaration.http.servers[]` `declaration.http.upstreams[]` `declaration.layer4.upstreams[]`

Examples

DNS resolver profiles to be defined under .declaration.http.resolvers[]

DNS resolver profile:

{
   "name": "Google",
   "address": "8.8.8.8",
   "valid": "5s",
   "ipv4": true,
   "ipv6": false,
   "timeout": "30s"
}

Maps

Map entries .declaration.maps[].entries.keymatch can be:

exact - exact variable matching
regex - case sensitive regex matching
iregex - case insensitive regex matching

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FEATURES.md

FEATURES.md

Supported features

NGINX Control plane support

NGINX `http` and `stream` servers

HTTP Locations

NGINX API Gateway use case

NGINX API Gateway use case - Developer Portal

NGINX API Gateway use case - Visibility

Client authentication

Examples

Client authorization

Examples

Upstream and Source of truth authentication

Examples

HTTP Headers manipulation

Examples

NGINX Javascript

Examples

DNS resolvers

Examples

Maps

Files

FEATURES.md

Latest commit

History

FEATURES.md

File metadata and controls

Supported features

NGINX Control plane support

NGINX http and stream servers

HTTP Locations

NGINX API Gateway use case

NGINX API Gateway use case - Developer Portal

NGINX API Gateway use case - Visibility

Client authentication

Examples

Client authorization

Examples

Upstream and Source of truth authentication

Examples

HTTP Headers manipulation

Examples

NGINX Javascript

Examples

DNS resolvers

Examples

Maps

NGINX `http` and `stream` servers