How to Configure a Proxy Provider for Reverse Proxy Authentication in Authentik

Use authentik's Proxy Provider with an outpost to protect applications that don't support native authentication protocols by inserting a reverse-proxy layer for OAuth2-based session validation.

The Proxy Provider in authentik enables you to secure legacy applications or services that lack built-in OIDC, SAML, or LDAP support. By deploying a lightweight authentik outpost alongside your application, you can enforce authentication at the reverse-proxy layer without modifying the upstream service.

Understanding the Proxy Provider Architecture

Core Model and Modes

The Proxy Provider is defined in authentik/providers/proxy/models.py (lines 73-99). This model stores critical routing parameters:

• external_host — The public URL users access
• internal_host — The upstream service URL (required for Proxy mode)
• mode — One of three ProxyMode values that determine how traffic flows

The three operation modes are:

Mode	Use Case	Traffic Flow
Proxy	Dedicated outpost per application	All traffic routes through outpost
Forward Single	Existing reverse proxy for single app	Only authentication checks forwarded to outpost
Forward Domain	Wildcard/domain-level protection	Single outpost handles multiple subdomains

OAuth2 Integration

The Proxy Provider inherits from OAuth2Provider, implementing the standard Authorization Code flow. The model automatically configures:

• Default scopes via set_oauth_defaults() including the ak_proxy scope
• Callback URL generation through _get_callback_url() pointing to /outpost.goauthentik.io/callback

Outpost Deployment Options

The authentik outpost runs as a standalone Go service (internal/web/proxy.go) and connects to your authentik instance. You can deploy it as:

• Embedded outpost — Runs within the main authentik container (simpler, single-node)
• Dedicated outpost — Separate container or Kubernetes deployment (scales independently)

Step-by-Step Configuration

1. Create the Proxy Provider and Application

Navigate to Applications → New Application in the authentik admin UI. Select Proxy Provider as the provider type, assign a name, and choose an authentication flow.

Programmatic creation is also supported:

from authentik.providers.proxy.models import ProxyProvider, ProxyMode

provider = ProxyProvider.objects.create(
    name="MyApp Proxy",
    external_host="https://myapp.example.com",
    internal_host="http://myapp-internal:8080",
    mode=ProxyMode.PROXY,
    intercept_header_auth=True,
)

provider.set_oauth_defaults()  # Automatically configures OAuth2 parameters

provider.save()

2. Select the Appropriate Proxy Mode

Choose your mode based on your infrastructure:

• Proxy mode — Deploy when you can point DNS directly to the outpost or place it behind your load balancer. The outpost handles all traffic forwarding.
• Forward auth (single application) — Use with NGINX auth_request or Traefik ForwardAuth for a single protected application.
• Forward auth (domain level) — Configure once to protect multiple subdomains (*.internal.example.com) with a single outpost.

3. Configure Host Settings

In the provider configuration:

• Set External host to the public-facing URL (e.g., https://dashboard.example.com)
• Set Internal host to the upstream service (e.g., http://dashboard-service:8080) — required only for Proxy mode

These values map directly to the external_host and internal_host fields in the model.

4. Deploy and Assign an Outpost

Go to Applications → Outposts and create a Proxy outpost. Attach your application to this outpost.

For Kubernetes deployments, use the official outpost image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: authentik-outpost-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: authentik-outpost-proxy
  template:
    metadata:
      labels:
        app: authentik-outpost-proxy
    spec:
      containers:
        - name: outpost-proxy
          image: ghcr.io/goauthentik/outpost:latest
          args: ["proxy"]
          env:
            - name: AUTHENTIK_URL
              value: "https://authentik.example.com"
            - name: AUTHENTIK_TOKEN
              valueFrom:
                secretKeyRef:
                  name: authentik-token
                  key: token

The outpost connects to your authentik instance and begins handling authentication requests.

5. Configure Your Reverse Proxy

NGINX (Proxy Mode)

Route all traffic to the outpost:

server {
    listen 443 ssl;
    server_name myapp.example.com;

    location / {
        proxy_pass http://authentik-outpost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

See website/docs/add-secure-apps/providers/proxy/_nginx_standalone.md for complete examples.

Traefik (Forward Auth Mode)

Route only authentication checks:

http:
  middlewares:
    authentik:
      forwardAuth:
        address: "http://authentik-outpost:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-authentik-username
          - X-authentik-groups

Reference website/docs/add-secure-apps/providers/proxy/_traefik_ingress.md for Ingress-specific configurations.

6. Verify Access

Open your External host URL in a browser. Unauthenticated users are redirected to your selected authentication flow, then returned to the application with session cookies set. The outpost validates these cookies on subsequent requests.

Reverse Proxy Configuration by Mode

Mode	Reverse Proxy Requirement	Outpost Location
Proxy	Point external_host DNS to outpost	Public-facing or behind load balancer
Forward Single	Route /outpost.goauthentik.io to outpost	Internal, accessible by reverse proxy
Forward Domain	Route *.external_host/outpost.goauthentik.io to outpost	Internal, handles multiple domains

Key Implementation Files

Understanding these source files helps with troubleshooting and customization:

• authentik/providers/proxy/models.py — Core ProxyProvider model with ProxyMode enum and set_oauth_defaults() method
• authentik/providers/proxy/api.py — REST API serializers and viewsets for provider management
• internal/web/proxy.go — Go outpost implementation handling session validation and request forwarding
• website/docs/add-secure-apps/providers/proxy/create-proxy-provider.md — Complete user-facing documentation

Summary

• The Proxy Provider protects non-OIDC applications through reverse-proxy authentication using OAuth2 flows
• Three proxy modes (proxy, forward_single, forward_domain) adapt to different infrastructure layouts
• The authentik outpost validates sessions in Go and forwards traffic or authentication results to your application
• Configuration requires setting external_host and internal_host in the provider, deploying an outpost, and routing traffic appropriately
• All OAuth2 defaults are applied automatically via set_oauth_defaults() in the provider model

Frequently Asked Questions

What is the difference between Proxy mode and Forward auth mode?

Proxy mode routes all application traffic through the authentik outpost, which then forwards to your upstream service. Forward auth modes use your existing reverse proxy to handle traffic, only forwarding authentication verification requests to the outpost. Proxy mode is simpler to configure but requires the outpost to handle all traffic; Forward auth modes are more flexible for complex deployments but require reverse-proxy-specific configuration.

Can I use the authentik Proxy Provider with any reverse proxy?

Yes. The outpost exposes standard HTTP endpoints that work with NGINX, Traefik, Caddy, Envoy, and others. For Proxy mode, any reverse proxy that can forward to an upstream works. For Forward auth, you need a reverse proxy supporting authentication delegation (like NGINX auth_request, Traefik ForwardAuth, or Caddy's forward_auth).

How does session validation work in the Proxy Provider?

The outpost maintains an encrypted session cookie (authentik_proxy). On each request, it validates this cookie against the authentik core API. If valid, the request proceeds with headers injected (X-authentik-username, X-authentik-groups). If invalid or missing, the user is redirected through the OAuth2 flow starting at /outpost.goauthentik.io/start.

Do I need a separate outpost for each application?

Not necessarily. In Proxy mode, each application typically needs its own outpost instance because the outpost binds to specific external_host/internal_host pairs. In Forward Domain mode, a single outpost can protect multiple subdomains. For Forward Single mode, you can reuse an outpost across applications if they share the same authentication requirements and your reverse proxy routes correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}