Authentification basée sur certificat (legacy)

attention

L'authentification basée sur certificat est dépréciée et sera supprimée dans une prochaine release. Cette fonctionnalité n'est plus activement maintenue. Si vous utilisez actuellement cette fonctionnalité, veuillez contacter support@gitguardian.com pour discuter des options de migration.

L'authentification basée sur certificat exige des utilisateurs qu'ils présentent un certificat client TLS pour s'authentifier auprès de GitGuardian. Cette méthode est essentielle pour s'authentifier via une Common Access Card (CAC) ou Personal Identity Verification (PIV).

Prérequis système

Vous aurez besoin d'une autorité de certification (CA) au format PEM pour configurer l'authentification client. GitGuardian prend en charge une ou plusieurs CA (un bundle) à cette fin. Ces CA seront utilisées pour valider les certificats clients requis pour s'authentifier au tableau de bord GitGuardian.

De plus, vous devez fournir votre propre identifiant utilisateur externe situé dans votre certificat client, ainsi que les identifiants utilisateur externes des utilisateurs que vous souhaitez inviter sur la plateforme GitGuardian. Par exemple, l'Electronic Data Interchange Personal Identifier (EDIPI) du Department of Defense trouvé dans le CN pourrait ressembler à C=FR,O=DGSE,CN=hubert.bonisseur.delabath.117 où l'EDIPI = 117.

Prérequis réseau

Règles sortantes

Pour assurer une bonne communication avec le ou les serveurs OCSP ou CRL, configurez les règles réseau suivantes :

Port	Source	Destination	Description
80	Tous nœuds K8S	votre/vos serveur(s) OCSP/CRL	Serveur(s) OCSP/CRL

Configuration initiale

Suivez ces étapes pour configurer l'authentification basée sur certificat dans votre instance Self-Hosted :

1. Configuration initiale

   1. Suivez les instructions spécifiques selon que vous installez GitGuardian dans un cluster embedded ou existant.
   2. Commencez avec le mode défini sur audit pour la configuration et la vérification initiales.
   3. Uploadez votre CA qui validera les certificats clients.
   4. Configurez l'expression régulière pour extraire l'identifiant utilisateur externe du subject du certificat client (ou utilisez celle par défaut si elle vous convient).

2. Authentifiez-vous pour la première fois

   1. Connectez-vous à votre tableau de bord GitGuardian et fournissez votre certificat client (ou insérez votre carte CAC/PIV).
   2. Si vous rencontrez une erreur lors de l'authentification, une page d'erreur apparaîtra avec la raison de l'échec (par exemple, certificat invalide, révoqué, etc.). Notez que cette page d'erreur ne s'affichera qu'en mode audit.
      
   3. Si votre certificat client est valide, procédez à la connexion avec votre login/mot de passe au tableau de bord GitGuardian.
   4. Puis, entrez l'identifiant utilisateur externe trouvé dans le CN de votre certificat client lorsque demandé.
      

3. Vérifiez et appliquez

   1. Naviguez vers l'admin area sous Settings > Certificate-Based Authentication pour voir les détails du certificat client et du mapping utilisateur.
      
   2. Si l'identifiant utilisateur externe n'est pas correctement associé à un utilisateur GitGuardian, un message d'erreur sera affiché. Assurez-vous que l'expression régulière extrait correctement l'identifiant externe de l'utilisateur et que l'identifiant utilisateur est correctement configuré.
      
   3. Après avoir confirmé l'authentification réussie et le mapping utilisateur correct, passez en mode enforce via KOTS ou Helm.
   4. Optionnel : vous pouvez activer l'authentification email/mot de passe ou Single Sign-On (SSO) en complément de l'authentification basée sur certificat. Cela fournit une couche de sécurité additionnelle et permet une gestion utilisateur scalable via SAML SSO.

4. Intégrez vos premiers dépôts et invitez de nouveaux utilisateurs

   1. Intégrez vos premiers dépôts pour démarrer la détection et la remédiation automatisées de secrets.
   2. Invitez d'autres membres de l'équipe avec leur identifiant utilisateur externe.
   3. ⚠️ Seuls les utilisateurs avec accès à l'admin area peuvent inviter des utilisateurs en fournissant l'identifiant utilisateur externe. Ils peuvent également le modifier dans la page Settings > Members.

Paramètres de configuration

Pour toute installation (KOTS ou Helm), configurez les paramètres suivants :

• Enable : active l'authentification basée sur certificat.
• Mode : définit le comportement de l'application concernant les certificats clients.
  • audit : pour la configuration uniquement. Affiche les informations de debug. ⚠️ Note : les routes API publiques ne sont pas fonctionnelles avec le mode audit.
  • enforce : pour la production. Exige un certificat client.
