NGINX auth_request module: The Complete Guide

Introduction

When deploying web applications, security is a fundamental concern. Authenticating user requests to only allow access to authorised users is a typical pattern in web security. NGINX, a high-performance HTTP server and reverse proxy, offers a powerful module ‘auth_request’ tailored for such purposes. The auth_request module allows NGINX to delegate user authentication to an external service. In this guide, we’ll explore the auth_request module in detail and walk you through setting it up.

Prerequisites

• A running instance of NGINX
• Understanding of HTTP authentication mechanisms
• Familiarity with setting up proxy servers

What Is the auth_request Module?

The auth_request module allows NGINX to make a sub-request to an external authentication service for every incoming request. The authentication service determines if the client is authorized to proceed. If the external service returns a success code (2xx), the original request continues processing. If it returns an error (usually 401 or 403), NGINX can block the request, respond with an error, or redirect the client to a login page.

Setting Up the auth_request Module

First, ensure NGINX is compiled with the auth_request module. Most standard packages include it by default, but you can confirm by running:

nginx -V 2>&1 | grep --color auth_request

If it’s included, you’ll see the ‘–with-http_auth_request_module’ in the output.

Example Configuration

Here’s how you would set it up inside your server block:

location = /auth {
    internal;
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body  off;
    proxy_set_header        Content-Length "";
    proxy_set_header        X-Original-URI $request_uri;
}

location / {
    auth_request /auth;
    auth_request_set $auth_status $upstream_status;

    ...

    additional configuration for the original request...
}

This sets up a location that will handle authentication. The ‘internal’ directive ensures that this location can only be accessed internally by NGINX.

Below explains the code step-by-step:

1. The /auth location block defines where the sub-request will be sent to which in our case is an authentication service listening at http://auth-service/validate. This location is marked as ‘internal’ meaning it cannot be accessed directly by clients.
2. The ‘proxy_pass_request_body off;’ directive tells NGINX not to pass the body of the request to the authentication service, as typically authentication can be performed without it.
3. ‘proxy_set_header’ directives clear the Content-Length header since we’re not passing the body and also provide the X-Original-URI header, which is the URI of the original request.
4. In the / location, the ‘auth_request’ directive enables authentication checks for this location by sending sub-requests to the /auth location. If the auth service validates a request, it will proceed; otherwise, it will be denied.
5. The ‘auth_request_set’ directive captures an authentication server’s response status for further processing or logging.

Handling Failures

When authentication fails, it’s important to handle the unauthorized request gracefully. You can redirect to a login page using an error_page directive:

error_page 401 = @error401;

location @error401 {
    return 302 /login.html;
}

Here, any 401 errors would redirect the end-user to /login.html. Adjust this based on your application specifics.

Advanced Configuration Options

NGINX provides further directives for fine-tuning the auth_request module:

• auth_request_set: Sets variable values based on the header fields from a sub-request response.
• auth_request_pass: Specifies what header fields of the original request are passed to the sub-request. Defaults to passing Host and Connection.
• $auth_status: A variable indicating the status code of the authentication sub-request, this can be used in subsequent processing.

Security Considerations

While the auth_request module is convenient, you should consider various security aspects such as:

• Always serving authentication endpoints over SSL/TLS.
• Ensuring the authentication service is not accessible to the public.
• Sanitizing all headers and user data before passing them to avoid injection attacks.

Conclusion

In this guide, we’ve covered the fundamentals of NGINX’s auth_request module and how to implement authentication at the edge layer.

With practical examples and considerations, you are now better equipped to use NGINX’s auth_request module to create secure applications. Always test configurations in a staging environment and consult NGINX documentation for the latest features and best practices.

Remember that securing your applications is an ongoing process, and NGINX is a powerful ally to have on your side.