himelranaswe/forwardauth

By himelranaswe

•Updated 12 months ago

Kubernetes forward-auth tested on Traefik ingress

Image

Security

Developer tools

Web servers

1.1K

Overview Tags

himelranaswe/forwardauth repository overview

⁠Kubernetes: Traefik Forward Auth

A Python-based forward authentication service for Traefik that provides OAuth 2.0 authentication with GitHub integration and user whitelisting capabilities.

⁠Features

OAuth 2.0 Integration: Seamless GitHub authentication
User Whitelisting: Restrict access to specific users by email
Custom Forbidden Page: Beautiful HTML page for unauthorized users
Session Management: Secure cookie-based session handling
Traefik Integration: Works as a Traefik middleware for route protection
Docker Support: Containerized application with Docker image

⁠Quick Start

# Apply the deployment
kubectl apply -f traefik-forward-auth-deploy.yaml

Example of deploy file

apiVersion: apps/v1
kind: Deployment
metadata:
  name: forward-auth
  namespace: forward-auth
spec:
  replicas: 1
  selector:
    matchLabels:
      app: forward-auth-python
  template:
    metadata:
      labels:
        app: forward-auth-python
    spec:
      containers:
        - name: forward-auth-python
          image: himelranaswe/forwardauth:latest # or himelranaswe/forwardauth:arm for ARM cpu
          imagePullPolicy: Always
          ports:
            - containerPort: 4181
          env:
            - name: PROVIDER
              value: "github"
            - name: GITHUB_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: github-client-id
            - name: GITHUB_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: github-client-secret
            - name: OAUTH_SCOPES
              value: "read:user,user:email"
            - name: SECRET
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: secret
            - name: COOKIE_DOMAIN
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: cookie-domain
            - name: INSECURE_COOKIE
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: insecure-cookie
            - name: AUTH_HOST
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: auth-host
            - name: URL_PATH
              value: "/_oauth"
            - name: WHITELIST
              valueFrom:
                secretKeyRef:
                  name: traefik-forward-auth-secret
                  key: whitelist_users
---
apiVersion: v1
kind: Service
metadata:
  name: forward-auth
  namespace: forward-auth
spec:
  selector:
    app: forward-auth
  ports:
    - port: 4181
      targetPort: 4181

⁠Apply the secret with your configuration

kubectl apply -f traefik-forward-auth-secret.yaml


### 3. Configure Traefik Middleware

```yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: github-auth
  namespace: forward-auth
spec:
  forwardAuth:
    address: http://forward-auth-python.forward-auth.svc.cluster.local:4181
    trustForwardHeader: true
    authResponseHeaders:
      - X-Forwarded-User
      - X-Forwarded-Email

⁠Configuration

⁠Environment Variables

Variable	Description	Required	Default
`PROVIDER`	OAuth provider (github)	Yes	`github`
`GITHUB_CLIENT_ID`	GitHub OAuth Client ID	Yes	-
`GITHUB_CLIENT_SECRET`	GitHub OAuth Client Secret	Yes	-
`OAUTH_SCOPES`	OAuth scopes	No	`read:user,user:email`
`SECRET`	JWT signing secret	Yes	-
`COOKIE_DOMAIN`	Cookie domain	No	-
`INSECURE_COOKIE`	Use insecure cookies	No	`false`
`AUTH_HOST`	Auth service hostname	Yes	-
`URL_PATH`	OAuth callback path	No	`/_oauth`
`WHITELIST`	Comma-separated list of allowed emails	No	-

⁠Secret Configuration Example

apiVersion: v1
kind: Secret
metadata:
  name: traefik-forward-auth-secret
  namespace: forward-auth
type: Opaque
stringData:
  github-client-id: "your-github-client-id"
  github-client-secret: "your-github-client-secret"
  secret: "your-jwt-secret-key"
  cookie-domain: ".yourdomain.com"
  insecure-cookie: "false"
  auth-host: "auth.yourdomain.com"
  whitelist_users: "[email protected],[email protected]"

⁠GitHub OAuth Setup

⁠1. Create GitHub OAuth App

Go to GitHub Settings → Developer settings → OAuth Apps
Click "New OAuth App"
Fill in the details:
- Application name: Your App Name
- Homepage URL: https://yourdomain.com
- Authorization callback URL: https://auth.yourdomain.com/_oauth

⁠2. Get Client Credentials

After creating the OAuth app, you'll get:

Client ID: Copy this to GITHUB_CLIENT_ID
Client Secret: Copy this to GITHUB_CLIENT_SECRET

⁠Usage Examples

⁠Basic Traefik IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: protected-app
  namespace: your-namespace
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.yourdomain.com`)
      kind: Rule
      services:
        - name: your-app-service
          port: 80
      middlewares:
        - name: github-auth
          namespace: your-namespace
  tls:
    secretName: app-tls

