Aller au contenu principal

mTLS et déploiement

Comment protéger un projet OneEntry avec un jeton ou un certificat mTLS, et déployer l'application sur un serveur avec Nginx, Docker et GitLab ou GitHub.

Partie 1 : configuration de mTLS​

Protéger l'API​

  1. Jeton : générez un jeton dans les paramètres OneEntry et envoyez-le dans l'en-tête de requête x-app-token.
  2. mTLS : activez mTLS dans votre tableau de bord OneEntry et générez un certificat dans les paramètres OneEntry.

Configurer le certificat​

  1. Dans votre tableau de bord, ouvrez l'onglet Access et passez du jeton à mTLS.
  2. Générez un nouveau certificat dans OneEntry (Settings → Application Certificates → Create New Certificate).
  3. Téléchargez-le et extrayez-le dans un dossier cert à la racine de votre projet.

Configurer l'environnement local (exemple React)​

  1. Téléchargez setupProxy.js et enregistrez-le dans le dossier src.
  2. Définissez le paramètre target sur l'adresse de votre projet.
  3. Installez http-proxy-middleware : npm install http-proxy-middleware.
  4. Lancez l'application.

Initialiser le SDK​

Lorsque mTLS est activé, l’API ne vérifie pas le jeton de l’application. Initialisez le SDK avec l’URL de votre projet comme d’habitude. Le SDK 1.0.175 exige toujours un token non vide : passez donc n’importe quelle chaîne factice :

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'mtls', // not checked when mTLS is enabled
});

Partie 2 : configuration du serveur​

Préparer le serveur​

  1. Mettez à jour les informations des dépôts : apt update.
  2. Ajoutez le dépôt Docker et installez les paquets : apt install nginx certbot docker-ce pwgen.

Configuration d'UFW​

  1. Bloquez toutes les connexions entrantes : ufw default deny incoming.
  2. Autorisez toutes les connexions sortantes : ufw default allow outgoing.
  3. Autorisez les connexions TCP entrantes sur les ports 22, 80 et 443 : ufw allow 22,80,443/tcp.

Configuration de SSH​

  1. Modifiez la configuration du démon SSH : nano /etc/ssh/sshd_config.
  2. Définissez PasswordAuthentication no.
  3. Redémarrez le démon SSH : systemctl restart ssh.

Configuration de Nginx​

  1. Supprimez le fichier de configuration par défaut : rm /etc/nginx/sites-available/default.
  2. Créez un nouveau fichier de configuration : nano /etc/nginx/sites-available/my_app.
  3. Téléchargez la configuration Nginx de OneEntry et remplacez "your_domain.com" par votre domaine.
  4. Exécutez : ln -s /etc/nginx/sites-available/my_app /etc/nginx/sites-enabled, en remplaçant "my_app" par le nom de votre fichier de configuration.
  5. Émettez les certificats SSL avec Certbot : certbot certonly --webroot -w /var/www/html -d your_domain.
  6. Vérifiez le renouvellement automatique des certificats : certbot renew --dry-run.
  7. Modifiez la tâche cron de Certbot pour que Nginx recharge sa configuration après l'émission des certificats : nano /etc/cron.d/certbot, en remplaçant la dernière ligne par : echo "0 */12 * * * root certbot -q renew && nginx -s reload" > /etc/cron.d/certbot
  8. Décommentez les lignes du fichier de configuration nano /etc/nginx/sites-available/my_app (où my_app est le nom de votre fichier de configuration).
  9. Vérifiez la configuration de Nginx : nginx -t.
  10. Rechargez Nginx après chaque modification : nginx -s reload.

Partie 3 : déployer l'application avec GitLab ou GitHub​

Accès du runner. L'utilisateur du runner GitHub rejoint les groupes docker et sudo, et le runner GitLab s'exécute en mode privilégié avec le socket Docker de l'hôte. Dans les deux cas, cela donne un contrôle de niveau root sur l'hôte : n'enregistrez donc le runner que pour votre propre dépôt et ne le laissez pas exécuter de jobs provenant de forks ou de merge requests non fiables. Les versions d'images sont celles avec lesquelles ce guide a été testé ; utilisez les versions actuelles prises en charge de gitlab/gitlab-runner et docker.

GitHub

Créer un utilisateur pour le runner GitHub​

  1. Générez un mot de passe : pwgen -s 15 1.
  2. Créez un nouvel utilisateur : useradd -m github-runner.
  3. Définissez-lui un mot de passe : passwd github-runner.
  4. Ajoutez le nouvel utilisateur aux groupes : usermod -aG docker github-runner et usermod -aG sudo github-runner.
  5. Changez le shell de l'utilisateur du runner : chsh -s /bin/bash github-runner.
  6. Basculez sur le nouvel utilisateur : sudo su - github-runner.

