Forward auth behind nginx auth_request, Traefik or Envoy

Who this page is for: the SSOGEN super administrator and the engineer who runs your ingress or reverse proxy. What you need first: an enrolled SSOGEN Gateway group (see Install and enroll an SSOGEN Gateway), the super administrator role, and an ingress that runs nginx (auth_request), Traefik (forwardAuth) or Envoy (ext_authz). Result: your ingress keeps serving the application, and before it forwards each request it asks the Gateway whether to let it through. People sign in to SSOGEN; the application does not change.

The examples use the fictional company Acme Corp. Acme serves its wiki at https://wiki.acme.example through its own nginx ingress, and its ingress identifies itself as ingress.acme.example.

How forward auth works

Forward auth is the App Proxy without the proxying. Your ingress stays in the request path and the Gateway only decides.

Step	What happens
1	A browser asks your ingress for https://wiki.acme.example/.
2	The ingress sends a check to the Gateway’s check port, over mutual TLS, describing the request.
3	With no session, the Gateway answers with a sign-in redirect. The person signs in to SSOGEN under the application’s policy.
4	With a valid session, the Gateway allows the request and returns the person’s identity. The ingress forwards the request to the application.
5	If the Gateway does not answer, the ingress refuses the request. Nothing opens by default.

A forward-auth listener has two ports: the check port, which only your ingress reaches, and a browser port for the Gateway’s own sign-in, callback and sign-out pages under /.ssogen/edge/ on the protected host. When SSOGEN ends a session or access is withdrawn, the next check refuses.

Compared with	Forward auth	Inline App Proxy route
Who forwards traffic to the application	Your ingress	The Gateway
Back-end servers, back-end sign-in, TLS settings on the route	None	Yes
Where TLS for the public host ends	Your ingress	The Gateway

1. Issue an origin certificate

1. Open Secure access, then Gateways, and go to your gateway group.
2. Under Listeners, select Issue an origin certificate. Give it a name and the host names your ingress dials to reach the Gateway.

SSOGEN signs it with your organization’s listener authority. The ingress checks the Gateway against this certificate.

2. Add the forward-auth listener

1. Under Listeners, select Add a listener and choose the kind forward-auth.
2. Pick the origin certificate from step 1 and enter the two ports.
3. In certificate mode, fill the authority that signs your ingress’s client certificate. For credentials issued by SSOGEN, select Use the SSOGEN listener authority.
4. Under Identities the ingress’s certificate must carry, add at least one DNS name or URI, for example ingress.acme.example. The save is refused without one.
5. Save the listener.

A group has one forward-auth listener. Open both ports on the Gateway host to your ingress only; see Gateway ports, firewall and sizing.

Network trust mode

The listener also offers a network mode, which trusts checks from listed source networks instead of a client certificate. An administrator must acknowledge it, and the acknowledgement is audited. Certificate mode is the one this guide uses.

3. Issue the ingress credential

1. On the listener’s row, select Issue ingress credential.
2. Choose one of the identities you listed in step 2.
3. Copy the certificate, the key and the authority to trust. They are shown once.

Install the three files where your ingress reads its upstream TLS settings. The ingress presents this certificate on every check.

4. Register the application

1. Open Applications, then App Proxy, and select Register App Proxy app.
2. Fill General, for example Name Acme Wiki.
3. On Connection, enter the Route ID you will give the route in step 5, for example route_acme_wiki, and the Gateway ID.
4. Choose the Sign-in policy, finish the wizard and select Activate application.
5. Assign the people or groups who may open it.

5. Create the forward-auth route

1. Open Secure access, then App Proxy routes, choose the Gateway group and select Add a route.
2. Pick the Application Acme Wiki.
3. Under Delivery, choose Forward-auth: your own ingress asks the Gateway whether to let each request through. The back-end, back-end sign-in and TLS sections disappear.
4. Enter the First hostname, the name your ingress serves: wiki.acme.example. Under Advanced, the path prefix defaults to /.
5. Leave Authentication required ticked unless the host must also be reachable without signing in.
6. Choose the sign-out scope (next section), then select Save and publish route.

The save places the route’s host names on the group’s forward-auth listener. The route list shows Forward-auth (your ingress) in the Backend column. An application has one route; add further host names under Hostnames.

6. Choose the sign-out scope

Under Delivery, the tick box Signing out of this application also signs the person out of SSOGEN sets what sign-out ends.

