Apache 2.4 mod_authnz_fcgi: Configuring External FastCGI Authentication and Authorization Providers

Apache HTTP Server 2.4 can delegate authentication and authorization decisions to external daemons using the mod_authnz_fcgi extension module. Rather than relying solely on internal flat files or database modules managed directly by Apache, mod_authnz_fcgi transmits authentication and authorization checks over FastCGI to a standalone backend service.

This guide explains how to define FastCGI providers with AuthnzFcgiDefineProvider, how to enable non-Basic authentication with AuthnzFcgiCheckAuthnProvider, how connection lifecycles operate, and how request environment variables are passed between Apache and backend authorizers.

Research Method and Limitations

This technical guide was prepared strictly from the supplied public documentation excerpts for Apache HTTP Server 2.4, specifically the module references for mod_authnz_fcgi (available in version 2.4.10 and later) and mod_auth_basic. No hands-on lab benchmarks, physical server installations, or performance tests were conducted. Competing external coverage was unavailable in the supplied dataset, and portions of the primary source text were truncated. Evaluation is based entirely on documented module behaviors, visible directive options, and explicit limitations within the provided text.

Before configuring mod_authnz_fcgi, verify the following prerequisites:

• Apache HTTP Server version 2.4.10 or higher compiled with or loading mod_authnz_fcgi (module identifier: authnz_fcgi_module).
• mod_auth_basic loaded when delegating HTTP Basic authentication.
• An independently managed FastCGI authorizer application listening on a reachable TCP socket (such as fcgi://localhost:10102/).

Process Management and Connection Handling

Application process management is permanently out of scope for mod_authnz_fcgi. Apache will not fork, monitor, spawn, or restart the authentication daemon.

Administrators must manage FastCGI application processes independently using external tools such as fcgistarter. The service must be running and listening before Apache sends requests.

Documented connection handling behavior includes:

• Transport protocol: Only TCP sockets (specified in the form fcgi://hostname:port/) are supported. Local Unix domain sockets and pipes are not currently supported.
• Connection closure: The connection to the FastCGI authorizer is closed after every phase of processing. If an authorizer handles separate authentication and authorization phases, two connections will be used.
• Internal subrequests: Providers are registered as AP_AUTH_INTERNAL_PER_CONF. Apache does not repeat checks for internal subrequests sharing the same access control configuration as the initial request.

Configuring Providers with AuthnzFcgiDefineProvider

External authorizers are declared in the server configuration context using the AuthnzFcgiDefineProvider directive.

Directive Syntax

AuthnzFcgiDefineProvider type provider-name backend-address

• type: Specifies the processing role. Must be authn (authentication), authz (authorization), or authnz (generic FastCGI authorizer performing both checks).
• provider-name: Assigns a name to the provider, which is referenced in other directives such as AuthBasicProvider, Require, or AuthnzFcgiCheckAuthnProvider.
• backend-address: Specifies the network endpoint formatted strictly as fcgi://hostname:port/.

Scenario 1: Separate Authentication and Authorization Roles

When the backend application handles authentication and authorization in distinct phases, define separate providers for each phase:

# Server configuration context
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/
AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10102/

# Directory or Location context
<Location "/protected/">
    AuthType Basic
    AuthName "Restricted Area"
    AuthBasicProvider FooAuthn
    Require FooAuthz
</Location>

In this workflow, Apache invokes FooAuthn during the authentication phase. If authentication succeeds, Apache initiates a second connection to FooAuthz during the authorization phase.

Scenario 2: Combined FastCGI Authorizer (authnz)

For applications conforming to the generic web-server-agnostic FastCGI authorizer protocol, both checks occur in a single invocation during the authentication phase:

# Server configuration context
AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/

# Directory or Location context
<Location "/protected/">
    AuthType Basic
    AuthName "Restricted Area"
    AuthBasicProvider FooAuthnz
    Require FooAuthnz
</Location>

When the provider type is authnz, the application is queried during the Apache HTTP Server API authentication phase. If the daemon returns a 200 status, subsequent evaluation of Require FooAuthnz during the authorization phase succeeds immediately without invoking the application a second time.

Non-Basic Authentication and AuthnzFcgiCheckAuthnProvider

Some capabilities of FastCGI authorizers cannot be enabled with AuthBasicProvider and require AuthnzFcgiCheckAuthnProvider in a directory context. These include non-Basic authentication, determining the user ID from the authorizer, selecting custom HTTP response codes, and returning response bodies of up to 8192 bytes for non-200 responses.

Directive Syntax and Options

AuthnzFcgiCheckAuthnProvider provider-name|None [option ...]

• provider-name: The name of an authn provider defined via AuthnzFcgiDefineProvider, or None to disable an inherited provider from an outer scope.
• Authoritative On|Off: Controls whether other modules are allowed to run when this module fails the request (defaults to On).
• RequireBasicAuth On|Off: Controls whether Basic authentication credentials are required before calling the authorizer (defaults to Off). When set to Off, requests without Basic authentication credentials can be passed to the authorizer. When set to On, a request lacking a user ID and password returns an HTTP 401 without invoking the authorizer.
• UserExpr expr: Specifies an expression using ap_expr syntax evaluated after calling the authorizer to determine the user identity when the client does not provide Basic authentication. A typical use is referencing a Variable-XXX setting returned by the authorizer, such as UserExpr "%{reqenv:MY_USER}" (where the authorizer emitted Variable-MY_USER: username). If UserExpr is specified and the user ID cannot be retrieved after a successful authentication response, Apache rejects the request with an HTTP 500 error.

Non-Basic Authentication Configuration Example

To pass non-Basic requests to the authorizer and resolve the user identity from a custom variable returned by the backend, configure AuthnzFcgiCheckAuthnProvider with RequireBasicAuth Off and UserExpr:

# Server configuration context
AuthnzFcgiDefineProvider authn CustomAuthn fcgi://localhost:10104/

# Directory or Location context
<Location "/custom-auth/">
    AuthnzFcgiCheckAuthnProvider CustomAuthn RequireBasicAuth Off UserExpr "%{reqenv:MY_USER}"
    Require valid-user
</Location>

Environment Variables and Custom Headers

When delegating to the FastCGI backend, Apache populates FastCGI environment variables based on the configured mode and request details:

• Role flags: For separate authz providers, Apache sets both FCGI_ROLE and FCGI_APACHE_ROLE to AUTHORIZER. For generic authnz providers, FCGI_ROLE is set to AUTHORIZER, while FCGI_APACHE_ROLE is not set.
• User credentials: When Basic authentication credentials are supplied, REMOTE_USER and REMOTE_PASSWD are passed to the authorizer. In authorization-only mode (authz), password variables are not passed.
• Returning custom variables: Backend authorizers can return custom response headers prefixed with Variable- (for example, Variable-AUTHZ_1: authz_01 or Variable-MY_USER: alice). Apache makes these values accessible to subsequent configuration directives as request environment variables (such as %{reqenv:AUTHZ_1} or %{reqenv:MY_USER}).

Logging and Diagnostic Levels

Troubleshooting FastCGI authorizer communication uses the standard Apache LogLevel directive:

Log levels can be configured specifically for the module, such as LogLevel info authnz_fcgi:trace2, to inspect variables without globally increasing verbosity.

Documented Limitations

When planning an architecture around mod_authnz_fcgi, account for the following documented constraints:

• Transport: Only TCP sockets (fcgi://hostname:port/) are supported. Local Unix domain sockets and pipes are not currently supported.
• No Digest authentication support: Using AuthDigestProvider is expected to be a permanent limitation because there is no authorizer flow for retrieving a password hash.
• mod_authn_socache interaction: Support for mod_authn_socache interaction is not currently implemented.
• No URI mapping: Client URIs cannot be mapped or rewritten using directives like ProxyPass in the authorizer phase.
• Application process management: Permanently out of scope for this module; processes must be managed externally.
• Charset restrictions: In an EBCDIC compilation environment, FastCGI protocol data is written in EBCDIC and expected to be received in EBCDIC.

Summary Checklist

• Start and monitor the external FastCGI daemon independently using external tools like fcgistarter.
• Define providers in the server configuration context using AuthnzFcgiDefineProvider with a valid TCP endpoint (fcgi://hostname:port/) and type (authn, authz, or authnz).
• For standard Basic authentication, attach defined providers inside directory or location blocks using AuthBasicProvider and Require.
• For non-Basic authentication, attach the provider inside the target directory context using AuthnzFcgiCheckAuthnProvider, setting RequireBasicAuth Off and UserExpr referencing a Variable-XXX returned by the authorizer.
• Avoid trace5 logging in production to prevent recording raw credentials and sensitive payload data.

Source references

• httpd.apache.org documentation
• httpd.apache.org documentation