Configurer le runner GitHub​

  1. Créez un runner : dans les paramètres de votre dépôt, ouvrez Actions → Runners et cliquez sur New self-hosted runner.
  2. Suivez les instructions du bloc Download et exécutez la première commande du bloc Configure.
  3. Ajoutez le runner au démarrage automatique du système : sudo ./svc.sh install. Saisissez le mot de passe généré précédemment.
  4. Démarrez le runner : sudo ./svc.sh start.
  5. Dans Actions → Runners, vérifiez que le runner est en cours d'exécution.
  6. Revenez à l'utilisateur root.
  7. Créez un répertoire de travail : mkdir -p /var/apps/frontend.
  8. Donnez les droits à l'utilisateur github-runner : chown -R github-runner:docker /var/apps/frontend.

Configurer les variables d'environnement dans GitHub​

  1. Créez les variables DOMAIN, MTLS_USER_CERT et MTLS_USER_KEY dans votre dépôt GitHub (Settings → Secrets and Variables).
  2. Générez un certificat dans OneEntry et placez le certificat et la clé dans les variables. Définissez DOMAIN sur l'adresse de votre projet, sans https.
  3. Téléchargez le fichier docker-compose.yml et deux archives .github et .docker.
  4. Placez docker-compose.yml et les deux archives dans le dossier racine de votre projet et extrayez-les (vous pouvez supprimer les archives ensuite).
  5. Poussez vers votre dépôt.
  6. Suivez l'exécution dans l'onglet Actions.
  7. Ouvrez l'application dans le navigateur pour vérifier qu'elle est disponible.
GitLab

Préparer la configuration du runner GitLab (exécuteur Docker)​

  1. Créez les répertoires nécessaires : mkdir -p /var/apps/gitlab-runner/volumes/etc/gitlab-runner.

  2. Créez docker-compose.yaml :

    cat <<EOT > /var/apps/gitlab-runner/docker-compose.yaml
    version: '3'
    services:
      runner:
        image: 'gitlab/gitlab-runner:v16.2.0'
        restart: always
        container_name: 'gitlab-runner'
        privileged: true
        volumes:
          - './volumes/etc/gitlab-runner:/etc/gitlab-runner'
          - '/var/run/docker.sock:/var/run/docker.sock'
    EOT

Enregistrement du runner GitLab​

  1. Ouvrez Settings → CI/CD → Runners et cliquez sur New project runner.
  2. Définissez les tags docker, frontend et créez le runner.
  3. Allez dans le répertoire du runner : cd /var/apps/gitlab-runner.
  4. Lancez la commande qui démarre l'enregistrement : docker compose run runner register.
  5. Saisissez l'URL de GitLab, par exemple https://gitlab.com/.
  6. Copiez le jeton d'enregistrement depuis la section Runners du projet dans GitLab et collez-le dans le terminal.
  7. Définissez l'exécuteur sur docker.
  8. Définissez l'image par défaut sur docker:20.10.16.

Définition des variables d'environnement dans GitLab​

  1. Créez les variables DOMAIN, MTLS_USER_CERT et MTLS_USER_KEY dans votre dépôt GitLab (Settings → CI/CD → Variables).
  2. Générez un certificat dans OneEntry, placez le certificat et la clé dans les variables, et définissez DOMAIN sur l'adresse de votre projet, sans https.
  3. Téléchargez docker-compose.yml, l'archive .gitlab-ci.yml et l'archive .docker, placez-les à la racine de votre projet et extrayez les archives (vous pouvez les supprimer ensuite).

Configuration du runner GitLab​

  1. Modifiez le fichier de configuration : nano volumes/etc/gitlab-runner/config.toml.
  2. Passez le paramètre privileged à true pour activer Docker-in-Docker.
  3. Remplacez la valeur de volumes par ['/var/run/docker.sock:/var/run/docker.sock', '/cache'] pour que Docker fonctionne correctement.
  4. Ajoutez user = 'gitlab-runner' au début du fichier pour exécuter le runner sous cet utilisateur.
  5. Enregistrez les modifications et quittez l'éditeur.

Démarrer et vérifier le runner GitLab​

  1. Démarrez le runner : docker compose up -d.
  2. Dans GitLab, vérifiez que le runner est actif ; son statut apparaît dans la section Runners du projet.

Configurer un runner supplémentaire sur l'hôte (exécuteur shell)​

  1. Suivez les instructions pour installer un runner supplémentaire qui s'exécute directement sur l'hôte, et non dans Docker.
  2. Définissez les tags du runner : shell, frontend.

Permissions du runner​

  1. Ajoutez l'utilisateur au groupe : usermod -aG docker gitlab-runner.
  2. Pour changer le propriétaire et le groupe d'un fichier ou d'un répertoire : chown -R gitlab-runner:docker /var/apps/frontend.

Vérification finale​

  1. Vérifiez que tous les runners sont configurés et prêts.
  2. Poussez vers votre dépôt.
  3. Suivez la progression dans Build → Pipelines.
  4. Ouvrez l'application dans le navigateur pour vérifier qu'elle est disponible.