portainer-core/npm-configs

NPM Forward Auth Configuration Files

This directory contains Nginx configuration snippets for Nginx Proxy Manager (NPM) forward authentication with Authentik.

Files

organizr-forward-auth.conf

Status: 🧪 Testing Service: Organizr (home.schweitz.net) Purpose: First test deployment of forward auth to validate standalone outpost functionality

DO NOT APPLY TO OTHER SERVICES YET - This is a proof-of-concept deployment to verify:

• Standalone outpost works correctly
• No redirect loops occur
• SSO functions as expected
• Cookie domain settings are correct

Once proven stable, this configuration can be adapted for other services.

Deployment Strategy

Phase 1: Single Service Test (Current)

• ✅ Deploy to Organizr only
• ✅ Test all authentication flows
• ✅ Verify no issues for 24-48 hours

Phase 2: Gradual Rollout (After Phase 1 Success)

Services to protect (in order):

1. Core API (api.schweitz.net) - Use OIDC instead of forward auth
2. Nextcloud (cloud.schweitz.net)
3. Gitea (git.schweitz.net)
4. Jellyfin (media.schweitz.net)
5. Open WebUI, Netdata, etc.

Rule: Deploy to ONE service at a time, test for 24 hours before proceeding to next.

Important Notes

Services That Should NOT Have Forward Auth

• ❌ auth.schweitz.net - The Authentik server itself (causes redirect loops)
• ❌ Any service not listed in the gradual rollout plan

Before Applying Configuration

1. Create backup of NPM database
2. Have rollback procedure ready
3. Test in incognito window first
4. Monitor logs actively

Configuration Template Structure

All forward auth configs follow this structure:

# 1. Buffer sizes (required for large auth headers)
proxy_buffers 8 16k;
proxy_buffer_size 32k;

# 2. Auth request directive
auth_request /outpost.goauthentik.io/auth/nginx;
error_page 401 = @goauthentik_proxy_signin;

# 3. Capture auth response headers
auth_request_set $auth_cookie $upstream_http_set_cookie;
# ... (other headers)

# 4. Forward headers to application
add_header Set-Cookie $auth_cookie;
proxy_set_header X-authentik-username $authentik_username;
# ... (other headers)

# 5. Outpost proxy location
location /outpost.goauthentik.io {
    proxy_pass https://authentik-proxy:9443/outpost.goauthentik.io;
    # ... (proxy settings)
}

# 6. Signin redirect handler
location @goauthentik_proxy_signin {
    internal;
    return 302 https://auth.schweitz.net/outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
}

Monitoring During Rollout

After applying forward auth to any service, monitor:

1. Authentik Proxy Logs:

   docker logs authentik-proxy -f
   

2. NPM Logs:

   docker logs npm -f
   

3. Service-Specific Logs:

   docker logs <service-name> -f
   

4. Memory Usage:

   docker stats authentik-proxy --no-stream
   

Success Criteria

Before proceeding to next service:

• ✅ No redirect loops
• ✅ Authentication works consistently
• ✅ Logout works correctly
• ✅ No errors in logs
• ✅ No memory leaks or performance issues
• ✅ SSO cookie persists across sessions

Rollback Procedure

If issues occur with ANY service:

1. Edit the proxy host in NPM
2. Go to Advanced tab
3. Delete the forward auth configuration
4. Save
5. Service will be accessible without authentication again
6. Investigate logs and fix issues before re-applying

---

Last Updated: 2025-11-21 Authentik Version: 2024.8.4 Outpost Type: Standalone (authentik-proxy container)