Quick Started

PrérequisCopy Anchor Link

• Un cluster Kubernetes (>= v1.30) Hôte pour faire tourner ProxyAuthK8S
  • Cert Manager pour la gestion des certificats TLS
  • Un ingress controller pour exposer les services de ProxyAuthK8S
• Un provider d'identité OIDC/Oauth2 (ex: Keycloak, Authentik, Dex, etc.) pour gérer l'authentification des utilisateurs
  • Redirect Uri autorisées :
    • ${PROXYAUTHK8S_DASHBOARD_URL}/auth/callback pour l'authentification des utilisateurs au Dashboard
    • ${PROXYAUTHK8S_DASHBOARD_URL}/auth/callback/{{Namespace}}/{{ClusterName}} pour la connexion à un cluster depuis le Dashboard
    • ${PROXYAUTHK8S_DASHBOARD_URL}/clusters/{{Namespace}}/{{ClusterName}}/auth/callback
    • http://localhost:18000/auth/callback/{{Namespace}}/{{ClusterName}} pour la connexion depuis le plugin kubectl
  • Un client OIDC/Oauth2 configuré avec les scopes openid groups profile email et l'audience proxyauthk8s
• Un ou plusieurs clusters Kubernetes cibles à exposer (le cluster hôte peut lui-même être un cluster exposé)
• kubectl pour interagir avec le cluster Kubernetes
• Helm pour installer ProxyAuthK8S
• Une bonne tasse de café pour accompagner le tout ☕

InstallationCopy Anchor Link

0. Cloner le repository et définir les constantesCopy Anchor Link

git clone https://github.com/batleforc/proxyauthk8s.git
cd proxyauthk8s

Dans cette présentation Quick Started, nous allons suivre les constantes suivantes:

# Namespace où ProxyAuthK8S sera installé
export NAMESPACE=proxyauthk8s
# URL (issuer) de votre provider d'identité OIDC/Oauth2
export OIDC_ISSUER_URL=https://auth.example.com
# ID client de votre provider d'identité OIDC/Oauth2
export OIDC_CLIENT_ID=proxyauthk8s-client
# Secret client de votre provider d'identité OIDC/Oauth2
export OIDC_CLIENT_SECRET=proxyauthk8s-secret
# Audience attendue dans les access tokens
export OIDC_AUDIENCE=proxyauthk8s
# Nom d'hôte du dashboard ProxyAuthK8S (sans le schéma)
export PROXYAUTHK8S_HOST=proxyauthk8s.example.com
export PROXYAUTHK8S_DASHBOARD_URL=https://${PROXYAUTHK8S_HOST}

Toutes les charts vont être installées dans le namespace proxyauthk8s mais vous pouvez le changer si vous le souhaitez. Assurez-vous simplement de mettre à jour les commandes d'installation en conséquence.

Commençons par créer ce namespace:

kubectl create namespace ${NAMESPACE}

1. Installer Redis/DragonflyCopy Anchor Link

ProxyAuthK8S stocke son état (sessions de login, compteurs de bannissement et de quotas) dans Redis. N'importe quel serveur compatible Redis fait l'affaire ; ici on utilise Dragonfly :

helm upgrade \
    --install dragonfly oci://ghcr.io/dragonflydb/dragonfly/helm/dragonfly \
    --namespace ${NAMESPACE} \
    --values deploy/quick-started/dragonfly.yaml

Cette exemple de setup est directement inspiré de la documentation officielle de DragonFly. La chart expose un service dragonfly sur le port 6379 :

export REDIS_URL=redis://dragonfly.${NAMESPACE}.svc:6379

2. Préparer les secretsCopy Anchor Link

Le backend lit sa configuration OIDC depuis un secret :

kubectl create secret generic proxyauthk8s-back-oidc \
  --namespace ${NAMESPACE} \
  --from-literal=OIDC_ISSUER_URL=${OIDC_ISSUER_URL} \
  --from-literal=OIDC_CLIENT_ID=${OIDC_CLIENT_ID} \
  --from-literal=OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET} \
  --from-literal=OIDC_SCOPES="openid groups profile email" \
  --from-literal=OIDC_AUDIENCE=${OIDC_AUDIENCE}

3. Installer ProxyAuthK8SCopy Anchor Link

L'installation de ProxyAuthK8S se fait via les helm charts exposées dans un registry OCI. On commence par écrire un fichier de values (les images suivent par défaut la version de la chart) :

cat > proxyauthk8s-values.yaml <<EOF
ingress:
  host: ${PROXYAUTHK8S_HOST}
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt # adaptez à votre issuer

oidc:
  source: secret
  objectName: proxyauthk8s-back-oidc

back:
  redis:
    source: env
    value:
      url: ${REDIS_URL}
EOF

Le front et le backend lisent tous deux la configuration OIDC depuis ce secret (le front n'en lit que les parties publiques : issuer, client id et scopes).

Puis on installe les CRD et l'application :

# Install the latest version of ProxyAuthK8s CRDs
helm upgrade \
  --install proxyauthk8s-crd oci://ghcr.io/batleforc/proxyauthk8s/chart-crd:0.6.0 \
  --namespace ${NAMESPACE}
# Install the latest version of ProxyAuthK8s
helm upgrade \
  --install proxyauthk8s oci://ghcr.io/batleforc/proxyauthk8s/chart:0.6.0 \
  --namespace ${NAMESPACE} \
  --values proxyauthk8s-values.yaml

Vérifiez que les pods démarrent :

kubectl get pods -n ${NAMESPACE}

4. Exposer le cluster hôteCopy Anchor Link

Maintenant que ProxyAuthK8S est installé, nous allons exposer le cluster hôte en créant une ressource ProxyKubeApi. Avec expose_via_dashboard: true, elle sera visible dans le dashboard par toute personne ayant le groupe dashboard-default-local-sso (par défaut dashboard-<namespace>-<nom>) dans le provider OIDC.

cat <<EOF | kubectl apply -f -
apiVersion: weebo.si.rs/v1
kind: ProxyKubeApi
metadata:
  name: local-sso
  namespace: default
spec:
  expose_via_dashboard: true
  cert:
    ConfigMap:
      name: kube-root-ca.crt
      key: ca.crt
  service:
    KubernetesService:
      name: kubernetes
      namespace: default
      port: 443
  auth_config:
    validate_against: OidcProvider
    oidc_provider:
      enabled: true
      issuer_url: "${OIDC_ISSUER_URL}"
      client_id: "${OIDC_CLIENT_ID}"
      client_secret: "${OIDC_CLIENT_SECRET}"
      audience: "${OIDC_AUDIENCE}"
      extra_scope: "openid groups profile email"
EOF

Vérifiez que le controller l'a pris en compte :

kubectl get proxykubeapi -n default local-sso -o jsonpath='{.status}'
# {"exposed":true,"path":"/clusters/default/local-sso"}

5. Enjoy ProxyAuthK8S! 🎉Copy Anchor Link

Maintenant que tout est en place, vous pouvez accéder au dashboard de ProxyAuthK8S à l'URL PROXYAUTHK8S_DASHBOARD_URL. Connectez-vous avec un utilisateur de votre provider d'identité qui a le groupe dashboard-default-local-sso et vous devriez voir votre cluster hôte exposé dans le dashboard. La suite se passe dans le guide du dashboard ou avec le plugin kubectl.