` depuis l'intérieur de la VM. Selon la manière dont l'hébergeur attache l'adresse publique, ce chemin peut ne pas aboutir. Le cas est traité dans la page Traefik.
Page suivante : **Socle système et Docker Engine**.
# Socle système et Docker Engine
## Le socle, c'est quoi ?
Le socle est ce que reçoit toute VM Nébuleuse avant la moindre application : un système à jour, un accès SSH restreint, un pare-feu, puis Docker avec son réseau partagé. Il est porté par deux rôles, `base-hardening` et `docker-engine`, appliqués dans cet ordre.
| Rôle | Rôle dans le socle |
|---|
| `base-hardening` | Mises à jour, SSH restreint au réseau d'administration, pare-feu `ufw` |
| `docker-engine` | Docker depuis le dépôt officiel, journaux limités, réseau `proxy` |
**VM Debian 12 vierge → `base-hardening` → `docker-engine` → machine prête à recevoir Traefik**
Concrètement, la VM livrée par le provisioning possède déjà un utilisateur `deploy` autorisé par clé SSH et membre de `sudo` sans mot de passe. Le socle ne crée pas cet utilisateur : il en dépend, et il le verrouille comme seul compte autorisé à se connecter.
## Prérequis
1. Les pages précédentes sont en place : inventaire, variables communes (`admin_network_cidr`) et `ansible ... -m ping` fonctionnel.
2. L'utilisateur `deploy` se connecte par clé et dispose de `sudo` sans mot de passe.
3. L'adresse `ansible_host` de chaque client est son adresse du réseau d'administration, car c'est celle sur laquelle SSH écoutera.
## Arborescence des deux rôles
```text
roles/
├── base-hardening/
│ ├── defaults/main.yml
│ ├── handlers/main.yml
│ ├── tasks/main.yml
│ └── templates/sshd-nebuleuse.conf.j2
└── docker-engine/
├── defaults/main.yml
├── handlers/main.yml
├── tasks/main.yml
└── templates/daemon.json.j2
```
## Le rôle `base-hardening`
### Variables
```yaml
# roles/base-hardening/defaults/main.yml
# Seul utilisateur autorisé à ouvrir une session SSH.
base_ssh_user: deploy
# Adresse sur laquelle SSH écoute : celle du réseau d'administration.
# "ansible_host" vaut cette adresse dans l'inventaire (voir page Inventaire).
base_ssh_listen_address: "{{ ansible_host }}"
# Réseau autorisé à joindre SSH (défini une fois pour tous dans group_vars/all).
base_admin_network_cidr: "{{ admin_network_cidr }}"
# Ports ouverts à tout Internet : uniquement le web.
base_public_tcp_ports:
- 80
- 443
```
### Configuration SSH
```text
# roles/base-hardening/templates/sshd-nebuleuse.conf.j2
# Fichier géré par Ansible : toute modification manuelle sera écrasée.
# Pas de connexion directe en root.
PermitRootLogin no
# Authentification par clé uniquement : aucun mot de passe n'est accepté.
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
# Un seul compte peut se connecter.
AllowUsers {{ base_ssh_user }}
# SSH n'écoute que sur l'adresse d'administration, jamais sur l'adresse publique.
ListenAddress {{ base_ssh_listen_address }}
```
Note — Sous Debian 12, le fichier principal `/etc/ssh/sshd_config` commence par une directive `Include /etc/ssh/sshd_config.d/*.conf`. Pour chaque paramètre, SSH retient la première valeur lue : le fichier déposé dans ce dossier l'emporte donc sur le fichier principal, sans avoir à le modifier.
### Tâches
```yaml
# roles/base-hardening/tasks/main.yml
- name: Mettre à jour l'index des paquets et les paquets installés
ansible.builtin.apt:
update_cache: true
# "dist" équivaut à "apt dist-upgrade" : gère aussi les changements de dépendances.
upgrade: dist
# Ne relit l'index qu'au bout d'une heure : évite un téléchargement inutile à chaque passage.
cache_valid_time: 3600
- name: Installer les paquets du socle
ansible.builtin.apt:
name:
- ufw # pare-feu de l'hôte
- unattended-upgrades # installation automatique des mises à jour de sécurité
- ca-certificates # certificats racine pour les téléchargements HTTPS
- curl # utilisé par d'autres rôles
state: present
- name: Activer les mises à jour de sécurité automatiques
ansible.builtin.copy:
dest: /etc/apt/apt.conf.d/20auto-upgrades
content: |
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
owner: root
group: root
mode: "0644"
- name: Déposer la configuration SSH durcie
ansible.builtin.template:
src: sshd-nebuleuse.conf.j2
dest: /etc/ssh/sshd_config.d/10-nebuleuse.conf
owner: root
group: root
mode: "0644"
# Vérifie la syntaxe avant d'écraser le fichier : une erreur ici couperait l'accès.
validate: /usr/sbin/sshd -t -f %s
notify: Redémarrer ssh
# Le pare-feu : l'ordre compte. La règle SSH est créée AVANT l'activation
# du pare-feu, sinon la connexion en cours serait coupée.
- name: Refuser par défaut tout trafic entrant
community.general.ufw:
default: deny
direction: incoming
- name: Autoriser SSH depuis le réseau d'administration uniquement
community.general.ufw:
rule: allow
port: "22"
proto: tcp
src: "{{ base_admin_network_cidr }}"
- name: Autoriser le web (HTTP et HTTPS) depuis Internet
community.general.ufw:
rule: allow
port: "{{ item }}"
proto: tcp
loop: "{{ base_public_tcp_ports }}"
- name: Activer ufw
community.general.ufw:
state: enabled
```
```yaml
# roles/base-hardening/handlers/main.yml
# Un handler ne s'exécute qu'à la fin des tâches, et seulement si une tâche l'a notifié.
- name: Redémarrer ssh
ansible.builtin.service:
name: ssh # le service s'appelle "ssh" sous Debian, pas "sshd"
state: restarted
```
## Le rôle `docker-engine`
### Variables
```yaml
# roles/docker-engine/defaults/main.yml
# Nom du réseau partagé entre Traefik et les applications (voir group_vars/all).
docker_engine_proxy_network: "{{ docker_proxy_network }}"
# Taille maximale d'un fichier de journal de conteneur, et nombre de fichiers conservés.
# Sans limite, les journaux d'un conteneur bavard finissent par remplir le disque.
docker_engine_log_max_size: "10m"
docker_engine_log_max_files: "3"
```
### Configuration du démon
```text
# roles/docker-engine/templates/daemon.json.j2
{
"log-driver": "json-file",
"log-opts": {
"max-size": "{{ docker_engine_log_max_size }}",
"max-file": "{{ docker_engine_log_max_files }}"
},
"live-restore": true
}
```
Le paramètre `live-restore` garde les conteneurs en marche pendant un redémarrage ou une mise à jour du démon Docker : une mise à jour du moteur ne coupe donc pas les services des clients.
### Tâches
```yaml
# roles/docker-engine/tasks/main.yml
- name: Créer le dossier des clés de dépôt
ansible.builtin.file:
path: /etc/apt/keyrings
state: directory
mode: "0755"
- name: Récupérer la clé de signature du dépôt Docker
ansible.builtin.get_url:
url: https://download.docker.com/linux/debian/gpg
dest: /etc/apt/keyrings/docker.asc
mode: "0644"
- name: Déclarer le dépôt officiel Docker
ansible.builtin.apt_repository:
# "signed-by" lie ce dépôt à sa clé : les paquets sont vérifiés avec elle.
# ansible_distribution_release vaut "bookworm" sur Debian 12.
repo: >-
deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc]
https://download.docker.com/linux/debian {{ ansible_distribution_release }} stable
filename: docker
state: present
- name: Installer Docker Engine et le plugin Compose
ansible.builtin.apt:
name:
- docker-ce
- docker-ce-cli
- containerd.io
- docker-buildx-plugin
- docker-compose-plugin # fournit la commande "docker compose"
- python3-docker # bibliothèque Python requise par les modules community.docker
state: present
update_cache: true
- name: Déposer la configuration du démon Docker
ansible.builtin.template:
src: daemon.json.j2
dest: /etc/docker/daemon.json
owner: root
group: root
mode: "0644"
notify: Redémarrer docker
- name: Activer et démarrer Docker
ansible.builtin.service:
name: docker
state: started
enabled: true
# Les handlers sont lancés ici plutôt qu'en fin de rôle : le réseau ci-dessous
# doit être créé sur un démon déjà configuré.
- name: Appliquer les changements de configuration du démon
ansible.builtin.meta: flush_handlers
- name: Créer le réseau partagé entre Traefik et les applications
community.docker.docker_network:
name: "{{ docker_engine_proxy_network }}"
driver: bridge
```
```yaml
# roles/docker-engine/handlers/main.yml
- name: Redémarrer docker
ansible.builtin.service:
name: docker
state: restarted
```
Note — L'utilisateur `deploy` n'est volontairement pas ajouté au groupe `docker`. Appartenir à ce groupe revient à avoir les droits root sur la machine. Ansible utilise déjà `sudo`, ce qui laisse une trace de chaque commande.
## Docker et le pare-feu : ce qu'il faut savoir
Docker gère lui-même ses règles de pare-feu. Quand un conteneur publie un port (comme Traefik sur 80 et 443), Docker l'ouvre directement, sans passer par `ufw`. Ainsi, une règle `ufw` ne bloque pas un port publié par un conteneur.
Ce comportement est connu, et il explique deux choix du projet : 1. Seul Traefik publie des ports vers l'extérieur. Les autres conteneurs restent sur le réseau `proxy`, sans port publié. 2. Les blocages dynamiques (Fail2ban) ne passent pas par `ufw` mais par la chaîne `DOCKER-USER`. Docker crée cette chaîne et ne la modifie jamais ; les règles qu'on y place sont donc appliquées avant celles de Docker.
## Le playbook du socle
Pour tester dès maintenant, un `site.yml` minimal suffit. Il sera complété à la page de déploiement.
```yaml
# site.yml
- name: Socle Nébuleuse
hosts: clients
become: true # les tâches s'exécutent en root via sudo
roles:
- { role: base-hardening, tags: [base] }
- { role: docker-engine, tags: [docker] }
```
```bash
# Simulation : montre ce qui changerait, sans rien modifier.
ansible-playbook site.yml --limit client-alpha --check --diff
# Déploiement réel.
ansible-playbook site.yml --limit client-alpha
```
## Vérification
```bash
# Depuis le serveur Ansible : un second passage ne doit rien modifier.
# La ligne finale doit afficher "changed=0".
ansible-playbook site.yml --limit client-alpha
# Sur la VM : valeurs SSH effectives.
sudo sshd -T | grep -E 'listenaddress|passwordauthentication|permitrootlogin|allowusers'
# Sur la VM : règles du pare-feu.
sudo ufw status verbose
# Sur la VM : version de Docker, pilote de journaux et live-restore.
docker version --format '{{.Server.Version}}'
docker info --format 'journaux={{.LoggingDriver}} live-restore={{.LiveRestoreEnabled}}'
# Sur la VM : le réseau partagé existe et la chaîne DOCKER-USER est disponible.
docker network ls --filter name=proxy
sudo iptables -L DOCKER-USER -n
```
Résultat attendu pour `sshd -T` : `listenaddress 10.99.0.21:22`, `passwordauthentication no`, `permitrootlogin no`, `allowusers deploy`.
## Pièges
1. **Se couper l'accès en modifiant SSH** : une erreur de `ListenAddress` ou une règle de pare-feu oubliée coupe la connexion. La validation `sshd -t` et l'ordre « règle avant activation » limitent le risque. Avant de fermer une session de test, ouvrir une seconde connexion pour vérifier que l'accès fonctionne encore.
2. **`ansible_host` qui n'est pas l'adresse d'administration** : SSH n'écouterait pas là où Ansible se connecte. L'inventaire de la première page respecte la règle ; une machine ajoutée avec son adresse publique fausserait le rôle.
3. **`apt` bloqué par un autre processus** : juste après le démarrage d'une VM neuve, `unattended-upgrades` peut tenir le verrou `apt`. Ansible patiente un moment, puis échoue avec « Could not get lock ». Relancer le playbook suffit.
4. **Pare-feu `ufw` qui « ne bloque rien » pour un conteneur** : voir la section précédente. Ce n'est pas un défaut de configuration.
5. **`docker_network` en erreur sur la bibliothèque Python** : le paquet `python3-docker` doit être installé avant toute tâche `community.docker`. Il fait partie de la liste des paquets du rôle.
6. **Journaux de conteneurs qui remplissent le disque** : sans `max-size`, aucune rotation n'est faite. La configuration `daemon.json` ne s'applique qu'aux conteneurs créés après elle ; les conteneurs existants doivent être recréés.
Page suivante : **Bastion Teleport : agent et enrôlement**.
# Bastion Teleport : agent et enrôlement
## Le bastion, c'est quoi ?
Un bastion est une porte d'entrée unique pour l'administration des machines. Au lieu d'ouvrir SSH sur chaque VM, les administrateurs se connectent au bastion, qui les authentifie, vérifie leurs droits, puis les met en relation avec la machine demandée en enregistrant la session. Nébuleuse utilise Teleport pour cela.
| Composant | Rôle |
|---|
| Proxy Teleport (sur le bastion) | Reçoit les connexions des administrateurs et des agents, sert le portail web |
| Auth Teleport (sur le bastion) | Authentifie, émet les certificats, applique les droits, conserve les enregistrements |
| Agent Teleport (sur chaque VM) | Rattache la VM au bastion et ouvre les sessions demandées |
**Administrateur → Bastion (authentification forte) → Tunnel déjà ouvert par l'agent → VM client**
Concrètement, c'est l'agent qui établit la connexion vers le bastion, pas l'inverse. La VM n'a donc aucun port d'administration à exposer : le tunnel est sortant, sur le port 443.
Note — L'installation du bastion lui-même (serveur Teleport, nom de domaine, création d'utilisateurs) est détaillée dans le livre Teleport de cette documentation, pages « Installation » et « Enroler des resources ». Cette page ne traite que ce qui est propre à Nébuleuse : déployer l'agent par Ansible, sans passer par l'interface web.
## Pourquoi un déploiement par Ansible ?
L'interface web de Teleport génère une commande à copier sur la machine, avec un jeton temporaire. C'est pratique pour une machine, mais cela ne passe pas à l'échelle : chaque nouveau client demanderait une intervention manuelle. Le rôle `teleport-agent` fait la même chose automatiquement : il demande un jeton au bastion, installe l'agent, écrit sa configuration et le démarre.
## Prérequis
1. Un bastion Teleport en service, joignable à `bastion.nebuleuse.example:443` depuis les VM clientes.
2. Le bastion est présent dans l'inventaire (voir ci-dessous), car Ansible doit y exécuter une commande.
3. La version de l'agent est inférieure ou égale à celle du bastion : un agent plus récent que le serveur n'est pas pris en charge.
4. Le socle système est appliqué sur la VM (page précédente).
## Ajouter le bastion à l'inventaire
Le bastion n'est pas un client : il forme son propre groupe, ce qui permet à Ansible de lui déléguer la création des jetons.
```yaml
# inventory/hosts.yml (version complétée)
all:
children:
bastion: # groupe du bastion : une seule machine
hosts:
bastion:
ansible_host: 10.99.0.3
clients: # groupe des VM clientes
hosts:
client-alpha:
ansible_host: 10.99.0.21
client-beta:
ansible_host: 10.99.0.22
```
## Arborescence du rôle
```text
roles/teleport-agent/
├── defaults/main.yml
├── handlers/main.yml
├── tasks/main.yml
└── templates/teleport.yaml.j2
```
## Variables
```yaml
# roles/teleport-agent/defaults/main.yml
# Version et édition de Teleport (édition communautaire, gratuite).
# Doit être inférieure ou égale à la version du bastion.
teleport_agent_version: "17.4.3"
teleport_agent_edition: "oss"
# Adresse du proxy du bastion (définie une fois pour tous dans group_vars/all).
teleport_agent_proxy: "{{ teleport_proxy_addr }}"
# Durée de validité du jeton d'enrôlement. Il ne sert qu'à la première connexion :
# une durée courte limite l'exposition si le jeton fuit.
teleport_agent_token_ttl: "30m"
# Étiquettes (labels) attachées à la machine dans Teleport.
# Les droits d'accès des administrateurs s'appuient dessus (voir plus bas).
teleport_agent_labels:
client: "{{ client_name }}"
env: production
```
## Configuration de l'agent
```text
# roles/teleport-agent/templates/teleport.yaml.j2
# Fichier géré par Ansible : toute modification manuelle sera écrasée.
version: v3
teleport:
# Nom affiché dans Teleport : le nom d'hôte de l'inventaire (unique par client).
nodename: {{ inventory_hostname }}
data_dir: /var/lib/teleport
# Adresse du bastion : l'agent s'y connecte en sortant.
proxy_server: {{ teleport_agent_proxy }}
{% if teleport_join_token.stdout | default('') | trim | length > 0 %}
# Présent uniquement lors du premier enrôlement. Une fois la machine enrôlée,
# elle conserve son identité dans data_dir et n'a plus besoin du jeton.
join_params:
method: token
token_name: {{ teleport_join_token.stdout | trim }}
{% endif %}
log:
output: stderr
severity: INFO
# Cette machine n'est ni un serveur d'authentification ni un proxy.
auth_service:
enabled: "no"
proxy_service:
enabled: "no"
# Le service SSH de Teleport : celui qui ouvre les sessions pour les administrateurs.
ssh_service:
enabled: "yes"
labels:
{% for nom, valeur in teleport_agent_labels.items() %}
{{ nom }}: {{ valeur }}
{% endfor %}
```
## Tâches
```yaml
# roles/teleport-agent/tasks/main.yml
# 1. Installer Teleport seulement s'il est absent.
- name: Chercher un Teleport déjà installé
ansible.builtin.command: which teleport
register: teleport_agent_installed
changed_when: false
failed_when: false # un code de retour non nul signifie simplement "absent"
- name: Installer Teleport (script officiel, version figée)
# Même méthode que la page « Installation » du livre Teleport.
# "set -o pipefail" : un échec de curl fait échouer toute la commande.
ansible.builtin.shell: |
set -o pipefail
curl -fsSL https://cdn.teleport.dev/install-v{{ teleport_agent_version }}.sh \
| bash -s {{ teleport_agent_version }} {{ teleport_agent_edition }}
args:
executable: /bin/bash
when: teleport_agent_installed.rc != 0
# 2. Savoir si la machine est déjà enrôlée.
# Le fichier host_uuid est créé au premier démarrage réussi de l'agent.
- name: Chercher une identité Teleport existante
ansible.builtin.stat:
path: /var/lib/teleport/host_uuid
register: teleport_agent_identity
# 3. Demander un jeton au bastion, seulement pour une première installation.
- name: Générer un jeton d'enrôlement sur le bastion
ansible.builtin.command: >-
tctl tokens add --type=node --ttl={{ teleport_agent_token_ttl }} --format=text
delegate_to: bastion # la commande s'exécute sur le bastion, pas sur la VM
register: teleport_join_token
changed_when: true # un nouveau jeton est créé à chaque exécution
no_log: true # le jeton est un secret : il ne doit pas apparaître dans les journaux
when: not teleport_agent_identity.stat.exists
# 4. Écrire la configuration (accès restreint : elle contient le jeton au premier passage).
- name: Déposer la configuration de l'agent
ansible.builtin.template:
src: teleport.yaml.j2
dest: /etc/teleport.yaml
owner: root
group: root
mode: "0600"
notify: Redémarrer teleport
no_log: true
# 5. Démarrer l'agent.
- name: Activer et démarrer l'agent Teleport
ansible.builtin.service:
name: teleport
state: started
enabled: true
```
```yaml
# roles/teleport-agent/handlers/main.yml
- name: Redémarrer teleport
ansible.builtin.service:
name: teleport
state: restarted
```
## Les droits des administrateurs
L'agent rattache la machine, mais ne dit pas qui a le droit de s'y connecter. Cela se définit dans des rôles Teleport, qui s'appuient sur les étiquettes de la machine. Dans Nébuleuse, une personne du support ne voit que les machines des clients qu'elle suit.
```yaml
# support-alpha.yaml : rôle Teleport (à créer une fois sur le bastion)
kind: role
version: v7
metadata:
name: support-alpha
spec:
allow:
# Comptes Unix sur la VM avec lesquels la session peut s'ouvrir.
logins: [deploy]
# Seules les machines portant l'étiquette client=alpha sont visibles.
node_labels:
client: alpha
```
```bash
# Sur le bastion : crée ou met à jour le rôle.
sudo tctl create -f support-alpha.yaml
# Crée un utilisateur avec ce rôle (même commande que dans le livre Teleport).
sudo tctl users add camille --roles=support-alpha
```
Note — Dans cet exemple, la session s'ouvre avec le compte `deploy`, qui a `sudo` sans mot de passe : donner ce login revient à donner les droits administrateur sur la VM. Pour un vrai support, un compte dédié avec des droits limités est préférable. Il s'ajouterait au socle système.
## L'authentification forte
La page de présentation parle d'authentification forte sur le bastion. Elle se configure côté serveur Teleport, dans la section `auth_service`. Voici le principe :
```yaml
# /etc/teleport.yaml sur le bastion (extrait)
auth_service:
authentication:
type: local
# La deuxième authentification est exigée pour chaque utilisateur.
# "webauthn" accepte les clés de sécurité matérielles et les passkeys.
second_factor: webauthn
webauthn:
rp_id: bastion.nebuleuse.example
```
Note — Ce paramètre appartient à l'installation du bastion, pas à l'agent. Il est à valider sur ta version de Teleport avant de le recopier dans la page d'installation.
## Déploiement
Le rôle s'insère dans `site.yml` juste après le socle :
```yaml
# site.yml (extrait)
roles:
- { role: base-hardening, tags: [base] }
- { role: docker-engine, tags: [docker] }
- { role: teleport-agent, tags: [teleport] }
```
```bash
# Un seul rôle, sur un seul client.
ansible-playbook site.yml --limit client-alpha --tags teleport
```
## Vérification
```bash
# Sur la VM : le service tourne et la connexion au bastion est établie.
systemctl status teleport --no-pager
journalctl -u teleport -n 20 --no-pager
# Sur le bastion : la machine est enrôlée, avec ses étiquettes.
sudo tctl nodes ls
```
Sur le portail web, la machine apparaît dans la liste des ressources sous le nom `client-alpha`, avec l'étiquette `client=alpha`. Depuis le poste d'un administrateur, la connexion se fait ensuite avec `tsh ssh deploy@client-alpha` après `tsh login`.
## Pièges
1. **Jeton expiré** : si le bastion est injoignable ou si le déploiement traîne, le jeton (30 minutes) expire avant le démarrage de l'agent. Le premier démarrage échoue, et les journaux de l'agent indiquent un jeton refusé. Il suffit de relancer le rôle : le fichier d'identité n'existant pas encore, un nouveau jeton est créé.
2. **Deuxième passage qui « change » quelque chose** : au premier passage, la configuration contient le jeton. Au deuxième, la machine est enrôlée, aucun jeton n'est généré, et le fichier est réécrit sans la section `join_params`. Ce changement unique est normal ; à partir du troisième passage, plus rien ne change.
3. **Agent plus récent que le bastion** : si la version de `teleport_agent_version` dépasse celle du bastion, l'agent est refusé. Mettre à jour le bastion en premier.
4. **Machine absente du portail** : vérifier que la VM atteint `bastion.nebuleuse.example:443` en sortie (pare-feu, DNS). L'agent n'a besoin d'aucun port entrant.
5. **Jeton visible dans un journal** : les tâches qui le manipulent portent `no_log: true`. Ne pas retirer cette ligne pour déboguer, ou le faire de façon temporaire et sur une VM de test.
6. **Chemin du binaire** : le test d'installation utilise la commande `which`, ce qui évite de dépendre de l'emplacement exact du binaire selon la version du paquet.
Page suivante : **Traefik**.
# Traefik
## Traefik, c'est quoi ?
Traefik est un reverse proxy conçu pour Docker. Il reçoit tout le trafic web d'une VM, lit les étiquettes (labels) posées sur les conteneurs, et en déduit seul vers quelle application envoyer chaque requête. Il obtient aussi les certificats HTTPS et les renouvelle automatiquement.
| Élément | Rôle |
|---|
| Point d'entrée `web` (port 80) | Reçoit le HTTP et redirige vers HTTPS ; sert au défi de validation Let's Encrypt |
| Point d'entrée `websecure` (port 443) | Reçoit le HTTPS et applique le certificat correspondant au nom demandé |
| Fournisseur Docker | Surveille les conteneurs et crée les routes à partir de leurs labels |
| Résolveur de certificats | Demande et renouvelle les certificats Let's Encrypt |
**Visiteur → `cloud.alpha.nebuleuse.example:443` → Traefik → conteneur Nextcloud**
Concrètement, ajouter une application ne demande jamais de modifier Traefik : il suffit que son conteneur soit sur le réseau `proxy` et porte les bons labels. Traefik le détecte à chaud, sans redémarrage.
## Prérequis
1. Le socle est en place : Docker installé, réseau `proxy` créé, ports 80 et 443 ouverts dans le pare-feu.
2. Un enregistrement DNS pointe chaque nom du client vers l'adresse publique de sa VM. Une entrée générique `*.alpha.nebuleuse.example` suffit.
3. Le port 80 est joignable depuis Internet : Let's Encrypt s'en sert pour vérifier que le domaine appartient bien au client.
4. Le domaine est réel. `nebuleuse.example` étant fictif, aucun certificat réel ne peut lui être délivré. Pour reproduire ce TP, remplacer le domaine par un domaine dont on dispose.
Note — Pendant les essais, activer le mode « staging » de Let's Encrypt (variable `traefik_acme_staging`). Les certificats délivrés ne sont pas reconnus par les navigateurs, mais le serveur de test n'impose pas les mêmes limites de demandes que le serveur réel, qui bloque un domaine après quelques échecs répétés.
## Arborescence du rôle
```text
roles/traefik/
├── defaults/main.yml
├── handlers/main.yml
├── tasks/main.yml
└── templates/
├── docker-compose.yml.j2
├── logrotate-traefik.j2
└── traefik.yml.j2
```
Sur la VM, le rôle crée :
```text
/opt/nebuleuse/traefik/
├── docker-compose.yml
├── traefik.yml # configuration statique
└── acme/acme.json # certificats (créé par Traefik, accès réservé à root)
/var/log/traefik/access.log # journal d'accès, lu par Fail2ban
```
## Variables
```yaml
# roles/traefik/defaults/main.yml
# Version de Traefik. Choisir une version récente : avec les versions récentes de Docker,
# une version trop ancienne de Traefik ne parvient plus à lire l'API Docker.
traefik_version: "v3.6"
# Dossier de travail sur la VM.
traefik_dir: /opt/nebuleuse/traefik
# Dossier du journal d'accès (monté dans le conteneur, lu par Fail2ban).
traefik_log_dir: /var/log/traefik
# Adresse e-mail déclarée auprès de Let's Encrypt (définie dans group_vars/all).
traefik_acme_email: "{{ nebuleuse_acme_email }}"
# true : utilise le serveur de test de Let's Encrypt (certificats non reconnus, sans limites strictes).
traefik_acme_staging: false
# Réseau Docker partagé avec les applications (défini dans group_vars/all).
traefik_network: "{{ docker_proxy_network }}"
# Noms de domaine que les applications doivent joindre à l'intérieur de la VM.
# Voir la section « Joindre le SSO depuis un conteneur ».
traefik_network_aliases:
- "{{ client_subdomains.sso }}.{{ client_domain }}"
```
## La configuration statique
La configuration statique décrit Traefik lui-même : ses ports, ses sources de configuration, ses certificats. Elle n'est lue qu'au démarrage.
```text
# roles/traefik/templates/traefik.yml.j2
# Fichier géré par Ansible : toute modification manuelle sera écrasée.
global:
# Pas de vérification de mise à jour ni de télémétrie : la VM n'a pas à contacter ces services.
checkNewVersion: false
sendAnonymousUsage: false
log:
level: INFO
# Journal d'accès : une ligne JSON par requête. Fail2ban le lit pour repérer les attaques.
accessLog:
filePath: /var/log/traefik/access.log
format: json
providers:
docker:
# Un conteneur n'est publié que s'il porte le label "traefik.enable=true".
exposedByDefault: false
# Réseau utilisé pour joindre les conteneurs.
network: {{ traefik_network }}
entryPoints:
web:
address: ":80"
http:
# Toute requête HTTP est redirigée vers HTTPS.
redirections:
entryPoint:
to: websecure
scheme: https
websecure:
address: ":443"
http:
tls:
# Tout routeur sur ce point d'entrée reçoit automatiquement un certificat
# pour le nom de sa règle Host(...).
certResolver: letsencrypt
certificatesResolvers:
letsencrypt:
acme:
email: {{ traefik_acme_email }}
# Emplacement des certificats : volume persistant, pour ne pas les redemander à chaque redémarrage.
storage: /acme/acme.json
{% if traefik_acme_staging %}
# Serveur de test de Let's Encrypt.
caServer: https://acme-staging-v02.api.letsencrypt.org/directory
{% endif %}
# Validation par HTTP : Let's Encrypt vérifie le domaine sur le port 80.
httpChallenge:
entryPoint: web
```
Note — Cette configuration obtient un certificat par nom de domaine. Pour un certificat unique couvrant tous les sous-domaines (certificat « wildcard »), il faut passer par la validation DNS, qui demande les identifiants de l'API du fournisseur de noms de domaine. C'est plus pratique, mais cela ajoute un secret par client.
## Le fichier Docker Compose
```text
# roles/traefik/templates/docker-compose.yml.j2
# Fichier géré par Ansible : toute modification manuelle sera écrasée.
services:
traefik:
image: traefik:{{ traefik_version }}
container_name: {{ client_name }}_traefik
restart: unless-stopped
# Interdit au processus de gagner de nouveaux privilèges.
security_opt:
- no-new-privileges:true
# Seul conteneur de la VM à publier des ports vers Internet.
ports:
- "80:80"
- "443:443"
volumes:
# Lecture de la liste des conteneurs. L'accès est en lecture seule, mais il donne
# tout de même une vue étendue sur Docker : voir « Pour aller plus loin ».
- /var/run/docker.sock:/var/run/docker.sock:ro
- {{ traefik_dir }}/traefik.yml:/etc/traefik/traefik.yml:ro
- {{ traefik_dir }}/acme:/acme
- {{ traefik_log_dir }}:/var/log/traefik
networks:
{{ traefik_network }}:
# Noms que les autres conteneurs peuvent joindre directement, sans sortir de la VM.
aliases:
{% for alias in traefik_network_aliases %}
- {{ alias }}
{% endfor %}
networks:
{{ traefik_network }}:
# Réseau créé par le rôle docker-engine : Compose ne doit pas le recréer.
external: true
```
## Rotation du journal d'accès
Un journal qui grossit sans limite finit par remplir le disque. Docker fait tourner les journaux de ses conteneurs, mais pas les fichiers que Traefik écrit lui-même. Une règle `logrotate` s'en charge.
```text
# roles/traefik/templates/logrotate-traefik.j2
{{ traefik_log_dir }}/access.log {
# Un fichier par jour, sept jours conservés.
daily
rotate 7
compress
delaycompress
missingok
notifempty
# Copie puis vide le fichier : Traefik continue d'écrire dans le même fichier ouvert.
copytruncate
}
```
## Tâches
```yaml
# roles/traefik/tasks/main.yml
- name: Créer les dossiers de Traefik
ansible.builtin.file:
path: "{{ item.path }}"
state: directory
mode: "{{ item.mode }}"
loop:
- { path: "{{ traefik_dir }}", mode: "0755" }
# Le dossier des certificats est réservé à root : il contient les clés privées.
- { path: "{{ traefik_dir }}/acme", mode: "0700" }
- { path: "{{ traefik_log_dir }}", mode: "0755" }
- name: Déposer la configuration statique de Traefik
ansible.builtin.template:
src: traefik.yml.j2
dest: "{{ traefik_dir }}/traefik.yml"
mode: "0644"
# Un changement de configuration statique demande un redémarrage.
notify: Redémarrer traefik
- name: Déposer le fichier Docker Compose de Traefik
ansible.builtin.template:
src: docker-compose.yml.j2
dest: "{{ traefik_dir }}/docker-compose.yml"
mode: "0644"
- name: Déposer la règle de rotation du journal d'accès
ansible.builtin.template:
src: logrotate-traefik.j2
dest: /etc/logrotate.d/traefik
mode: "0644"
- name: Démarrer Traefik
community.docker.docker_compose_v2:
project_src: "{{ traefik_dir }}"
# "present" crée ou met à jour les conteneurs, sans toucher à ceux déjà conformes.
state: present
- name: Attendre que Traefik écoute sur le port 443
# Le module s'exécute sur la VM : "127.0.0.1" désigne donc la VM elle-même.
ansible.builtin.wait_for:
host: 127.0.0.1
port: 443
timeout: 60
```
```yaml
# roles/traefik/handlers/main.yml
- name: Redémarrer traefik
community.docker.docker_compose_v2:
project_src: "{{ traefik_dir }}"
state: restarted
```
## Comment une application se déclare
Traefik n'a aucune liste d'applications : chaque conteneur se décrit lui-même avec des labels. Toutes les pages d'application suivent ce modèle, ici pour Nextcloud.
```text
# Extrait d'un docker-compose.yml.j2 d'application (exemple : Nextcloud)
labels:
# Publier ce conteneur (obligatoire, car exposedByDefault vaut false).
- "traefik.enable=true"
# Réseau à utiliser si le conteneur est sur plusieurs réseaux.
- "traefik.docker.network={{ docker_proxy_network }}"
# Règle de routage : les requêtes pour ce nom vont vers ce conteneur.
# Le nom du routeur (nextcloud-alpha) doit être unique sur la VM.
- "traefik.http.routers.nextcloud-{{ client_name }}.rule=Host(`{{ client_subdomains.nextcloud }}.{{ client_domain }}`)"
# Point d'entrée HTTPS : le certificat est demandé automatiquement.
- "traefik.http.routers.nextcloud-{{ client_name }}.entrypoints=websecure"
# Port d'écoute de l'application À L'INTÉRIEUR du conteneur.
- "traefik.http.services.nextcloud-{{ client_name }}.loadbalancer.server.port=80"
```
## Joindre le SSO depuis un conteneur
Une application doit parfois contacter le SSO de la VM, par exemple pour échanger un code de connexion contre un jeton. Elle le fait avec son adresse publique, `sso.alpha.nebuleuse.example`. Or ce nom pointe vers l'adresse publique de la VM, et un conteneur qui cherche à la joindre fait un détour par l'extérieur : le chemin fonctionne ou non selon la façon dont l'hébergeur attache l'adresse publique à la machine (adresse portée directement par la VM ou traduite par une passerelle).
Le plus fiable est d'éviter ce détour. Le rôle donne à Traefik un **alias** de réseau : sur le réseau `proxy`, le nom `sso.alpha.nebuleuse.example` est résolu vers le conteneur Traefik lui-même. L'application joint donc Traefik directement, sur le port 443, avec le même nom et le même certificat. Le résultat est le même pour l'utilisateur, sans dépendre de l'adresse publique.
```yaml
# Extrait de docker-compose.yml.j2 (généré par le rôle)
networks:
proxy:
aliases:
- sso.alpha.nebuleuse.example
```
Seul le nom du SSO a besoin de cet alias, car c'est le seul que les applications appellent entre elles. La variable `traefik_network_aliases` permet d'en ajouter d'autres si une application doit en joindre une autre.
## Vérification
```bash
# Sur la VM : Traefik est démarré et publie les ports 80 et 443.
docker ps --filter name=traefik --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
# La redirection HTTP vers HTTPS répond "301".
curl -sI http://127.0.0.1 | head -n 1
# Un nom sans application répond "404" : Traefik écoute, mais n'a aucune route pour lui.
curl -skI https://127.0.0.1 | head -n 1
# Journal de démarrage : aucune erreur de certificat attendue.
docker logs --tail 30 alpha_traefik
# Journal d'accès : le champ ClientHost doit contenir l'adresse du visiteur, pas celle de Docker.
sudo tail -n 3 /var/log/traefik/access.log | jq '{ClientHost, RequestHost, DownstreamStatus}'
```
Une fois une application déployée, le certificat apparaît avec :
```bash
# Affiche l'émetteur et les dates de validité du certificat de l'application.
echo | openssl s_client -connect cloud.alpha.nebuleuse.example:443 -servername cloud.alpha.nebuleuse.example 2>/dev/null | openssl x509 -noout -issuer -dates
```
## Pour aller plus loin
- **Protéger l'accès au socket Docker.** Même en lecture seule, le socket expose beaucoup d'informations sur la machine. Un intermédiaire comme `docker-socket-proxy` limite Traefik aux seules requêtes nécessaires.
- **Certificats wildcard** par validation DNS, pour ne pas dépendre de l'accès au port 80.
- **En-têtes de sécurité** (HSTS, `X-Content-Type-Options`) ajoutés par un middleware commun à toutes les applications.
## Pièges
1. **Limites de Let's Encrypt** : des demandes répétées en échec bloquent temporairement un domaine. Tester avec `traefik_acme_staging: true`, puis repasser à `false` en supprimant le contenu du dossier `acme` pour obtenir les vrais certificats.
2. **DNS pas encore propagé** : le défi échoue et le journal indique que le domaine ne pointe pas vers la VM. Vérifier l'enregistrement avant de redémarrer Traefik.
3. **Application inaccessible, erreur 404** : le label `traefik.enable=true` ou la règle `Host(...)` est absente ou erronée. Le routeur n'existe pas, donc Traefik ne sait pas où envoyer la requête.
4. **Application inaccessible, erreur 502 ou 504** : Traefik trouve la route mais n'atteint pas le conteneur. Causes habituelles : mauvais port dans le label `loadbalancer.server.port`, conteneur absent du réseau `proxy`, ou conteneur sur plusieurs réseaux sans label `traefik.docker.network`.
5. **Traefik ne détecte plus aucun conteneur** : avec les versions récentes de Docker, une version trop ancienne de Traefik n'arrive plus à lire l'API Docker. Le journal mentionne une version d'API trop ancienne. Mettre à jour `traefik_version`.
6. **Adresse du visiteur remplacée par celle de la passerelle Docker** : le journal d'accès montre l'adresse interne de Docker au lieu de celle du visiteur, ce qui rend Fail2ban inefficace. Le cas se rencontre surtout avec les connexions IPv6 ou lorsqu'un intermédiaire est placé devant la VM. Le contrôle se fait avec la dernière commande de vérification, depuis une adresse extérieure.
7. **Noms de routeur en double** : deux conteneurs qui déclarent le même nom de routeur se contredisent, et seul l'un des deux fonctionne. Le nom du client dans le nom du routeur évite les collisions entre projets.
8. **Modification de `traefik.yml` sans effet** : la configuration statique n'est lue qu'au démarrage. Le handler redémarre Traefik quand le fichier change ; les labels, eux, sont pris en compte à chaud.
Page suivante : **Authentik (SSO)**.
# Authentik (SSO)
## Authentik, c'est quoi ?
Authentik est un fournisseur d'identité : il détient les comptes des utilisateurs et dit aux applications qui est connecté. Une application qui lui délègue la connexion n'a plus de mots de passe à gérer : l'utilisateur se connecte une fois sur Authentik, puis accède à toutes les applications de la VM. Le protocole utilisé est OpenID Connect (OIDC).
| Élément | Rôle |
|---|
| Serveur Authentik | Interface web, API et pages de connexion |
| Worker Authentik | Tâches de fond (envoi d'e-mails, nettoyage, synchronisations) |
| PostgreSQL | Base de données d'Authentik (comptes, configuration) |
| Provider OIDC | Définit comment une application se connecte (identifiant, secret, adresses de retour) |
| Application | Objet Authentik qui rattache un provider à une application et à ses règles d'accès |
**Utilisateur → Application → redirection vers Authentik → connexion → retour à l'application avec un jeton**
Concrètement, chaque application commandée par un client a besoin d'un provider et d'une application dans Authentik, créés avec les bons réglages. Faire ces réglages à la main dans l'interface est long et source d'erreurs. Le rôle les fait donc par l'API d'Authentik, avec un jeu de tâches réutilisable que toutes les pages d'application appellent.
## Prérequis
1. Traefik est en place et publie `sso.alpha.nebuleuse.example` (page précédente).
2. Quatre secrets existent dans le Vault du client : `vault_authentik_secret_key`, `vault_authentik_db_password`, `vault_authentik_bootstrap_password` et `vault_authentik_bootstrap_token`. Les deux derniers complètent la liste de la page « Inventaire et variables ».
3. `curl` est installé sur la VM (fait par le socle).
Note — Le mot de passe et le jeton d'amorçage ne sont lus qu'au tout premier démarrage d'Authentik : ils créent le compte administrateur `akadmin` et son jeton d'API. Les modifier ensuite dans le Vault ne change rien dans Authentik.
## Arborescence du rôle
```text
roles/authentik/
├── defaults/main.yml
├── tasks/
│ ├── main.yml # déploiement, attente, découverte des objets communs
│ ├── oidc_app.yml # création d'un provider et d'une application OIDC (réutilisable)
│ └── first_user.yml # création du premier compte du client
└── templates/
└── docker-compose.yml.j2
```
## Variables
```yaml
# roles/authentik/defaults/main.yml
# Version d'Authentik : remplacer par la dernière version stable (voir les notes de version).
# Depuis la version 2025.10, Redis n'est plus nécessaire. Sur une version plus ancienne,
# un conteneur Redis doit être ajouté au fichier Docker Compose.
authentik_version: "2025.10"
# Dossier de travail sur la VM.
authentik_dir: /opt/nebuleuse/authentik
# Nom de domaine d'Authentik et adresse de son API.
authentik_host: "{{ client_subdomains.sso }}.{{ client_domain }}"
authentik_api: "https://{{ authentik_host }}/api/v3"
# Secrets : définis dans le Vault, jamais en clair ici.
authentik_secret_key: "{{ vault_authentik_secret_key }}"
authentik_db_password: "{{ vault_authentik_db_password }}"
authentik_bootstrap_password: "{{ vault_authentik_bootstrap_password }}"
authentik_bootstrap_token: "{{ vault_authentik_bootstrap_token }}"
# Réseau Docker partagé avec Traefik.
authentik_network: "{{ docker_proxy_network }}"
# Flux d'autorisation utilisé par les applications.
# "explicit-consent" : l'utilisateur valide un écran de consentement à la première connexion.
# Il existe aussi une variante "implicit-consent", sans écran de validation.
authentik_authorization_flow_slug: default-provider-authorization-explicit-consent
authentik_invalidation_flow_slug: default-provider-invalidation-flow
# Fichier d'en-tête contenant le jeton d'API (lu par curl, jamais passé en argument).
authentik_api_header_file: /root/.authentik-api-header
# Base de toutes les commandes curl qui appellent l'API.
# -sS : silencieux, mais affiche les erreurs
# -k : n'exige pas de certificat reconnu (nécessaire en mode "staging")
# --fail-with-body : échoue sur une erreur HTTP, en affichant la réponse du serveur
# --resolve : résout le nom d'Authentik vers la VM elle-même, sans passer par le DNS
# -H @fichier : lit l'en-tête d'authentification dans un fichier
authentik_curl_base:
- curl
- -sS
- -k
- --fail-with-body
- --resolve
- "{{ authentik_host }}:443:127.0.0.1"
- -H
- "@{{ authentik_api_header_file }}"
```
## Le fichier Docker Compose
```text
# roles/authentik/templates/docker-compose.yml.j2
# Fichier géré par Ansible : toute modification manuelle sera écrasée.
# Il contient des secrets : accès réservé à root.
# Variables communes au serveur et au worker (ancre YAML réutilisée plus bas).
x-authentik-env: &authentik_env
AUTHENTIK_SECRET_KEY: "{{ authentik_secret_key }}"
AUTHENTIK_POSTGRESQL__HOST: db
AUTHENTIK_POSTGRESQL__USER: authentik
AUTHENTIK_POSTGRESQL__NAME: authentik
AUTHENTIK_POSTGRESQL__PASSWORD: "{{ authentik_db_password }}"
# Lus uniquement au premier démarrage : créent le compte "akadmin" et son jeton d'API.
AUTHENTIK_BOOTSTRAP_PASSWORD: "{{ authentik_bootstrap_password }}"
AUTHENTIK_BOOTSTRAP_TOKEN: "{{ authentik_bootstrap_token }}"
AUTHENTIK_BOOTSTRAP_EMAIL: "{{ client_admin_email }}"
services:
server:
image: ghcr.io/goauthentik/server:{{ authentik_version }}
container_name: {{ client_name }}_authentik_server
restart: unless-stopped
command: server
environment: *authentik_env
volumes:
- {{ authentik_dir }}/media:/media
- {{ authentik_dir }}/custom-templates:/templates
depends_on:
db:
condition: service_healthy
networks:
- {{ authentik_network }}
- internal
labels:
- "traefik.enable=true"
- "traefik.docker.network={{ authentik_network }}"
- "traefik.http.routers.authentik-{{ client_name }}.rule=Host(`{{ authentik_host }}`)"
- "traefik.http.routers.authentik-{{ client_name }}.entrypoints=websecure"
# Port HTTP interne d'Authentik.
- "traefik.http.services.authentik-{{ client_name }}.loadbalancer.server.port=9000"
worker:
image: ghcr.io/goauthentik/server:{{ authentik_version }}
container_name: {{ client_name }}_authentik_worker
restart: unless-stopped
command: worker
environment: *authentik_env
volumes:
- {{ authentik_dir }}/media:/media
- {{ authentik_dir }}/custom-templates:/templates
depends_on:
db:
condition: service_healthy
# Le worker n'a pas besoin d'être joignable : réseau interne uniquement.
networks:
- internal
db:
image: postgres:16-alpine
container_name: {{ client_name }}_authentik_db
restart: unless-stopped
environment:
POSTGRES_USER: authentik
POSTGRES_DB: authentik
POSTGRES_PASSWORD: "{{ authentik_db_password }}"
volumes:
- {{ authentik_dir }}/db-data:/var/lib/postgresql/data
# Les autres services attendent que la base soit prête avant de démarrer.
healthcheck:
test: ["CMD-SHELL", "pg_isready -d authentik -U authentik"]
interval: 5s
timeout: 5s
retries: 10
# La base n'est jamais exposée sur le réseau partagé avec Traefik.
networks:
- internal
networks:
{{ authentik_network }}:
external: true
internal: {}
```
Note — Seul le serveur est sur le réseau partagé `proxy`. La base de données et le worker restent sur un réseau privé au projet : aucune autre application de la VM ne peut atteindre la base d'Authentik.
## Déploiement et découverte des objets communs
La première partie du rôle déploie les conteneurs, attend que l'API réponde, puis retrouve les objets d'Authentik dont tous les providers ont besoin : les deux flux, les mappings de scope et la règle d'accès.
```yaml
# roles/authentik/tasks/main.yml
- name: Créer les dossiers d'Authentik
ansible.builtin.file:
path: "{{ item }}"
state: directory
mode: "0755"
loop:
- "{{ authentik_dir }}"
- "{{ authentik_dir }}/media"
- "{{ authentik_dir }}/custom-templates"
- "{{ authentik_dir }}/db-data"
- name: Déposer le fichier Docker Compose d'Authentik
ansible.builtin.template:
src: docker-compose.yml.j2
dest: "{{ authentik_dir }}/docker-compose.yml"
# Le fichier contient des secrets : root uniquement.
mode: "0600"
no_log: true
- name: Démarrer Authentik
community.docker.docker_compose_v2:
project_src: "{{ authentik_dir }}"
state: present
# Le premier démarrage applique les migrations de la base : cela peut durer plusieurs minutes.
- name: Attendre que l'API d'Authentik soit prête
ansible.builtin.command:
argv:
- curl
- -fsS
- -k
- --resolve
- "{{ authentik_host }}:443:127.0.0.1"
- "https://{{ authentik_host }}/-/health/live/"
register: authentik_ready
until: authentik_ready.rc == 0
retries: 60
delay: 5
changed_when: false
# Le jeton est écrit dans un fichier d'en-tête plutôt que passé en argument à curl :
# il n'apparaît ni dans la liste des processus, ni dans les journaux d'Ansible.
- name: Déposer le fichier d'en-tête d'authentification pour l'API
ansible.builtin.copy:
dest: "{{ authentik_api_header_file }}"
content: "Authorization: Bearer {{ authentik_bootstrap_token }}\n"
owner: root
group: root
mode: "0600"
no_log: true
# --- Découverte des objets communs à tous les providers ---
- name: Trouver le flux d'autorisation
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/flows/instances/?slug=' ~ authentik_authorization_flow_slug] }}"
register: authentik_authz_flow_raw
changed_when: false
- name: Trouver le flux d'invalidation
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/flows/instances/?slug=' ~ authentik_invalidation_flow_slug] }}"
register: authentik_invalidation_flow_raw
changed_when: false
- name: Lister les mappings de scope
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/propertymappings/provider/scope/?page_size=200'] }}"
register: authentik_scope_mappings_raw
changed_when: false
- name: Retenir les identifiants des objets trouvés
ansible.builtin.set_fact:
authentik_authz_flow_pk: "{{ (authentik_authz_flow_raw.stdout | from_json).results[0].pk }}"
authentik_invalidation_flow_pk: "{{ (authentik_invalidation_flow_raw.stdout | from_json).results[0].pk }}"
# Les trois mappings standard : sans eux, l'application reçoit un jeton sans identité.
authentik_scope_mapping_pks: >-
{{ (authentik_scope_mappings_raw.stdout | from_json).results
| selectattr('scope_name', 'in', ['openid', 'profile', 'email'])
| map(attribute='pk') | list }}
# --- Règle d'accès : "toute personne connectée peut utiliser l'application" ---
- name: Chercher la règle d'accès Nébuleuse
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/policies/expression/?name=nebuleuse-allow-all'] }}"
register: authentik_policy_raw
changed_when: false
- name: Créer la règle d'accès si elle est absente
ansible.builtin.command:
argv: >-
{{ authentik_curl_base + ['-X', 'POST', '-H', 'Content-Type: application/json',
'--data-binary', ({'name': 'nebuleuse-allow-all', 'expression': 'return True'} | to_json),
authentik_api ~ '/policies/expression/'] }}
register: authentik_policy_created
when: (authentik_policy_raw.stdout | from_json).results | length == 0
- name: Retenir l'identifiant de la règle d'accès
ansible.builtin.set_fact:
authentik_allow_policy_pk: >-
{{ (authentik_policy_created.stdout | from_json).pk
if authentik_policy_created is not skipped
else (authentik_policy_raw.stdout | from_json).results[0].pk }}
```
Note — Les commandes `curl` sont lancées avec `argv` (une liste d'arguments) plutôt qu'avec une chaîne : il n'y a ainsi aucun guillemet à échapper dans le JSON. Dans ce déploiement, le module `ansible.builtin.uri` n'a pas été retenu : `curl` s'est montré plus prévisible, notamment avec `--resolve` et les certificats de test.
## Créer une connexion OIDC pour une application
Ce fichier de tâches est le cœur de l'intégration. Il est appelé une fois par application, avec trois paramètres : le nom, l'identifiant court (le « slug ») et les adresses de retour autorisées. Il crée le provider, l'application, lie la règle d'accès, puis retourne l'identifiant client, le secret et l'adresse de l'émetteur.
```yaml
# roles/authentik/tasks/oidc_app.yml
#
# Paramètres attendus :
# oidc_app_name : nom affiché dans Authentik (ex. "Nextcloud")
# oidc_app_slug : identifiant court, utilisé dans les adresses (ex. "nextcloud")
# oidc_redirect_uris : liste d'adresses de retour autorisées
# [{ matching_mode: strict, url: "https://..." }]
# oidc_sub_mode : (facultatif) identifiant d'utilisateur transmis à l'application
#
# Résultats :
# oidc_client_id, oidc_client_secret, oidc_issuer
# 1. Le provider : décrit comment l'application se connecte.
- name: "{{ oidc_app_name }} : chercher le provider"
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/providers/oauth2/?name=' ~ oidc_app_slug] }}"
register: oidc_provider_lookup
changed_when: false
no_log: true # la réponse contient le secret client
- name: "{{ oidc_app_name }} : créer le provider s'il est absent"
ansible.builtin.command:
argv: >-
{{ authentik_curl_base + ['-X', 'POST', '-H', 'Content-Type: application/json',
'--data-binary', (oidc_provider_payload | to_json),
authentik_api ~ '/providers/oauth2/'] }}
vars:
oidc_provider_payload:
name: "{{ oidc_app_slug }}"
# Flux d'AUTORISATION : pas le flux d'authentification, sinon l'utilisateur boucle sur la connexion.
authorization_flow: "{{ authentik_authz_flow_pk }}"
invalidation_flow: "{{ authentik_invalidation_flow_pk }}"
# "confidential" : l'application garde un secret côté serveur.
client_type: confidential
# Identifiant transmis à l'application pour désigner l'utilisateur (voir la section Pièges).
sub_mode: "{{ oidc_sub_mode | default('hashed_user_id') }}"
# Adresses de retour : "strict" exige une correspondance exacte, caractère pour caractère.
redirect_uris: "{{ oidc_redirect_uris }}"
# Les mappings openid, profile et email : sans eux, "scopes demandés non configurés".
property_mappings: "{{ authentik_scope_mapping_pks }}"
register: oidc_provider_created
when: (oidc_provider_lookup.stdout | from_json).results | length == 0
no_log: true
- name: "{{ oidc_app_name }} : retenir le provider"
ansible.builtin.set_fact:
oidc_provider: >-
{{ (oidc_provider_created.stdout | from_json)
if oidc_provider_created is not skipped
else (oidc_provider_lookup.stdout | from_json).results[0] }}
no_log: true
# 2. L'application : rattache le provider à un nom et à des règles d'accès.
- name: "{{ oidc_app_name }} : chercher l'application"
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/core/applications/?slug=' ~ oidc_app_slug] }}"
register: oidc_app_lookup
changed_when: false
- name: "{{ oidc_app_name }} : créer l'application si elle est absente"
ansible.builtin.command:
argv: >-
{{ authentik_curl_base + ['-X', 'POST', '-H', 'Content-Type: application/json',
'--data-binary', (oidc_app_payload | to_json),
authentik_api ~ '/core/applications/'] }}
vars:
oidc_app_payload:
name: "{{ oidc_app_name }}"
slug: "{{ oidc_app_slug }}"
provider: "{{ oidc_provider.pk }}"
policy_engine_mode: any
register: oidc_app_created
when: (oidc_app_lookup.stdout | from_json).results | length == 0
- name: "{{ oidc_app_name }} : retenir l'application"
ansible.builtin.set_fact:
oidc_app_pk: >-
{{ (oidc_app_created.stdout | from_json).pk
if oidc_app_created is not skipped
else (oidc_app_lookup.stdout | from_json).results[0].pk }}
# 3. La règle d'accès : sans elle, la connexion se termine par "Accès refusé".
# Elle n'est liée qu'à la création de l'application, pour ne pas multiplier les liens.
- name: "{{ oidc_app_name }} : lier la règle d'accès à l'application"
ansible.builtin.command:
argv: >-
{{ authentik_curl_base + ['-X', 'POST', '-H', 'Content-Type: application/json',
'--data-binary', (oidc_binding_payload | to_json),
authentik_api ~ '/policies/bindings/'] }}
vars:
oidc_binding_payload:
target: "{{ oidc_app_pk }}"
policy: "{{ authentik_allow_policy_pk }}"
order: 0
when: oidc_app_created is not skipped
# 4. Les valeurs que l'application doit connaître.
- name: "{{ oidc_app_name }} : retenir les valeurs de connexion"
ansible.builtin.set_fact:
oidc_client_id: "{{ oidc_provider.client_id }}"
oidc_client_secret: "{{ oidc_provider.client_secret }}"
# Adresse de l'émetteur : l'application y trouve la découverte automatique de la configuration.
oidc_issuer: "https://{{ authentik_host }}/application/o/{{ oidc_app_slug }}/"
no_log: true
```
Une page d'application appelle ce fichier de tâches ainsi :
```yaml
# roles/nextcloud/tasks/main.yml (extrait)
- name: Créer la connexion SSO de Nextcloud
ansible.builtin.include_tasks: ../../authentik/tasks/oidc_app.yml
vars:
oidc_app_name: Nextcloud
oidc_app_slug: nextcloud
oidc_redirect_uris:
- matching_mode: strict
url: "https://{{ client_subdomains.nextcloud }}.{{ client_domain }}/apps/user_oidc/code"
```
Les adresses OIDC dont l'application a besoin sont toutes construites à partir de l'adresse de l'émetteur :
| Usage | Adresse |
|---|
| Découverte automatique | `https://sso.alpha.nebuleuse.example/application/o//.well-known/openid-configuration` |
| Autorisation | `https://sso.alpha.nebuleuse.example/application/o/authorize/` |
| Jeton | `https://sso.alpha.nebuleuse.example/application/o/token/` |
| Informations sur l'utilisateur | `https://sso.alpha.nebuleuse.example/application/o/userinfo/` |
| Déconnexion | `https://sso.alpha.nebuleuse.example/application/o//end-session/` |
## Le premier compte du client
Le compte `akadmin` sert à l'exploitation par Nébuleuse. Le client a besoin de son propre compte, créé à partir de `client_admin_email`. Son mot de passe n'est volontairement pas défini ici : il est choisi par le client, par un lien de réinitialisation envoyé par le support.
```yaml
# roles/authentik/tasks/first_user.yml
- name: Chercher le compte du client
ansible.builtin.command:
argv: "{{ authentik_curl_base + [authentik_api ~ '/core/users/?username=' ~ client_admin_email] }}"
register: authentik_user_lookup
changed_when: false
- name: Créer le compte du client s'il est absent
ansible.builtin.command:
argv: >-
{{ authentik_curl_base + ['-X', 'POST', '-H', 'Content-Type: application/json',
'--data-binary', (authentik_user_payload | to_json),
authentik_api ~ '/core/users/'] }}
vars:
authentik_user_payload:
username: "{{ client_admin_email }}"
name: "Administrateur {{ client_name }}"
email: "{{ client_admin_email }}"
is_active: true
when: (authentik_user_lookup.stdout | from_json).results | length == 0
```
Dans `main.yml`, ce fichier est inclus à la fin du rôle :
```yaml
# roles/authentik/tasks/main.yml (fin du fichier)
- name: Créer le premier compte du client
ansible.builtin.include_tasks: first_user.yml
```
## Vérification
```bash
# Sur la VM : les trois conteneurs sont démarrés et la base est « healthy ».
docker ps --filter name=authentik --format '{{.Names}}\t{{.Status}}'
# L'API répond et reconnaît le jeton : doit afficher l'utilisateur "akadmin".
curl -sSk --resolve sso.alpha.nebuleuse.example:443:127.0.0.1 \
-H @/root/.authentik-api-header \
https://sso.alpha.nebuleuse.example/api/v3/core/users/me/ | jq '.user.username'
# Une connexion OIDC existe et la découverte automatique répond (exemple : Nextcloud).
curl -sSk --resolve sso.alpha.nebuleuse.example:443:127.0.0.1 \
https://sso.alpha.nebuleuse.example/application/o/nextcloud/.well-known/openid-configuration | jq '.issuer'
```
Dans l'interface, on se connecte sur `https://sso.alpha.nebuleuse.example/if/admin/` avec `akadmin` et le mot de passe d'amorçage. Les rubriques **Applications** et **Providers** doivent lister chaque application commandée.
## Pièges
1. **Flux d'authentification à la place du flux d'autorisation** : l'utilisateur se reconnecte en boucle au lieu d'être renvoyé vers l'application. Le provider doit utiliser un flux dont le slug commence par `default-provider-authorization-`.
2. **Mappings de scope absents** : l'erreur « Application requested scopes not configured » apparaît. Les trois mappings `openid`, `profile` et `email` doivent être attachés au provider.
3. **« Accès refusé » après une connexion réussie** : dans le déploiement qui sert de base à ce TP, une application sans règle liée refusait l'accès. La règle `return True` est liée à chaque application pour l'autoriser à toute personne connectée.
4. **`sub_mode` inadapté** : c'est l'identifiant de l'utilisateur transmis à l'application. La valeur par défaut `hashed_user_id` convient à la plupart des applications. Une application qui attend un UUID (PaperMerge, par exemple) échoue avec une erreur de format : utiliser `user_uuid`. Les valeurs possibles sont `hashed_user_id`, `user_id`, `user_uuid`, `user_username`, `user_email` et `user_upn`.
5. **Utilisateur introuvable côté application** : certaines applications font correspondre l'utilisateur d'Authentik à un compte qu'elles ont déjà. Le nom d'utilisateur et l'adresse e-mail doivent alors être identiques de part et d'autre, et la connexion doit se faire avec ce compte, pas avec `akadmin`.
6. **Adresse de retour différente** : l'adresse déclarée dans Authentik et celle utilisée par l'application doivent être identiques, y compris pour un `/` final. L'erreur affichée mentionne une URI de redirection invalide.
7. **Compter avec `.count`** : la liste des résultats d'Authentik est dans `.results`, et le nombre d'éléments dans `.pagination.count`. Un `.count` direct provoque l'erreur « 'dict object' has no attribute 'count' ». Le rôle compte avec `.results | length`.
8. **Jeton visible dans la liste des processus ou dans les journaux** : le passer en argument de `curl` l'expose. D'où le fichier d'en-tête en mode `0600` et les `no_log: true`.
9. **Modifier un provider existant** : le rôle ne met pas à jour un provider déjà créé. Si les adresses de retour changent, il faut les modifier dans l'interface, ou supprimer le provider pour qu'il soit recréé.
10. **Premier démarrage long** : les migrations de la base peuvent prendre plusieurs minutes. Le rôle attend jusqu'à cinq minutes avant d'abandonner.
11. **Version de Redis** : sur une version d'Authentik antérieure à 2025.10, le serveur et le worker exigent un conteneur Redis, absent du fichier Compose de cette page.
## Pour aller plus loin
- **Remplacer le jeton d'amorçage** par un compte de service dédié, aux droits limités à la gestion des providers, puis supprimer le jeton d'amorçage une fois le déploiement terminé.
- **Configurer l'envoi d'e-mails** (SMTP) pour que les liens de réinitialisation et les notifications partent directement d'Authentik.
- **Déclarer la configuration par « blueprints »** : Authentik sait charger des fichiers de description, une alternative à l'API qui offre une vraie mise à jour déclarative.
Page suivante : **Nextcloud**.