Authelia

https://www.authelia.com/

Repository Layout

This is a Kubernetes deployment repo managed by ArgoCD. Edit kustomization.yaml, values.yaml, resources/, or patches/ directly. ArgoCD syncs from the repository root.

To render manifests locally (uses the same image as CI and ArgoCD):

./kustomize-build.sh

Integration Methods

Authelia supports two primary integration patterns for applications:

1. OpenID Connect (OIDC) Integration (Recommended for Complex Applications)

Use Case: Applications with built-in OIDC support that need user identity information.

Currently Integrated Applications:

• GitLab: Full OIDC integration with auto sign-in
• Nextcloud: OIDC login app with admin privilege mapping
• WikiJS: OIDC authentication with custom endpoint

Benefits:

• User identity propagation (username, email, groups)
• Custom claims and role mapping
• Logout integration
• Application-specific authorization

2. Traefik ForwardAuth Middleware (For Simple Authentication)

Use Case: Applications without native OIDC support requiring basic authentication.

Available Middleware: authelia/forwardauth-authelia@kubernetescrd

Benefits:

• Simple authentication overlay
• No application configuration required
• Automatic user headers injection
• Centralized access control

Adding OIDC Integration to New Applications

Step 1: Generate Client Credentials

Generate secure client credentials using Authelia's recommended approach:

# Generate client ID (72 characters from RFC3986 unreserved character set)
docker run --rm authelia/authelia:latest authelia crypto rand --length 72 --charset rfc3986

# Generate client secret (use strong random generation)
docker run --rm authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric

Step 2: Configure Authelia Client Registration

Add the new client to authelia/development/values.yaml:

identity_providers:
  oidc:
    clients:
      - client_name: "Application Name"
        client_id: "generated-client-id-72-chars"
        client_secret:
          path: "/secrets/oidc-clients/app_digest"  # Reference to secret (see Step 3)
        authorization_policy: "one_factor"  # or "two_factor" for enhanced security
        redirect_uris:
          - "https://app.xarif.de/auth/callback"  # Application-specific callback
        require_pkce: true  # Enable PKCE for security
        token_endpoint_auth_method: "client_secret_basic"  # or "client_secret_post"

Step 2 and 4 are dependent on the client itself. Start visiting the Authelia Client Integration Guide to check for configuration about your client.

Step 3: Add Client Secret to SOPS-Encrypted Configuration

Update authelia/development/resources/oidc-clients-secret.yaml:

# Add to the existing secret structure
app_digest: ENC[AES256_GCM,data:hash-of-client-secret,iv:...,tag:...,type:str]

Step 4: Configure Application OIDC Settings

Common OIDC Configuration Parameters:

• Provider URL: https://auth.xarif.de
• Discovery Endpoint: https://auth.xarif.de/.well-known/openid-configuration
• Scopes: openid profile email groups
• PKCE: Enabled
• Client Authentication: Basic or POST method

Example Application Configurations:

Nextcloud (oidc_login app):

'oidc_login_provider_url' => 'https://auth.xarif.de',
'oidc_login_client_id' => 'your-client-id',
'oidc_login_client_secret' => 'your-client-secret',
'oidc_login_scope' => 'openid profile email groups',
'oidc_login_button_text' => 'Log in with Authelia',

GitLab (omnibus config):

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Authelia", 
    args: {
      issuer: "https://auth.xarif.de",
      discovery: true,
      scope: ["openid","profile","email","groups"],
      client_options: {
        identifier: "your-client-id",
        secret: "your-client-secret"
      }
    }
  }
]

Official Authelia Client Integration Guides

https://www.authelia.com/integration/openid-connect/clients/

Adding ForwardAuth Protection to Applications

• The Authelia Helm chart automatically deploys the Traefik ForwardAuth middleware (forwardauth-authelia) in the authelia namespace.
• This middleware is immediately available for use without additional configuration.
• Documentation of the Authelia integration with Traefik: https://www.authelia.com/integration/proxies/traefik/
• Documentation of creating Ingress resources in the xarif.de Kubernetes Cluster: https://git.xarif.de/kubernetes/traefik/src/branch/main/README.md#creating-ingress-resources

Method 1: Standard Kubernetes Ingress

Add middleware annotation to existing ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: protected-app
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: authelia-forwardauth-authelia@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
  - host: app.xarif.de
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Method 2: Traefik IngressRoute

Add middleware reference to IngressRoute:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: protected-app
spec:
  entryPoints:
    - web
    - websecure
  routes:
    - match: Host(`app.xarif.de`) && PathPrefix(`/`)
      kind: Rule
      middlewares:
        - name: forwardauth-authelia
          namespace: authelia
      services:
        - name: app-service
          port: 80

Add new users to Authelia

sops development/resources/users-secret.yaml

Passwords must be set by the "Forgot Password" function initially.

User Database: File-based configuration in SOPS-encrypted secret

Example User Configuration:

users:
  username:
    displayname: "Display Name"
    email: user@domain.com
    groups:  # Optional
      - users
      - specific-app-users

Security Considerations

1. Client Secret Security: Always use SOPS encryption for client secrets
2. PKCE Enabled: Required for all OIDC clients for security
3. Secure Redirects: Only allow HTTPS redirect URIs matching *.xarif.de
4. Token Security: Use client_secret_basic authentication when possible
5. Access Control: Define appropriate authorization policies per application

Troubleshooting

Common Integration Issues:

1. OIDC Discovery Failures: Verify https://auth.xarif.de/.well-known/openid-configuration
2. Redirect URI Mismatch: Ensure exact match between Authelia config and application
3. Client Secret Issues: Use only alphanumeric characters for compatibility
4. ForwardAuth Headers: Check Remote-User header injection in application logs
5. Cross-Namespace Middleware: Ensure Traefik allowCrossNamespace enabled

Useful Commands:

# Check Authelia logs
kubectl logs -n authelia deployment/authelia

# Verify middleware availability
kubectl get middleware -n authelia

# Test OIDC discovery endpoint
curl https://auth.xarif.de/.well-known/openid-configuration

Documentation References

• Authelia Integration Guide: https://www.authelia.com/integration/prologue/introduction/
• OIDC Client Examples: https://www.authelia.com/integration/openid-connect/clients/
• Traefik ForwardAuth: https://www.authelia.com/integration/proxies/traefik/
• Kubernetes Integration: https://www.authelia.com/integration/kubernetes/traefik-ingress/