HTTP Auth RADIUS#

The module checks the user name and password that the client sends with HTTP Basic authentication against one or more RADIUS servers. The password goes to the RADIUS server in the User-Password attribute (PAP); other authentication methods, such as CHAP or MS-CHAP, are not supported.

Installation#

To install the module, use one of the following packages:

  • Angie: angie-module-http-auth-radius

  • Angie PRO: angie-pro-module-http-auth-radius

Loading the Module#

Load the module in the main{} context:

load_module modules/ngx_http_auth_radius_module.so;

With the module loaded, the http context must contain at least one radius_server block: otherwise worker processes log no radius servers and exit at startup, and Angie does not restart them.

Configuration Example#

load_module modules/ngx_http_auth_radius_module.so;

http {
    radius_server radius1 {
        url          10.0.0.11:1812;
        secret       "radius-secret";
        auth_timeout 2s;
        auth_retries 2;
    }

    radius_server radius2 {
        url    10.0.0.12;
        secret "radius-secret";
    }

    server {
        listen 80;

        location / {
            radius_servers radius1;
            radius_servers radius2;
            auth_radius    "Restricted";

            proxy_pass http://127.0.0.1:8080;
        }
    }
}

Each radius_server block in the http context describes one RADIUS server: its address (url, port 1812 by default) and the shared secret. Define these blocks before the locations that refer to them. If the server does not reply within auth_timeout (5 seconds by default), the module sends the request again, up to auth_retries requests in total (3 by default). With the values above, the module waits up to 4 seconds for radius1. The block also accepts nas_identifier, a value that the module sends in its requests, and queue_size, the number of requests to the server that can wait for a reply at once (10 by default).

In a location, each radius_servers directive adds a server to the list that the module tries in order, and auth_radius (or its synonym radius_auth) enables authentication with the given realm. If a server does not reply after all attempts or refuses the connection, the module asks the next server; when the list runs out, the client gets a 503 response. If a server rejects the credentials, the client gets a 401 response, and the module does not ask the next server.

The module does not send the Message-Authenticator attribute. A RADIUS server that requires it in every request, such as FreeRADIUS with its default client settings in recent releases, ignores the module's requests, and the client gets a 503 response after the timeouts expire. Allow requests without this attribute for the Angie client on the RADIUS server.

The radius_servers and auth_radius directives work only in a location block and are not inherited by nested locations; specify them in every location to protect.

With radius_health instead of auth_radius, a location checks whether the RADIUS servers respond. The module sends a check request with the user name and password given in the directive, both optional. If a server replies at all, accepting or rejecting these credentials, the module lets the client's request through. The health_timeout and health_retries parameters of the radius_server block (5 seconds and 1 by default) apply to these check requests.

Additional Information#

Version: 458af16

Detailed documentation and source code are available at: ten0s/ngx_http_auth_radius_module