Choice	What sign-out ends	Next visit
Ticked (default)	The Gateway session, then the SSOGEN session	The person signs in again
Unticked	The Gateway session only	The person is signed straight back in by the SSOGEN session

After sign-out the person lands on the Gateway’s signed-out page, https://wiki.acme.example/.ssogen/edge/loggedout. You do not register this address; SSOGEN accepts exactly that page for the route’s host names.

7. Configure your ingress

Use the ingress configuration SSOGEN supplies for nginx, Traefik and Envoy, and edit only the host names, ports and certificate paths. It is tested against real nginx, Traefik and Envoy, and it already does the following:

• Describes the request itself. The ingress, not the client, tells the Gateway the URL, method, client address and host.
• Removes override headers. Path-override and method-override headers sent by a client never reach the check or the application.
• Protects identity. Identity values reach the application only from the Gateway’s answer; the Gateway’s session cookie never reaches the application.
• Fails closed. A Gateway that does not answer means a refused request.

Rules when you merge it into your own configuration:

• nginx. One protected application host per server block. A location that sets its own proxy_set_header lines must also include the protection file from the supplied configuration; otherwise nginx drops the Gateway’s values in that location.
• Traefik. Apply SSOGEN’s middlewares to each protected router in the order given. Set an entry-point write timeout, because Traefik’s forwardAuth has no timeout of its own. A StripPrefix or AddPrefix middleware goes after SSOGEN’s forward-auth middleware, never before it.
• Envoy. Merge all the supplied filters, in order, and the clusters.
• Caches. Anything that caches responses for the protected host (an nginx proxy_cache, a CDN) must be keyed by the person’s session or switched off for that host.
• Routing. Route /.ssogen/edge/ on the protected host to the Gateway’s browser port.

Check it worked

1. Open https://wiki.acme.example/ in a private window. You are sent to the SSOGEN sign-in page.
2. Sign in as an assigned person. You land on the page you asked for.
3. In the Admin Console, open Secure access, Gateways. The instance row shows the ingress self-check for the protected host.
4. Sign out from the application. With the default scope, opening the wiki again asks you to sign in.
5. Stop the Gateway service or block the check port. The wiki must stop answering, not open up.

Keys and sessions

Each gateway group has its own session and assertion keys for forward auth. Rotate session keys now on the group replaces them at once; everyone signed in to the group’s forward-auth applications signs in again.

On an organization hosted by SSOGEN, forward auth is switched on for your organization by SSOGEN, together with Gateways. Until it is on, a forward-auth listener cannot be saved. See Your hosted SSOGEN organization.

Troubleshooting

What you see	Why	What to do
The route save is refused because the group has no forward-auth listener, or more than one	A route’s host names go on the group’s one forward-auth listener.	Add one forward-auth listener (step 2), or remove the extra one.
The listener save is refused	No identity under Identities the ingress’s certificate must carry, or no authority in certificate mode.	Add a DNS name or URI, and select Use the SSOGEN listener authority.
That application already has a route	An application has exactly one route.	Add the host name to the existing route under Hostnames.
Every request is refused (nginx 500, Envoy 403)	The ingress cannot reach or trust the Gateway.	Check the check port in the firewall, the authority, the client certificate and the Gateway name in the ingress configuration.
Every request is refused with 403 and the Gateway log names a path-override or method-override header	Your ingress adds one of these headers to the check.	Use only the supplied check configuration. Do not add proxy_set_header X-Original-URI $request_uri; or an X-Forwarded-Uri or X-Forwarded-Prefix line from another product’s forward-auth guide. On Traefik, move StripPrefix or AddPrefix after SSOGEN’s middleware.
Every request signs in again	The Gateway’s cookie does not come back to it.	Route /.ssogen/edge/ on the protected host to the browser port.
421 from nginx	The request’s host is not the protected host of that server block.	Use one server block per protected host.
A request with ; in the path, or a percent-encoded letter or digit, is refused	The check refuses path spellings that could cross a route boundary.	Use a session cookie instead of a session id in the URL, and plain paths.
The application sees no identity on one nginx location	That location sets its own proxy_set_header and lacks the protection include.	Add the include to that location and to nested ones.
One person sees another person’s page	A cache in front of the protected host is not keyed by session.	Key it by session or switch caching off for that host.

Related guides

• Publish an internal app with the App Proxy
• What the SSOGEN Gateway does
• Gateway ports, firewall and sizing
• Reverse proxy security and TLS requirements