How authentik forward auth with NGINX auth_request works for legacy apps
With auth_request, NGINX sends a subrequest for every incoming request to an authentik outpost before it forwards the request to the application. The outpost answers with allow or deny: if the visitor has an authentik session that satisfies the policies bound to the application, NGINX passes the request upstream, and if not, the visitor is redirected to the authentik login flow. This suits an application that has no OIDC or SAML support and cannot be changed to speak either protocol, but still needs its users to sign in through the same authentik instance as the rest of the estate. Teams usually pick this pattern when the application is a vendor product or an internal tool with no maintained code path for SSO, when a native integration would require modifying code they do not own, or when they want one access policy point in front of several small web apps.
The authentik proxy provider is the documented provider type for this job, and it covers authentication and authorization at the HTTP edge: it decides who may reach a host or path and, depending on configuration, which identity headers the application receives. It does not make the application itself understand identity. Applications that trust headers must be kept unreachable except through NGINX, or a user could forge those headers, and that restriction is a network design task your team owns. The proxy provider also does not replace native SSO for applications that can consume OIDC, SAML or LDAP directly, and it does not manage the application's own roles or sessions. Before you commit, confirm with the authentik provider documentation linked from the authentik providers reference which proxy modes and header behavior match your version, and check that every route you plan to protect is covered by the provider definition.
The rest of the pattern depends on where the outpost runs and how NGINX reaches it. Your first design decision is whether the outpost is the one embedded in the authentik server or a standalone proxy outpost placed close to the application, since that choice changes the URL NGINX calls and the trust boundary between them. Your second decision is the cookie domain and whether one provider covers a single application or a shared parent domain, because that determines how sessions are shared across hostnames. Plan a test environment where you can confirm redirects, session expiry and header values end to end before any production host is switched to auth_request.
What the outpost location and auth_request subrequest do
With auth_request, NGINX does not ask authentik whether to allow a request in the same breath as serving it. Before it hands a request to the application, NGINX sends an internal subrequest to an authentication location, and the response code decides what happens next. A 2xx response lets the original request continue to the upstream, while a 401 or 403 stops it. The key design point is that the outpost, not the application, makes that allow or deny decision. The application behind NGINX never sees an unauthenticated request for a protected path, and it never needs to know that authentik exists. Your NGINX configuration needs one internal location that proxies the subrequest to the authentik outpost path, plus the auth_request directive on each protected location that references it. Confirm the exact outpost path, the required host header and the forwarded headers against the forward auth documentation for your authentik version before you copy any snippet, because these paths have changed across releases.
Architecturally, the endpoint NGINX calls is served by the authentik server container, which runs core plus an embedded outpost. The worker container handles background tasks, and PostgreSQL stores configuration, sessions and the data the decision depends on, so a slow or unavailable database affects every protected application at once. The subrequest is also on the hot path: each protected request triggers a check, so latency in the authentik server appears as latency in every application it guards. Plan for the server to be reachable from the NGINX host over the network you have chosen, and decide whether the embedded outpost on the server container is sufficient for your traffic or whether a standalone proxy outpost should handle these checks. The Docker Compose and Kubernetes guides describe the server and worker containers and the external PostgreSQL you should plan for in production. Confirm the current architecture in the authentik architecture documentation before you size the NGINX-to-authentik path.
Which NGINX forward auth configuration fits each situation
This table compares the main configuration choices for protecting NGINX-served applications with authentik, including provider scope, outpost placement, NGINX versus ingress-nginx, and header handling. Read each row for the situation that fits, then check the trade-off before you commit to a layout.
| Decision | When it fits | Trade-off to weigh |
|---|---|---|
| Single-application provider | One hostname or a small number of apps with different access rules | One provider and outpost route per app, so more configuration to maintain as apps grow |
| Domain-level provider | Many apps under one parent domain that share the same sign-in and access policy | Cookie scope and authorization are shared across apps, so per-app policy needs extra care |
| Embedded outpost | Small deployments where the authentik server already reaches the NGINX host and you want fewer moving parts | The outpost shares the server container, so you must confirm it is reachable from NGINX and decide whether to keep it enabled |
| Standalone proxy outpost | Outposts placed near applications, separate network zones, or hosts that must not reach the authentik server directly | Another container to deploy, token management and upgrades to keep in step with authentik |
| Plain NGINX auth_request | Hosts where you manage nginx.conf directly and want explicit control over locations and headers | Every outpost location, header and redirect rule is written by hand and must be tested on each change |
| ingress-nginx annotations | Kubernetes clusters already routing through ingress-nginx, where annotations express the auth endpoint and headers | Behavior depends on the controller version and annotation set, so confirm the annotations against your controller documentation |
| Identity headers passed upstream | Applications that read the signed-in user from request headers and cannot do their own login | Apps must be unreachable except through NGINX, or a client could forge the headers |
| Session and redirect handling | Browser users who should land on the login page and return to the original URL after sign-in | Redirect and cookie domain settings must match the public hostname exactly, or sign-in loops appear |
Setting up auth_request with an authentik proxy provider
This sequence connects one NGINX-served application to authentik so that NGINX asks authentik whether each request is allowed before it reaches the application. When it is finished, unauthenticated users are sent to sign in, signed-in users with access reach the application with identity headers, and sessions can be ended centrally.
Create the proxy provider and application
An administrator in authentik creates a proxy provider in forward auth mode for the public hostname of the application, then creates an application that uses it and binds an access policy or group. Set the external host to the URL users open in the browser, and set the authorization flow to the one your team uses for sign-in. Check that the provider and application appear in the admin interface with the expected hostname and that the policy is bound. Confirm the mode (single application or domain level) matches the cookie scope you intend, because that choice affects every later step.
Deploy or confirm the outpost
Confirm that an outpost serving the proxy provider is running and reachable from the NGINX host. The embedded outpost in the authentik server can serve proxy providers, and a standalone proxy outpost is the usual choice when NGINX sits on a different host or network segment. Verify the outpost is connected to authentik in the admin interface and that its health shows as current. Record the address NGINX will use for the outpost path, because the next step depends on it. Consult the deployment guides for your installation method before changing any ports.
Add the outpost location to NGINX
On the NGINX server block for the application, add a location that matches the outpost path, such as the path authentik documents for the proxy, and proxy it to the outpost address with the Host header and the forwarded headers the outpost expects. Keep this location internal to the proxy and do not expose it to the application's own routes. Run the NGINX configuration test and reload only after it passes. Confirm that requesting the outpost path directly returns a response from authentik rather than a 404 from NGINX or the application.
Configure the auth_request subrequest
In the protected location block, add an auth_request directive that points to an internal authentication location, which proxies a subrequest to the outpost's authorization endpoint. The subrequest carries the original request's cookies and host so the outpost can decide. Confirm that the subrequest location is marked internal and that the protected location returns a redirect rather than the content when the subrequest is denied. Test the configuration with a request that has no session cookie and check that NGINX does not serve the application content.
Set the sign-in redirect and header passing
Use auth_request_set to read the identity headers returned by the outpost, such as the username, email, groups and any custom headers the provider sends, and pass them to the application with proxy_set_header. Configure the error_page or redirect handling for 401 and 403 responses so that unauthenticated users go to the authentik sign-in flow and return to the original URL afterward. Make sure the application trusts these headers only from NGINX, and that clients cannot send their own copies of them. Verify by signing in and checking that the application or a test endpoint receives the expected values.
Test allowed, denied and logged-out requests
Run three checks in a browser or with a command-line client. First, sign in as a user in the permitted group and confirm the application loads and receives identity headers. Second, sign in as a user outside the policy and confirm access is refused without exposing application content. Third, sign out in authentik, reload the application and confirm that the session is no longer accepted. Record each result, and repeat the check on the production hostname before opening access to users. Any mismatch in cookie domain or redirect URL usually points back to the provider's external host setting.
Using ingress-nginx annotations for authentik forward auth on Kubernetes
On Kubernetes, the ingress-nginx external authentication annotations send each request to the authentik outpost before it reaches the application. The authentik Kubernetes guide installs the server and worker with Helm, and the outpost service it creates is the target that the auth subrequest must reach. Confirm the outpost service name, namespace and port in your own Helm release, because the ingress annotations point at a full in-cluster address. The annotation names and their behavior also change between ingress-nginx releases, so check them against the version you run before copying any example. Treat the annotations as a starting point for a test cluster, not as a finished configuration.
Reachability is the first thing to verify. The auth URL must resolve from the namespace of the application's Ingress, which may be a different namespace from authentik. If they differ, the Service address needs the namespace in its DNS name, and any NetworkPolicy in either namespace must allow the ingress controller pods to reach the outpost port. Keep the outpost on the cluster network and do not expose it through a public Ingress just so the annotation can resolve. Also confirm which response headers ingress-nginx copies from the auth response to the upstream, since the identity headers you rely on for the application depend on that list being correct.
The Helm guide's bundled PostgreSQL is intended for demonstration and test environments, so a cluster built from the default chart values should not carry real users. For production, plan a separately managed PostgreSQL and point authentik at it before you move any application behind the annotations, because the outpost depends on the core service being healthy. Ask your platform team to confirm who owns the database, backup schedule and failover, and test a restore before go-live. Also record the authentik version you deploy, since the supported security release lines are published in the authentik security policy and the upgrade path determines when you change this configuration.
Security risks when NGINX trusts authentik headers
With auth_request, NGINX forwards identity decisions from authentik to the application, so the application trusts whatever headers reach it. The cards below cover the places where that trust breaks: a request that skips the proxy, client-supplied headers, cookie and TLS scope, the outpost endpoint, patch currency and audit evidence.
Bypassing the proxy
If the application port or its internal service is reachable without going through the NGINX location that runs auth_request, a client can send identity headers directly and the application will accept them. Confirm that the application listens only on a private interface or network, that firewall rules and Kubernetes network policies allow traffic only from the NGINX pods or host, and test a direct request with forged headers before go-live. The application must never be reachable except through NGINX.
Stripping client-supplied identity headers
NGINX must clear any identity header a client sends, such as the username or groups headers that authentik's auth response sets, before it adds the values from the outpost response. Otherwise a browser can supply its own value on a request that happens to pass a less strict location. Review every proxy_set_header line for the protected location, and confirm that the header names used by your authentik provider match the ones the application reads.
Cookie domain and TLS settings
The authentik session cookie is scoped by domain, so a cookie domain set too broadly can share sessions with sibling applications you do not control. Serve every protected host over HTTPS, set the cookie attributes your provider configuration calls for, and confirm that plain HTTP requests for protected paths are redirected rather than answered. Check these settings in the browser after each change, not only in the configuration file.
Protecting the outpost endpoint
The /outpost.goauthentik.io/ path and the auth endpoint that NGINX calls internally should not be reachable from the public internet as a general service, and the outpost should not be exposed to users in ways the design does not intend. Restrict the internal auth location with allow and deny or network rules, and confirm which paths are public in your configuration. Ask your team to document each location block that touches authentik.
Upgrading within supported versions
authentik publishes a security policy that lists the versions receiving security fixes, and it announces security releases at least 24 hours in advance. Your NGINX-side auth configuration and the authentik server and outpost must move together, so a version that falls out of support leaves the forward auth path unpatched. Subscribe to the release feed, track which versions are supported, and plan upgrades before a version drops off that list.
Logging auth decisions
Forward auth decisions happen at two layers: authentik records who signed in and which provider was evaluated, and NGINX records each request that reached the protected location and its status. Forward both sets of logs to a central store, keep the request ID or timestamp needed to correlate them, and alert on unusual patterns such as repeated 401 or 403 responses from one client. Confirm your retention period with your compliance owner, since authentik's own retention depends on your logging setup.
Questions teams ask before protecting NGINX apps with authentik
What does it cost to protect NGINX apps with authentik forward auth?
The cost is mainly the people time to design, configure, test and hand over the setup, plus the infrastructure that runs authentik and its outpost. Effort rises with the number of applications, how many distinct access policies they need, whether each app needs its own provider or a shared parent domain, and how many NGINX servers or environments must be covered. Infrastructure cost depends on your hosting choices and sizing. The authentik Docker Compose guide describes a host with at least 2 CPU cores and 2 GB of RAM as a starting point for test and small-scale production. Ask any partner for a fixed-scope quote that lists applications, environments, deliverables and what is excluded, since DeployOpen agrees scope and deliverables in writing before work starts.
How long does an authentik forward auth setup take?
Duration depends on inputs more than on the NGINX configuration itself. The main inputs are the number of applications, whether an identity source and MFA policy already exist in authentik, how many NGINX hosts and environments are involved, and how much testing and change control your organization requires. Before estimating, confirm which applications are in scope, which hostnames and paths they use, who owns DNS and TLS certificates, and whether a staging environment is available. A small single-application pilot is usually much shorter than a multi-domain rollout across production and staging. Ask for a timeline tied to these named inputs in the written scope.
Can our in-house team set up NGINX auth_request with authentik alone?
Yes, if your team already runs NGINX and authentik and has someone comfortable with reverse proxy configuration, cookies and redirects. The work is well bounded: an outpost location, an auth_request check, headers passed to the upstream, and a redirect to login for unauthenticated users. The risk areas are cookie domains, session handling across several hostnames, and making sure the application cannot be reached directly without passing through the proxy. Teams without this experience often spend most of their time on those edge cases. Be honest about the skills in the team, and consider an external review of the final configuration before production.
What do we need to provide for the engagement?
Plan to provide access and decisions rather than custom code. Typical inputs include:
- Administrative access to the authentik instance, or a named contact who can grant it
- Access to the NGINX hosts, their configuration files and a way to test changes
- The list of applications, their hostnames, paths and whether they already handle login
- Ownership of DNS records and TLS certificates for each hostname
- The access rules each application needs, such as group membership or MFA requirements
- A staging environment and a named approver for production changes
Identify these owners early, because delays usually come from waiting for them rather than from the configuration work.
Does authentik Open Source support forward auth with NGINX?
Confirm this against the current authentik documentation and the license for the version you plan to run. The project's repository places most code under the MIT license, while code in the enterprise directory uses a separate license. The pricing page lists Open Source as free with community support through Discord, and lists Google Workspace, Microsoft Entra ID, mTLS, privileged access management, enhanced audit logging and ticket-based support as Enterprise features. Forward auth through the proxy outpost is listed among provider types on the providers page, but verify which features you need against the edition documentation before you commit. Decide on edition based on the features your access model requires, and ask your partner to confirm them in writing.
How should we handle authentik and NGINX upgrades after go-live?
Treat upgrades as a recurring task with its own plan. Track the supported versions on the authentik security policy page, which lists the versions receiving security fixes, and note that security releases are announced at least 24 hours in advance. Review the release notes for each version you skip, since breaking changes can differ by release. The 2025.10 release notes, for example, describe removing Redis and a rise in PostgreSQL connections after upgrading, which affects capacity planning. Upgrade outposts alongside the server so their versions stay compatible, and test NGINX configuration changes in staging before production. Ask for an upgrade procedure and a support arrangement in the written scope, including who performs upgrades and who verifies login flows afterward.
How DeployOpen scopes and delivers NGINX forward auth
A forward auth rollout touches the reverse proxy, the authentik outpost, the applications behind it and the identity policy that decides who gets in. The cards below follow the order DeployOpen uses: agree the written scope, build inside your infrastructure, test both allow and deny paths, hand over documentation, then keep the setup current.
Written scope before work starts
Most engagements are fixed-scope, so the list of protected applications, hostnames, cookie domains and the authentik version is agreed in writing before any configuration changes. Expect the scope to name whether each application gets its own provider or shares a parent domain, because that choice changes the number of outpost paths and policies to build. Ask the quote to state which NGINX deployment is covered, whether it runs on bare metal, Docker or ingress-nginx, and who owns the TLS certificates.
Configuration in your infrastructure
The NGINX configuration, outpost deployment and authentik settings are applied in your environment, including your cloud accounts, data centers or air-gapped networks. Access to the reverse proxy and authentik admin interface is granted to the people who will run them after handover. Confirm which change-control process applies, how configuration is stored, and whether NGINX and authentik configuration will live in version control.
Allow and deny path testing
Forward auth fails quietly when the auth_request subrequest succeeds for the wrong users or fails for the right ones. Testing covers an unauthenticated request that must redirect to login, an authenticated user who is in the permitted group, and an authenticated user who is not, which must be refused. It also checks that identity headers reach the upstream application and that the application cannot be reached by bypassing NGINX. Ask for the test cases to be written down with expected results.
Documentation and handover
The handover pack records the NGINX locations, the outpost endpoint, the headers passed upstream, the policy bindings per application and the rollback steps. It also lists which settings must change together during an authentik upgrade, such as the outpost version and the server version. Ask for the documentation format, who receives it, and whether it is kept in your own repository so your team can maintain it without DeployOpen.
Retainers for upgrades and support
Forward auth depends on a matching outpost and server version, and authentik publishes security releases on a short notice window, so the setup needs ongoing attention. A retainer covers scheduled upgrades, reviewing security releases for the versions you run and answering support questions after go-live. Confirm the response expectations, which versions are in scope, and what is billed separately, such as major changes to the NGINX layout or new applications added later.
