Forward Auth (Deprecated)

danger

Starting v0.21.0, Pomerium will no longer support Forward Auth. Supporting Forward Auth requires Pomerium to route requests from third-party proxies to make access control decisions. This goes against zero-trust principles as specified in the BeyondCorp model, which states that all traffic should flow through a single proxy.

• Environmental Variable: FORWARD_AUTH_URL
• Config File Key: forward_auth_url
• Type: URL (must contain a scheme and hostname)
• Example: https://forwardauth.corp.example.com
• Resulting Verification URL: https://forwardauth.corp.example.com/?uri={URL-TO-VERIFY}
• Optional

Forward authentication creates an endpoint that can be used with third-party proxies that do not have rich access control capabilities (nginx, nginx-ingress, ambassador, traefik). Forward authentication allows you to delegate authentication and authorization for each request to Pomerium.

Request flow

Examples

NGINX Ingress

Some reverse-proxies, such as nginx split access control flow into two parts: verification and sign-in redirection. Notice the additional path /verify used for auth-url indicating to Pomerium that it should return a 401 instead of redirecting and starting the sign-in process.

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: verify
  annotations:
    kubernetes.io/ingress.class: 'nginx'
    certmanager.k8s.io/issuer: 'letsencrypt-prod'
    nginx.ingress.kubernetes.io/auth-url: https://forwardauth.corp.example.com/verify?uri=$scheme://$host$request_uri
    nginx.ingress.kubernetes.io/auth-signin: 'https://forwardauth.corp.example.com/?uri=$scheme://$host$request_uri'
spec:
  tls:
    - hosts:
        - verify.corp.example.com
      secretName: quickstart-example-tls
  rules:
    - host: verify.corp.example.com
      http:
        paths:
          - path: /
            backend:
              serviceName: verify
              servicePort: 80

Traefik docker-compose

If the forward_auth_url is also handled by Traefik, you will need to configure Traefik to trust the X-Forwarded-* headers as described in the documentation.

version: '3'

services:
  traefik:
    # The official v2.2 Traefik docker image
    image: traefik:v2.2
    # Enables the web UI and tells Traefik to listen to docker
    command:
      - '--api.insecure=true'
      - '--providers.docker=true'
      - '--entrypoints.web.address=:80'
      - '--entrypoints.web.forwardedheaders.insecure=true'
    ports:
      # The HTTP port
      - '80:80'
      # The Web UI (enabled by --api.insecure=true)
      - '8080:8080'
    volumes:
      # So that Traefik can listen to the Docker events
      - /var/run/docker.sock:/var/run/docker.sock
  verify:
    # A container that exposes an API to show its IP address
    image: pomerium/verify:latest
    labels:
      - 'traefik.http.routers.verify.rule=Host(`verify.corp.example.com`)'
      # Create a middleware named `foo-add-prefix`
      - 'traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=x-pomerium-claim-email,x-pomerium-claim-id,x-pomerium-claim-groups,x-pomerium-jwt-assertion'
      - 'traefik.http.middlewares.test-auth.forwardauth.address=http://forwardauth.corp.example.com/?uri=https://verify.corp.example.com'
      - 'traefik.http.routers.verify.middlewares=test-auth@docker'