nginx auth_gate Module

Overview

About This Module

The nginx auth_gate module is a dynamic module that adds variable value comparison validation, JSON field validation, JWT claim validation, and JWT signature verification capabilities to nginx. It operates in nginx's PRECONTENT phase, validating authorization conditions before requests reach the backend.

License: MIT License

Key Features

• Operator-Based Comparison: 8 operators (eq, gt, ge, lt, le, in, any, match) with negation via ! prefix
• JSON Field Validation: Parse variable values as JSON and validate specific fields using JQ-like field paths
• JWT Claim Validation: Decode JWT tokens and validate payload claims with operators
• JWT Signature Verification: Verify JWT signatures using JWKS fetched via subrequests (RSA, ECDSA, EdDSA)
• Variable Truthiness Check: Check if variables are truthy (compatible with the commercial auth_require directive)
• Custom Error Codes: Specify HTTP error codes (400-599) per directive with the error= parameter
• Flexible Field Paths: JQ-like syntax supporting nested keys, array indices, and bracket notation
• ReDoS Protection: PCRE match/depth limits and dynamic pattern compilation limits

Security

This module provides JWT signature verification via auth_gate_jwt_verify and handles authorization with various validation directives. See SECURITY.md for security considerations.

Relationship to the Commercial auth_require

The auth_gate directive also provides truthiness check functionality equivalent to the auth_require directive from the nginx commercial subscription. See COMMERCIAL_COMPATIBILITY.md for details.

Quick Start

See INSTALL.md for installation instructions.

Minimal Configuration

The following are minimal examples of each directive provided by the auth_gate module:

load_module "/usr/lib/nginx/modules/ngx_http_auth_gate_module.so";

http {
    # Strip Bearer prefix from Authorization header
    map $http_authorization $bearer_token {
        default "";
        ~*^Bearer\s+(?<t>.+)$ $t;
    }

    server {
        # auth_gate: compare variable values with operators
        location /admin {
            auth_gate $arg_role eq "admin" error=403;
            proxy_pass http://backend;
        }

        # auth_gate_json: validate fields in a JSON variable
        location /api {
            auth_gate_json $json .role eq "admin" error=403;
            proxy_pass http://backend;
        }

        # auth_gate_jwt_verify: verify JWT signature using JWKS
        location = /jwks {
            internal;
            proxy_set_header Accept-Encoding "";
            proxy_pass http://idp/.well-known/jwks.json;
        }
        location /secure-api {
            auth_gate_jwt_verify $bearer_token jwks=/jwks;
            auth_gate_jwt $bearer_token .role eq "admin" error=403;
            proxy_pass http://backend;
        }

        # auth_gate_jwt: validate JWT token claims (assumes signature verification by another module)
        location /external {
            auth_gate_jwt $token .sub !eq "" error=401;
            proxy_pass http://backend;
        }
    }
}

Directives

This module provides the following directives. See DIRECTIVES.md for details.

Directive	Function
auth_gate	Operator-based variable value comparison, and variable truthiness check
auth_gate_json	Parse variable value as JSON and validate specified fields with operators
auth_gate_jwt	Decode variable value as JWT and validate payload claims (no signature verification)
auth_gate_jwt_verify	Verify JWT signature using JWKS fetched from an internal location

There are 8 operators: eq, gt, ge, lt, le, in, any, and match, with negation possible via the ! prefix.

Embedded Variables

This module provides the following nginx variables. See DIRECTIVES.md for details.

Variable	Description
$auth_gate_epoch	Current UNIX epoch time (seconds)

Appendix

Processing Flow Overview

The auth_gate module operates in nginx's PRECONTENT phase. For each request, validations are executed in the following order. When any validation fails, short-circuit evaluation (skipping remaining checks) returns the corresponding error code (default: 401 for auth_gate_jwt_verify, 403 for others). The request proceeds to the next phase only if all validations pass.

Standards References

• nginx commercial auth_require: Commercial version directive specification
• RFC 7519 - JSON Web Token (JWT): JWT specification
• RFC 7515 - JSON Web Signature (JWS): JWS specification
• RFC 7517 - JSON Web Key (JWK): JWK specification
• jq Manual: Reference for field path syntax
• PCRE - Perl Compatible Regular Expressions: Regular expression engine for the match operator

Related Documentation

Configuration & Operations:

• DIRECTIVES.md: Directive and variable reference
• EXAMPLES.md: Quick start and practical configuration examples
• INSTALL.md: Installation guide (prerequisites, build instructions)
• SECURITY.md: Security considerations (JWT signature verification, input validation)
• TROUBLESHOOTING.md: Troubleshooting (common issues, log inspection)

Reference:

• COMMERCIAL_COMPATIBILITY.md: Commercial auth_require compatibility