Authentification par carte à puce

{{< details >}}

• Niveau : Premium, Ultimate
• Offre : GitLab Self-Managed

{{< /details >}}

GitLab prend en charge l'authentification par carte à puce.

Authentification par mot de passe existante {#existing-password-authentication}

Par défaut, les utilisateurs existants peuvent continuer à se connecter avec un nom d'utilisateur et un mot de passe lorsque l'authentification par carte à puce est activée.

Pour forcer les utilisateurs existants à utiliser uniquement l'authentification par carte à puce, désactivez l'authentification par nom d'utilisateur et mot de passe.

Méthodes d'authentification {#authentication-methods}

GitLab prend en charge deux méthodes d'authentification :

• Certificats X.509 avec bases de données locales.
• Serveurs LDAP.

Authentification auprès d'une base de données locale avec des certificats X.509 {#authentication-against-a-local-database-with-x509-certificates}

{{< details >}}

• Statut : Expérimental

{{< /details >}}

Les cartes à puce avec certificats X.509 peuvent être utilisées pour s'authentifier auprès de GitLab.

Pour utiliser une carte à puce avec un certificat X.509 pour s'authentifier auprès d'une base de données locale avec GitLab, CN et emailAddress doivent être définis dans le certificat. Par exemple :

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=Random Corp Ltd, CN=Random Corp
        Validity
            Not Before: Oct 30 12:00:00 2018 GMT
            Not After : Oct 30 12:00:00 2019 GMT
        Subject: CN=Gitlab User, [email protected]

Authentification auprès d'une base de données locale avec des certificats X.509 et l'extension SAN {#authentication-against-a-local-database-with-x509-certificates-and-san-extension}

{{< details >}}

• Statut : Expérimental

{{< /details >}}

Les cartes à puce avec certificats X.509 utilisant des extensions SAN peuvent être utilisées pour s'authentifier auprès de GitLab.

Pour utiliser une carte à puce avec un certificat X.509 pour s'authentifier auprès d'une base de données locale avec GitLab :

• Au moins une des extensions subjectAltName (SAN) doit définir l'identité de l'utilisateur (email) au sein de l'instance GitLab (URI).
• L'URI doit correspondre à Gitlab.config.host.gitlab.
• Si votre certificat ne contient qu'one entrée d'e-mail SAN, vous n'avez pas besoin de l'ajouter ou de la modifier pour faire correspondre l'email avec l'URI.

Par exemple :

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=Random Corp Ltd, CN=Random Corp
        Validity
            Not Before: Oct 30 12:00:00 2018 GMT
            Not After : Oct 30 12:00:00 2019 GMT
        ...
        X509v3 extensions:
            X509v3 Key Usage:
                Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage:
                TLS Web Server Authentication
            X509v3 Subject Alternative Name:
                email:[email protected], URI:http://gitlab.example.com/

Authentification auprès d'un serveur LDAP {#authentication-against-an-ldap-server}

{{< details >}}

• Statut : Expérimental

{{< /details >}}

GitLab met en œuvre une méthode standard de correspondance de certificats en suivant RFC4523. Il utilise la règle de correspondance de certificats certificateExactMatch sur l'attribut userCertificate. Comme prérequis, vous devez utiliser un serveur LDAP qui :

• Prend en charge la règle de correspondance certificateExactMatch.
• Possède le certificat stocké dans l'attribut userCertificate.

Authentification auprès d'un serveur LDAP Active Directory {#authentication-against-an-active-directory-ldap-server}

{{< history >}}

• Introduit dans GitLab 16.9.
• Ajout des formats reverse_issuer_and_subject et reverse_issuer_and_serial_number dans GitLab 17.11.
• Les formats issuer_and_subject, reverse_issuer_and_subject et subject ont été mis à jour dans GitLab 18.6 avec un indicateur nommé smartcard_ad_formats_v2. Activé par défaut. Désactivez cet indicateur pour rétablir ces formats aux versions précédentes.
• Disponible en version générale dans GitLab 18.9. L'indicateur de feature flag smartcard_ad_formats_v2 a été supprimé.

{{< /history >}}

[!flag] La fonctionnalité de cette fonction est contrôlée par un feature flag. Pour plus d'informations, consultez l'historique.

Active Directory ne prend pas en charge la règle certificateExactMatch ni l'attribut userCertificate. La plupart des outils d'authentification basée sur des certificats, tels que les cartes à puce, utilisent l'attribut altSecurityIdentities, qui peut contenir plusieurs certificats pour chaque utilisateur. Les données du champ doivent correspondre à l'un des formats recommandés par Microsoft.

Utilisez les attributs suivants pour personnaliser le champ que GitLab vérifie et le format des données de certificat :

• smartcard_ad_cert_field - indique le nom du champ à rechercher. Il peut s'agir de n'importe quel attribut d'un objet utilisateur.
• smartcard_ad_cert_format - indique le format des informations extraites du certificat. Ce format doit être l'une des valeurs suivantes. La valeur la plus courante est issuer_and_serial_number pour correspondre au comportement des serveurs LDAP non Active Directory.

Pour issuer_and_serial_number, la portion <SR> est en ordre d'octets inversé, avec l'octet le moins significatif en premier. Pour plus d'informations, consultez comment mapper un utilisateur à un certificat à l'aide de l'attribut altSecurityIdentities.

Les formats d'émetteur inversés trient la chaîne d'émetteur de la plus petite unité à la plus grande. Certains serveurs Active Directory stockent les certificats dans ce format.

[!note] Si aucun smartcard_ad_cert_format n'est spécifié, mais qu'un serveur LDAP est configuré avec active_directory: true et les cartes à puce activées, GitLab adopte par défaut le comportement de la version 16.8 et antérieures, et utilise certificateExactMatch sur l'attribut userCertificate.

Authentification auprès d'Entra ID Domain Services {#authentication-against-entra-id-domain-services}

{{< history >}}

• Introduit dans GitLab 16.9.

{{< /history >}}

Microsoft Entra ID, anciennement connu sous le nom d'Azure Active Directory, fournit un annuaire basé sur le cloud pour les entreprises et les organisations. Entra Domain Services fournit une interface LDAP sécurisée en lecture seule vers l'annuaire, mais n'expose qu'un sous-ensemble limité des champs disponibles dans Entra ID.

Entra ID utilise le champ CertificateUserIds pour gérer les certificats clients des utilisateurs, mais ce champ n'est pas exposé dans LDAP / Entra ID Domain Services. Avec une configuration cloud uniquement, il n'est pas possible pour GitLab d'authentifier les cartes à puce des utilisateurs via LDAP.

Dans un environnement hybride sur site et cloud, les entités sont synchronisées entre le contrôleur Active Directory sur site et le cloud Entra ID via Entra Connect. Si vous synchronisez votre attribut altSecurityIdentities avec certificateUserIds dans Entra ID à l'aide d'Entra ID Connect, vous pouvez exposer ces données dans LDAP / Entra ID Domain Services afin qu'elles puissent être authentifiées par GitLab :

1. Ajoutez une règle à Entra ID Connect pour synchroniser l'altSecurityIdentities avec un attribut supplémentaire dans Entra ID.
2. Activez cet attribut supplémentaire en tant qu'attribut d'extension dans Entra ID Domain Services.
3. Configurez le champ smartcard_ad_cert_field dans GitLab pour utiliser cet attribut d'extension.

Configurer GitLab pour l'authentification par carte à puce {#configure-gitlab-for-smart-card-authentication}

Pour les installations de packages Linux :

1. Modifiez /etc/gitlab/gitlab.rb :

   rubyCopy

   # Allow smart card authentication
   gitlab_rails['smartcard_enabled'] = true
   
   # Path to a file containing a CA certificate
   gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
   
   # Host and port where the client side certificate is requested by the
   # webserver (NGINX/Apache)
   gitlab_rails['smartcard_client_certificate_required_host'] = "smartcard.example.com"
   gitlab_rails['smartcard_client_certificate_required_port'] = 3444
   

   [!note] Attribuez une valeur à au moins l'une des variables suivantes : gitlab_rails['smartcard_client_certificate_required_host'] ou gitlab_rails['smartcard_client_certificate_required_port'].

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

Pour les installations compilées manuellement :

1. Configurez NGINX pour demander un certificat côté client

   Dans la configuration NGINX, un contexte serveur additional doit être défini avec la même configuration, à l'exception des éléments suivants :

   • Le contexte serveur NGINX supplémentaire doit être configuré pour s'exécuter sur un port différent :

     plaintextCopy

     listen *:3444 ssl;
     

   • Il peut également être configuré pour s'exécuter sur un nom d'hôte différent :

     plaintextCopy

     listen smartcard.example.com:443 ssl;
     

   • Le contexte serveur NGINX supplémentaire doit être configuré pour exiger le certificat côté client :

     plaintextCopy

     ssl_verify_depth 2;
     ssl_client_certificate /etc/ssl/certs/CA.pem;
     ssl_verify_client on;
     

   • Le contexte serveur NGINX supplémentaire doit être configuré pour transmettre le certificat côté client :

     plaintextCopy

     proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;
     

   Par exemple, voici un exemple de contexte serveur dans un fichier de configuration NGINX (tel que /etc/nginx/sites-available/gitlab-ssl) :

   plaintextCopy

   server {
       listen smartcard.example.com:3443 ssl;
   
       # certificate for configuring SSL
       ssl_certificate /path/to/example.com.crt;
       ssl_certificate_key /path/to/example.com.key;
   
       ssl_verify_depth 2;
       # CA certificate for client side certificate verification
       ssl_client_certificate /etc/ssl/certs/CA.pem;
       ssl_verify_client on;
   
       location / {
           proxy_set_header    Host                        $http_host;
           proxy_set_header    X-Real-IP                   $remote_addr;
           proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
           proxy_set_header    X-Forwarded-Proto           $scheme;
           proxy_set_header    Upgrade                     $http_upgrade;
           proxy_set_header    Connection                  $connection_upgrade;
   
           proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;
   
           proxy_read_timeout 300;
   
           proxy_pass http://gitlab-workhorse;
       }
   }
   

2. Modifiez config/gitlab.yml :

   yamlCopy

   ## Smart card authentication settings
   smartcard:
     # Allow smart card authentication
     enabled: true
   
     # Path to a file containing a CA certificate
     ca_file: '/etc/ssl/certs/CA.pem'
   
     # Host and port where the client side certificate is requested by the
     # webserver (NGINX/Apache)
     client_certificate_required_host: smartcard.example.com
     client_certificate_required_port: 3443
   

   [!note] Attribuez une valeur à au moins l'une des variables suivantes : client_certificate_required_host ou client_certificate_required_port.

3. Enregistrez le fichier et redémarrez GitLab pour que les modifications prennent effet.

Recommandations de sécurité supplémentaires {#additional-security-recommendations}

Pour une sécurité renforcée, déployez GitLab derrière un pare-feu tel que CloudFlare WAF ou un serveur exécutant ModSecurity. Les URL correspondant aux modèles suivants doivent être accessibles au NGINX déployé dans le cadre de GitLab, mais pas aux clients externes :

/-/smartcard/extract_certificate
/-/smartcard/verify_certificate

Ces chemins ne doivent être accessibles de l'extérieur qu'en utilisant le nom d'hôte et le port de la carte à puce alloués à NGINX, et ne doivent pas être accessibles de l'extérieur en utilisant le nom d'hôte et le port principaux de GitLab. Cela doit être robuste contre les attaques par en-tête d'hôte HTTP, afin que les utilisateurs ne puissent pas soumettre leurs propres paramètres de certificat sans passer par NGINX.

Étapes supplémentaires lors de l'utilisation des extensions SAN {#additional-steps-when-using-san-extensions}

Pour les installations de packages Linux :

1. Ajoutez à /etc/gitlab/gitlab.rb :

   rubyCopy

   gitlab_rails['smartcard_san_extensions'] = true
   

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

Pour les installations compilées manuellement :

1. Ajoutez la ligne san_extensions dans config/gitlab.yml dans la section de la carte à puce :

   yamlCopy

   smartcard:
      enabled: true
      ca_file: '/etc/ssl/certs/CA.pem'
      client_certificate_required_port: 3444
   
      # Enable the use of SAN extensions to match users with certificates
      san_extensions: true
   

2. Enregistrez le fichier et redémarrez GitLab pour que les modifications prennent effet.

Étapes supplémentaires lors de l'authentification auprès d'un serveur LDAP {#additional-steps-when-authenticating-against-an-ldap-server}

Pour les installations de packages Linux :

1. Modifiez /etc/gitlab/gitlab.rb :

   rubyCopy

   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
   main:
     # snip...
     # Enable smart card authentication against the LDAP server. Valid values
     # are "false", "optional", and "required".
     smartcard_auth: optional
   
     # If your LDAP server is Active Directory, you can configure these two fields.
     # Specify which field contains certificate information, 'altSecurityIdentities' by default
     smartcard_ad_cert_field: altSecurityIdentities
   
     # Specify format of certificate information. Valid values are:
     # principal_name, rfc822_name, issuer_and_subject, subject, issuer_and_serial_number
     smartcard_ad_cert_format: issuer_and_serial_number
   EOS
   

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

Pour les installations compilées manuellement :

1. Modifiez config/gitlab.yml :

   yamlCopy

   production:
     ldap:
       servers:
         main:
           # snip...
           # Enable smart card authentication against the LDAP server. Valid values
           # are "false", "optional", and "required".
           smartcard_auth: optional
   
           # If your LDAP server is Active Directory, you can configure these two fields.
           # Specify which field contains certificate information, 'altSecurityIdentities' by default
           smartcard_ad_cert_field: altSecurityIdentities
   
           # Specify format of certificate information. Valid values are:
           # principal_name, rfc822_name, issuer_and_subject, subject, issuer_and_serial_number
           smartcard_ad_cert_format: issuer_and_serial_number
   

2. Enregistrez le fichier et redémarrez GitLab pour que les modifications prennent effet.

Exiger une session de navigateur avec connexion par carte à puce pour l'accès Git {#require-browser-session-with-smart-card-sign-in-for-git-access}

Pour les installations de packages Linux :

1. Modifiez /etc/gitlab/gitlab.rb :

   rubyCopy

   gitlab_rails['smartcard_required_for_git_access'] = true
   

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

Pour les installations compilées manuellement :

1. Modifiez config/gitlab.yml :

   yamlCopy

   ## Smart card authentication settings
   smartcard:
     # snip...
     # Browser session with smart card sign-in is required for Git access
     required_for_git_access: true
   

2. Enregistrez le fichier et redémarrez GitLab pour que les modifications prennent effet.

Mots de passe pour les utilisateurs créés via l'authentification par carte à puce {#passwords-for-users-created-via-smart-card-authentication}

Le guide Mots de passe générés pour les utilisateurs créés via l'authentification intégrée fournit un aperçu de la façon dont GitLab génère et définit les mots de passe pour les utilisateurs créés via l'authentification par carte à puce.