⁠With Custom Middleware

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: github-auth
  namespace: your-namespace
spec:
  forwardAuth:
    address: http://forward-auth-python.forward-auth.svc.cluster.local:4181
    trustForwardHeader: true
    authResponseHeaders:
      - X-Forwarded-User
      - X-Forwarded-Email

⁠Authentication Flow

User Access: User visits protected application
Middleware Check: Traefik forwards request to forward-auth service
Session Validation: Service checks for valid session
OAuth Redirect: If no session, redirect to GitHub OAuth
GitHub Authentication: User authenticates with GitHub
Callback Processing: GitHub redirects back to /_oauth endpoint
User Validation: Service checks if user email is in whitelist
Access Decision:
- Allowed: User gets access to application
- Forbidden: User sees custom forbidden page

⁠Customization

⁠Custom Forbidden Page

The forbidden page template is located at templates/forbidden.html inside container. You can customize it by mounting volume:

Styling: Modify CSS in the template
Content: Change text and layout
Actions: Add custom buttons or links
Branding: Update footer and branding information

⁠Whitelist Management

Users are whitelisted by email address. The whitelist is configured via the WHITELIST environment variable:

# Single user
WHITELIST="[email protected]"

# Multiple users
WHITELIST="[email protected],[email protected],[email protected]"

⁠Security Considerations

Cookies are HTTP-only and secure by default
Use COOKIE_DOMAIN for proper domain scoping
Set INSECURE_COOKIE=false for HTTPS environments

⁠JWT Secret

Use a strong, random secret for JWT signing
Rotate the secret periodically
Store securely in Kubernetes secrets

⁠Network Security

Run forward-auth service in a secure namespace
Use network policies to restrict access
Ensure HTTPS for all external communications

⁠Troubleshooting

⁠Common Issues

⁠1. OAuth Redirect URI Mismatch

redirect url not appropriate with this application

Solution: Ensure the callback URL in GitHub OAuth app matches your AUTH_HOST:

https://auth.yourdomain.com/_oauth

⁠2. User Not Whitelisted

Symptoms: User sees forbidden page after successful GitHub authentication

Solution: Add user's email to the WHITELIST environment variable

⁠Debugging

⁠Check Logs

kubectl -n forward-auth logs -l app=forward-auth

⁠Verify Configuration

kubectl -n forward-auth get secret traefik-forward-auth-secret -o yaml

⁠Test Authentication Flow

curl -I https://your-protected-app.com/

⁠API Endpoints

Endpoint	Method	Description
`/verify`	GET	Traefik middleware endpoint
`/start`	GET	Initiate OAuth flow
`/_oauth`	GET	OAuth callback endpoint
`/logout`	GET	Clear session and logout

⁠Development

Currently only support Github OAuth. You can modify and use as you like. Repo: https://github.com/Swe-HimelRana/traefik-forward-auth⁠

⁠License

This project is licensed under the MIT License.

⁠Support

For issues and questions:

Create an issue in the repository [Github] (https://github.com/Swe-HimelRana/traefik-forward-auth⁠)
Contact: [email protected]⁠

⁠Changelog

⁠Version (latest and arm)

Initial Python implementation
GitHub OAuth integration
User whitelisting
Traefik middleware support
Enhanced security features
Support X64 [tag: latest] and ARM64 [tag: arm] Architecture (CPU)

⁠Security vulnerability Monitoring and Protection

# CVE-2025-45582
Our project’s Python base image has been flagged for CVE-2025-45582, a known tar archive extraction vulnerability.

✅ Impact on this project: None.
Our implementation does not use any tar extraction or related functionality, meaning this vulnerability cannot be exploited in the context of this project.

🔒 Status: Safe.
Although the underlying image reports the CVE, our usage of the image does not expose your environment to this vulnerability.

Tag summary

Recent tags

Content type

Image

Digest

sha256:b6c0ec8dd…

Size

47.1 MB

Last updated

12 months ago

docker pull himelranaswe/forwardauth