NginX GeoIP Setup Guide

Integrating NGINX with Web App Session Authentication and URL Whitelisting

This guide demonstrates how to restrict access using NGINX so that only a specific whitelist of endpoints is publicly available, while all other requests are validated against your web app’s session mechanism.

1. Overview

The setup leverages NGINX’s auth_request module to offload session/token validation to your backend. Requests to protected resources invoke an internal endpoint that inspects session cookies (or JWTs), returning a 200 status for authenticated sessions and a 401 otherwise. Unauthenticated requests are then redirected to your login page.

2. Architecture and Workflow

• Public Whitelist: Endpoints (e.g., /public1, /public2) bypass the auth check.
• Auth Check: Other endpoints trigger the auth_request directive.
• Internal Validation: A dedicated internal location (/auth) proxies the request to your web app’s session validation endpoint.
• Redirection: Unauthorized requests (401) are intercepted and redirected to the login page.

3. NGINX Configuration

Below is a sample configuration demonstrating the core components.

server {
    listen 80;
    server_name example.com;

    # Public endpoints – no auth required.
    location ~ ^/(public1|public2|public3) {
        try_files $uri $uri/ =404;
    }

    # Login endpoint for redirection.
    location /login {
        proxy_pass http://app_backend/login;
    }

    # All other endpoints require session validation.
    location / {
        auth_request /auth;
        error_page 401 = @redirect_to_login;
        proxy_pass http://app_backend;
    }

    # Internal endpoint for session validation.
    location = /auth {
        internal;
        proxy_pass http://app_backend/validate;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header Cookie $http_cookie;
    }

    # Redirect unauthorized users to the login page.
    location @redirect_to_login {
        return 302 /login;
    }
}

Explanation:

• Whitelist Block:
  The regex-based location ~ ^/(public1|public2|public3) ensures that these endpoints are served without session validation.

• Auth Request Directive:
  In the main location block, auth_request /auth; invokes the internal /auth location to perform session validation.
  The backend validation service examines cookies (or tokens) and returns 200 if valid, or 401 if not.

• Internal Validation Location:
  Marked with internal so it can’t be accessed directly by clients. The configuration strips the request body and forwards only the necessary headers (e.g., cookies) to your web app’s /validate endpoint.

• Error Handling:
  An error_page 401 directive catches unauthorized responses and reroutes them to a named location (@redirect_to_login), which issues a 302 redirect to /login.

4. Backend Considerations

Your web application’s /validate endpoint should:

• Inspect session cookies or tokens.
• Return a 200 status for authenticated sessions.
• Return a 401 status for non-authenticated requests.

For example, a lightweight endpoint in a Node.js/Express app might look like:

app.get('/validate', (req, res) => {
  if (req.session && req.session.user) {
    return res.sendStatus(200);
  }
  res.sendStatus(401);
});

Ensure your login endpoint and session management logic are aligned with this validation mechanism.

5. Testing and Debugging

• Access Public URLs: Confirm that URLs matching the whitelist are accessible without redirection.
• Test Protected Endpoints: Verify that non-authenticated requests trigger the auth check and are redirected to /login.
• Session Simulation: Use browser dev tools or curl with cookie headers to simulate authenticated and non-authenticated states.
• NGINX Logs: Monitor access and error logs for debugging issues related to auth_request or proxy configuration.