• Certificate Authority : la CA qui valide les certificats clients (aussi appelée bundle de CA).
• CRL (optionnel) : la liste de révocation de certificats au format PEM ou DER (OCSP utilisé si non défini).
• Regex : l'expression régulière pour extraire l'identifiant unique d'utilisateur du Distinguished Name (DN) du certificat, partie du subject du certificat.

Cluster existant

attention

Lorsque vous activez cette option, la terminaison TLS est faite sur les pods backend. Activez SSL passthrough selon votre méthode d'exposition (Service Loadbalancer ou Ingress). Des exemples sont fournis ci-dessous.

Installation via KOTS

Dans la console d'administration KOTS, activez Use Certificate-Based Authentication et configurez les paramètres.

Installation via Helm

Dans les values Helm, configurez le bloc suivant :

tls:
  clientAuth:
    enabled: true
    mode: enforce
    userRegex: '(?:.+,)?CN=[^.]+\.[^.]+\.[^.]+\.(\d+)(?:,.+)?'
    crt: ''
    key: ''
    caCrt: ''
    ocspCacheSize: '10m'
    existingSecret: ''
    existingSecretKeys:
      crt: 'server.crt'
      key: 'server.key'
      caCrt: 'ca.crt' # PEM format
    crl:
      url: ''
      cron: '0 0 * * *'
      persistence:
        storageClass: ''
        accessModes:
          - ReadWriteMany
        size: 1Gi
        labels: {}
        annotations: {}

Utilisez des secrets existants pour stocker les certificats.

Exemple d'annotations

Service Loadbalancer sur DigitalOcean

service.beta.kubernetes.io/do-loadbalancer-tls-ports: '443'
service.beta.kubernetes.io/do-loadbalancer-tls-passthrough: 'true'

Ingress avec NGINX Ingress Controller

ingress:
  tls:
    enabled: true
  annotations:
    nginx.ingress.kubernetes.io/ssl-passthrough: 'true'
service:
  port: 443

Ajoutez ces lignes dans la section annotations de la console d'administration KOTS ou dans les values Helm.

Notes sur l'utilisation de CRL dans un cluster existant

Vous pouvez choisir d'effectuer les vérifications de révocation via CRL au lieu du serveur OCSP. Ce mode :

• crée un Persistent Volume utilisant un storageClass dans l'accessMode de votre choix. Cette configuration dépend de votre cluster.
• récupère la CRL à un intervalle régulier que vous définissez via une expression cron

Veuillez contacter notre équipe de support si nécessaire.

Embedded Cluster

Dans la console d'administration KOTS, activez Use Certificate-Based Authentication et configurez les paramètres.

Troubleshooting

Si vous rencontrez des problèmes d'authentification, il est recommandé de passer en mode audit. Pour diagnostiquer le problème, vous pouvez consulter les logs du pod webapp-internal_api. Pour plus de détails, consultez notre page troubleshooting.

Pour filtrer les logs sur les warnings, vous pouvez utiliser la commande suivante :

kubectl logs webapp-internal-api-6b98b7b9bc-wcvpb | grep warning

Problèmes courants :

1. Certificat client invalide :

{
  "timestamp": "2024-08-16T14:57:54.713592Z",
  "level": "warning",
  "event": "Mutual tls authentication failed",
  "reason": "Missing or invalid certificate",
  "remote_auth_result": "FAILED:certificate revoked",
  "logger": "auth.mutual_tls.services.middlewares",
  "gg_service": "ward-runs-app",
  "gg_environment": "onprem",
  "gg_version": "2024.8.0"
}

Solution : vérifiez la validité du certificat client. Vérifiez les problèmes tels que l'expiration ou la révocation.

2. L'identifiant utilisateur externe ne peut pas être mappé à un utilisateur GitGuardian :

{
  "timestamp": "2024-08-16T14:58:05.121226Z",
  "level": "warning",
  "event": "Mutual tls authentication failed",
  "reason": "Invalid User",
  "remote_user_dn": "CN=client3.0000000003,OU=Dev,O=GG,L=Paris,ST=Paris,C=FR",
  "external_user_id": "0000000003",
  "logger": "auth.mutual_tls.services.middlewares",
  "gg_service": "ward-runs-app",
  "gg_environment": "onprem",
  "gg_version": "2024.8.0"
}

Solution : assurez-vous que l'expression régulière extrait correctement l'identifiant externe de l'utilisateur. De plus, vérifiez que l'identifiant utilisateur externe est correctement associé à un utilisateur GitGuardian dans la section Settings > Members du tableau de bord GitGuardian. Vous devez avoir les privilèges admin pour accéder à ce paramètre.