OAuth2 Proxy¶

Aperçu¶

OAuth2 Proxy fournit une authentification centralisée pour les services AKKO dépourvus de support OIDC natif. Il agit comme passerelle d'authentification entre Traefik et les services backend, validant les sessions utilisateur auprès de Keycloak avant d'autoriser l'accès. Cela évite d'implémenter OAuth2/OIDC dans chaque service individuellement.

Architecture¶

  Navigateur ──→ Traefik (:443)
                     │
                     │  middleware forward-auth
                     ▼
             OAuth2 Proxy (:4180)
                     │
                     │  validation de session
                     ▼
                 Keycloak
               (fournisseur OIDC)
                     │
                     │  session valide → autoriser
                     ▼
             Service backend
           (Dashboards, MLflow, LiteLLM, Cockpit)

Le middleware forward-auth de Traefik envoie chaque requête entrante à OAuth2 Proxy pour validation. Si l'utilisateur a un cookie de session valide, la requête est transmise au backend. Sinon, l'utilisateur est redirigé vers la page de connexion de Keycloak.

Ports¶

Port	Fonction	Exposé
4180	HTTP — point d'accès du proxy d'authentification	Interne uniquement (accédé par le middleware Traefik)

Pas d'accès direct

Les utilisateurs n'accèdent jamais directement à OAuth2 Proxy. Traefik route les requêtes d'authentification vers lui de manière transparente via le middleware forward-auth.

Services protégés¶

Service	Pourquoi OAuth2 Proxy ?
Dashboards	Dashboards supporte OAuth nativement, mais OAuth2 Proxy fournit une gestion de session unifiée
MLflow	Aucune authentification intégrée — entièrement ouvert par défaut
LiteLLM	Passerelle API avec auth basique uniquement — nécessite une protection OIDC
Cockpit	Portail HTML/JS statique — aucune capacité d'authentification backend

Les services avec support OIDC Keycloak natif (JupyterHub, Superset, Airflow, Keycloak lui-même) gèrent l'authentification directement et n'utilisent pas OAuth2 Proxy.

Configuration¶

Fournisseur OIDC Keycloak¶

OAuth2 Proxy est configuré pour utiliser Keycloak comme fournisseur d'identité OIDC :

provider: keycloak-oidc
oidc-issuer-url: https://identity.akko.local/realms/akko
client-id: akko-oauth2-proxy
client-secret: ${OAUTH2_PROXY_CLIENT_SECRET}

cookie-name: _akko_oauth2
cookie-secret: ${OAUTH2_PROXY_COOKIE_SECRET}   # 32 octets aléatoires en base64
cookie-domain: .akko.local                      # partagé entre tous les sous-domaines
cookie-secure: true
cookie-samesite: lax

Le domaine du cookie doit correspondre

Le cookie-domain doit être défini sur le domaine de base partagé par tous les services (.akko.local en k3d). Si les services utilisent des domaines différents, le cookie de session ne sera pas partagé et les utilisateurs feront face à des demandes de connexion répétées.

Upstream et redirection¶

upstream: static://200                    # renvoyer 200 pour les sessions valides
redirect-url: https://cockpit.akko.local/oauth2/callback
email-domain: "*"                         # autoriser tous les domaines email

L'upstream static://200 signifie qu'OAuth2 Proxy ne proxifie pas le trafic lui-même — il valide uniquement la session et renvoie des en-têtes à Traefik.

Intégration Traefik¶

Le middleware forward-auth est défini comme un CRD Traefik :

middleware.yaml

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth2-proxy-forward-auth
spec:
  forwardAuth:
    address: http://akko-oauth2-proxy:4180/oauth2/auth
    trustForwardHeader: true
    authResponseHeaders:
      - X-Auth-Request-User
      - X-Auth-Request-Email
      - X-Auth-Request-Groups

Les services nécessitant une protection ajoutent cette annotation à leur Ingress :

traefik.ingress.kubernetes.io/router.middlewares: >-
  akko-oauth2-proxy-forward-auth@kubernetescrd

Chart Helm¶

OAuth2 Proxy est déployé via le sous-chart personnalisé akko-oauth2-proxy :

helm/akko/charts/akko-oauth2-proxy/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    ├── secret.yaml
    ├── middleware.yaml    # CRD Traefik
    └── ingress.yaml      # pour /oauth2/callback

Valeurs clés¶

values.yaml

akko-oauth2-proxy:
  image:
    repository: quay.io/oauth2-proxy/oauth2-proxy
    tag: "7.7.1"
  provider: keycloak-oidc
  cookie:
    domain: .akko.local
  ingress:
    enabled: true
    hostname: cockpit.akko.local
    path: /oauth2

Vérification de santé¶

GET http://akko-oauth2-proxy:4180/ping

Renvoie OK lorsque le proxy est prêt.

Dépannage¶

Problèmes courants

Boucle de redirection infinie : La cause la plus fréquente est un décalage entre la redirect-url et les URIs de redirection valides du client Keycloak. Vérifiez dans l'administration Keycloak (Clients > akko-oauth2-proxy > Valid Redirect URIs) que https://cockpit.akko.local/oauth2/callback est bien listé. Vérifiez aussi le domaine du cookie.
403 Forbidden après connexion : OAuth2 Proxy peut rejeter l'utilisateur si email-domain est trop restrictif ou si le token Keycloak ne contient pas les claims attendues. Consultez les logs d'OAuth2 Proxy avec kubectl logs deploy/akko-oauth2-proxy pour plus de détails.
Session perdue entre services : Tous les services doivent partager le même cookie-domain (.akko.local). Si un service utilise un domaine différent, le cookie n'est pas envoyé et l'utilisateur apparaît non authentifié.