Zum Inhalt

OAuth2 Proxy role

Deploy OAuth2 Proxy containers to protect services with OIDC authentication via Authentik or Zitadel identity providers.

Usage

Create a variable file for each service you want to protect:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# vars/service_name.yml
oauth2_proxy_container_name: oauth2-servicename
oauth2_proxy_client_id: service-client-id-from-idp
oauth2_proxy_client_secret: service-client-secret-from-idp
oauth2_proxy_cookie_secret: randomly-generated-secret-32chars
oauth2_proxy_upstream: http://service.example.com
oauth2_proxy_redirect_url: https://service.example.com/oauth2/callback
oauth2_proxy_issuer_url: https://authentik.rwcloud.ch/application/o/servicename
oauth2_proxy_whitelist_domains: example.com
oauth2_proxy_cookie_domains: example.com

Include the role in your playbook with the appropriate variable file:

1
2
3
4
5
6
7
# playbooks/proxmox/deploy_docker_services.yml
- hosts: docker_services
  vars_files:
    - ../vars/oauth2_wiki.yml
  roles:
    - role: oauth2_proxy
      tags: oauth2-wiki

The role provides these tags: - oauth2-proxy-install - Deploy OAuth2 Proxy container - oauth2-proxy-uninstall - Remove OAuth2 Proxy container - Service-specific tags (e.g., oauth2-wiki)

Docs

Deploy OAuth2 Proxy for a specific service (example: wiki):

1
2
3
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml \
  --vault-password-file ./.vault_pass \
  --tags oauth2-wiki,oauth2-proxy-install

Remove OAuth2 Proxy for a service:

1
2
3
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml \
  --vault-password-file ./.vault_pass \
  --tags oauth2-wiki,oauth2-proxy-uninstall

Configuration Details

The role deploys OAuth2 Proxy with: - Official Image: bitnami/oauth2-proxy:latest - Provider: OIDC (OpenID Connect) - Network: Connects to caddy_old network - Port: 4180 (internal) - Authentication: Integrated with Authentik/Zitadel

Architecture

Each protected service requires its own OAuth2 Proxy container with unique configuration:

  1. User requests protected service → Redirected to OAuth2 Proxy
  2. OAuth2 Proxy → Redirects to Identity Provider (Authentik/Zitadel)
  3. User authenticates → IDP redirects back with token
  4. OAuth2 Proxy validates token → Sets secure cookie
  5. Subsequent requests → Proxy validates cookie and allows access

Environment Variables

Key configuration options: - OAUTH2_PROXY_PROVIDER=oidc - Use OpenID Connect - OAUTH2_PROXY_EMAIL_DOMAIN=* - Allow any email domain - OAUTH2_PROXY_COOKIE_SECURE=true - HTTPS-only cookies - OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true - Auto-redirect to IDP - OAUTH2_PROXY_CODE_CHALLENGE_METHOD=S256 - PKCE for security - OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER=true - Forward auth headers - OAUTH2_PROXY_PASS_ACCESS_TOKEN=true - Pass access token to upstream

Setting Up a New Protected Service

  1. Register application in IDP (Authentik/Zitadel)
  2. Name: Your service name
  3. Redirect URI: https://service.example.com/oauth2/callback

  4. Note the Client ID and Client Secret

  5. Generate cookie secret 

    1
    python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'

  6. Create variable file (e.g., vars/oauth2_myservice.yml) 

    1
2
3
4
5
6
7
8
9
    oauth2_proxy_container_name: oauth2-myservice
oauth2_proxy_client_id: myservice-client-id
oauth2_proxy_client_secret: myservice-client-secret
oauth2_proxy_cookie_secret: your-generated-secret
oauth2_proxy_upstream: http://myservice:8080
oauth2_proxy_redirect_url: https://myservice.example.com/oauth2/callback
oauth2_proxy_issuer_url: https://authentik.rwcloud.ch/application/o/myservice
oauth2_proxy_whitelist_domains: example.com
oauth2_proxy_cookie_domains: example.com

  7. Configure Caddy/Traefik to route through OAuth2 Proxy 

    1
2
3
4
5
6
7
    myservice.example.com {
    forward_auth oauth2-myservice:4180 {
        uri /oauth2/auth
        copy_headers X-Auth-Request-User X-Auth-Request-Email
    }
    reverse_proxy myservice:8080
}

  8. Deploy with Ansible 

    1
2
    ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_services.yml \
  --tags oauth2-myservice,oauth2-proxy-install

Variable Files

Each protected service needs its own variable file in the vars/ directory: - vars/oauth2_wiki.yml - vars/oauth2_dashboard.yml - vars/oauth2_grafana.yml - etc.

Security Features

OAuth2 Proxy provides: - OIDC authentication - Secure cookie-based sessions - PKCE (Proof Key for Code Exchange) - Authorization header forwarding - Access token passing to upstream - Domain whitelisting - Secure cookies (HTTPS only)

Troubleshooting

Common issues:

Redirect loop: Check that oauth2_proxy_redirect_url matches IDP configuration

Cookie not set: Verify oauth2_proxy_cookie_domains matches your domain

403 Forbidden: Check oauth2_proxy_whitelist_domains includes your domain

IDP errors: Verify oauth2_proxy_issuer_url is correct and reachable