OIDC Auth Nginx Microservice

📖 Description

This project provides a microservice for OIDC authentication with Nginx. It is designed as a reverse proxy layer that enforces authentication before giving access to backend services (HTTP or WebSocket). The Nginx configuration files included in the project let you secure any service by plugging it behind the OIDC auth gateway.

---

🚀 Usage

1. Build and run

You can run the microservice via Docker:

docker-compose up --build

This starts:

• Nginx on ports 8000 (auth endpoints) and 8001 (protected example service).
• An auth backend handling OIDC logic (login, token validation, conditions).
• Example mock services to demonstrate how to protect an API and a WebSocket server.

---

2. Configure Nginx for your service

• Copy the provided configuration snippets (auth_service.conf, use_auth.conf).
• Adjust the URLs (proxy_pass, server_name, etc.) for your own service.
• Include the config in your nginx.conf to enable the OIDC auth check.

The flow is:

1. Requests to your service go through Nginx.
2. auth_request sends them to /sso/check.
3. If authorized → request is proxied to your backend.
4. If unauthorized → user is redirected to /sso/login.

---

3. Use $auth_params for fine-grained access control

The auth backend /sso/check endpoint supports conditional checks with the X-Conditions header, which Nginx sets using $auth_params.

Example:

location /ws {
    set $auth_params "not__service=QAE";
    auth_request /sso/check;
    error_page 401 = @login;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_pass http://my_websocket_backend;
}

Here:

• $auth_params sends conditions to the backend.
• Keys can use not__ for negation.
• The backend checks decoded token claims against these conditions and returns 200, 401, or 403 accordingly.

This makes it possible to restrict access to certain users, roles, or services based on claims in the OIDC token.

---

🔎 Endpoints

• GET /up → health check ({"status":"ok", "version":"1.0"})
• GET /sso/login → starts the login flow
• POST /sso/check → internal check used by Nginx auth_request
• Protected service examples available at port 8001 (HTTP + WebSocket)

---

📌 Notes

• The auth backend must implement OIDC logic (token validation, claim checking).
• The provided configs are examples: adjust them to fit your services.
• $auth_params allows attribute-based access control (ABAC) by passing conditions to the backend.

---

📜 License

MIT