CouchDB : utilisateurs et droits

Deux niveaux de comptes

Niveau	Rôle	Stockage
Administrateurs	Tout faire sur le serveur (bases, configuration, utilisateurs)	Fichier de configuration ([admins] de local.ini)
Utilisateurs	Accès aux bases selon leurs droits	Base _users

Les mots de passe sont stockés hachés (PBKDF2) : saisis en clair dans l’API ou le fichier, CouchDB les remplace par leur empreinte.

Administrateurs

# créer ou changer le mot de passe d'un administrateur
curl -sn -X PUT "$COUCH/_node/_local/_config/admins/gestion" -d '"<mot-de-passe>"'
curl -sn "$COUCH/_node/_local/_config/admins" | jq .
curl -sn -X DELETE "$COUCH/_node/_local/_config/admins/gestion"

Un seul administrateur suffit pour commencer ; en créer d’autres nominatifs facilite le suivi. Le mot de passe fourni dans la commande peut apparaître dans l’historique du shell : préférer Fauxton (via tunnel SSH) pour créer un compte, ou désactiver l’historique le temps de la commande.

Utilisateurs

Créer un utilisateur, c’est créer un document dans _users :

curl -sn -X PUT "$COUCH/_users/org.couchdb.user:alice" \
  -H 'Content-Type: application/json' \
  -d '{"name":"alice","password":"<mot-de-passe>","roles":["vendeurs"],"type":"user"}'
curl -sn "$COUCH/_users/org.couchdb.user:alice" | jq .

L’identifiant du document doit être org.couchdb.user: suivi du nom. Le champ password est remplacé par derived_key et salt dès l’enregistrement.

Lister et supprimer :

curl -sn "$COUCH/_users/_all_docs" | jq '.rows[].id'
curl -sn -X DELETE "$COUCH/_users/org.couchdb.user:alice?rev=1-…"

Changer un mot de passe : relire le document, remplacer password, renvoyer avec le bon _rev.

Droits d’une base : _security

Par défaut, une base est lisible par tout le monde, y compris les anonymes. Définir _security pour restreindre :

curl -sn -X PUT "$COUCH/boutique/_security" -H 'Content-Type: application/json' -d '{
  "admins":  { "names": [], "roles": ["gestionnaires"] },
  "members": { "names": ["alice"], "roles": ["vendeurs"] }
}'
curl -sn "$COUCH/boutique/_security" | jq .

Section	Droits
admins	Lire, écrire, gérer les documents de conception et _security
members	Lire et écrire les documents (pas les documents de conception)
Les deux vides	Base publique : tout le monde lit et écrit selon la configuration

Attention

Avec members vide, la base est ouverte à tout visiteur pouvant joindre le serveur. Toujours renseigner members (au moins un nom ou un rôle) pour toute base contenant des données non publiques.

Vérifier :

curl -s -o /dev/null -w '%{http_code}\n' "$COUCH/boutique/_all_docs"          # 401 sans identifiants
curl -s -o /dev/null -w '%{http_code}\n' -u alice "$COUCH/boutique/_all_docs"  # 200 avec le mot de passe

Authentification des clients

curl -u alice "$COUCH/boutique/_all_docs"                 # authentification basique
curl -si -X POST "$COUCH/_session" -H 'Content-Type: application/json' \
  -d '{"name":"alice","password":"<mot-de-passe>"}' -c cookies.txt
curl -s -b cookies.txt "$COUCH/boutique/_all_docs" | jq .total_rows

Les applications utilisent une session par cookie (/_session) ou l’authentification basique uniquement en HTTPS. Une application web ne doit pas embarquer d’identifiants administrateur : créer un compte applicatif avec les droits minimaux.

Validation des écritures

Un document de conception peut refuser des écritures :

curl -sn -X PUT "$COUCH/boutique/_design/validation" -H 'Content-Type: application/json' -d '{
  "validate_doc_update": "function(nouveau, ancien, utilisateur) { if (!nouveau._deleted && nouveau.type === \"client\" && !nouveau.email) { throw({forbidden: \"email obligatoire\"}); } }"
}'

Accès distant

Trois conditions :

1. CouchDB n’écoute que sur 127.0.0.1 par défaut : ne pas exposer le port 5984 directement.
2. Publier derrière un reverse proxy HTTPS (Caddy) :

couch.exemple.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5984
}

3. Restreindre : ne publier que l’API nécessaire. Pour Fauxton et l’administration, préférer un tunnel SSH (voir SSH : tunnels). Voir aussi Caddy : exemples réutilisables.

Pare-feu (seuls 22, 80 et 443 ouverts ; voir UFW : écrire des règles) :

sudo ufw allow 80,443/tcp
sudo ss -tlnp | grep 5984             # 127.0.0.1:5984

Pour réplication entre serveurs : autoriser uniquement l’adresse de l’autre serveur (sudo ufw allow from 203.0.113.20 to any port 5984 proto tcp) et utiliser HTTPS.

CORS

Pour qu’une application web d’un autre domaine appelle l’API depuis un navigateur :

curl -sn -X PUT "$COUCH/_node/_local/_config/chttpd/enable_cors" -d '"true"'
curl -sn -X PUT "$COUCH/_node/_local/_config/cors/origins" -d '"https://app.exemple.com"'
curl -sn -X PUT "$COUCH/_node/_local/_config/cors/credentials" -d '"true"'
curl -sn -X PUT "$COUCH/_node/_local/_config/cors/methods" -d '"GET, PUT, POST, HEAD, DELETE"'
curl -sn -X PUT "$COUCH/_node/_local/_config/cors/headers" -d '"accept, authorization, content-type, origin, referer"'

Ne pas utiliser origins = * avec des identifiants.

Dépannage

Symptôme	Piste
{"error":"forbidden","reason":"You are not a db member."}	Utilisateur absent de members de la base
{"error":"unauthorized","reason":"Name or password is incorrect."}	Identifiants erronés
La base reste accessible sans mot de passe	_security vide ou members vide
Un utilisateur créé ne peut pas se connecter	Mauvais format de l’identifiant (org.couchdb.user:nom), type manquant
Erreur CORS dans le navigateur	enable_cors, origins, en-têtes autorisés
{"error":"forbidden","reason":"Only administrators can …"}	Action réservée aux administrateurs

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune : la gestion des accès dépend de CouchDB.

Pour aller plus loin

• Sécurité de CouchDB
• Suite : Index et performances

Dans la même rubrique

• Installation
• Utilisation en console
• Bases et documents
• Requêtes
• Utilisateurs et droits
• Index et performances
• Sauvegarde et réplication