Barrel
EN GitHub

Authentification

barrel_server est ouvert tant que vous ne configurez pas auth. Vous pouvez alors accepter des jetons bearer globaux, des jetons de capacité par espace, des requêtes signées Ed25519 et des certificats clients (mTLS). Les clients de réplication trouvent leurs identifiants dans l’app env de barrel_docdb. Lisez cette page avant d’exposer un serveur, de donner accès à un navigateur ou à un agent, ou de répliquer entre nœuds.

Quelle méthode

MéthodeQui l’utiliseCe qu’elle prouve
Bearer globalOpérateurs, services de confianceLe détenteur d’un secret partagé ; accès complet
Jeton de capacité (bsp_...)Agents, navigateursLe détenteur d’un jeton pour un espace, avec des droits
Requête signée (Ed25519, v3)Nœuds qui répliquentLe détenteur de la clé a envoyé exactement cette requête
mTLSNœuds sur un réseau privéUn certificat de votre autorité de certification ; pas quel client

Sans TLS, un jeton bearer peut être capturé et rejoué. Faites tourner le serveur en HTTPS quand vous utilisez des jetons sur un réseau non fiable.

Jetons bearer

{barrel_server, [{auth, #{tokens => [<<"s3cret">>]}}]}

Chaque route sauf /health exige alors Authorization: Bearer <token>. Une liste vous permet la rotation : ajoutez le nouveau jeton, basculez les clients, retirez l’ancien. / n’est plus public une fois l’auth activée.

curl localhost:8080/db/demo/doc/a
curl -H 'authorization: Bearer s3cret' \
  localhost:8080/db/demo/doc/a
Sortie d’une exécution sur barrel_server 1.13.0
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
{"error":"unauthorized"}

HTTP/1.1 200 OK
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7","id":"a",
"kind":"note","n":1,"title":"hello world"}

Jetons de capacité

Un jeton de capacité est émis pour un espace avec les droits read, write ou admin (voir Espaces et capacités) :

curl -X POST localhost:8080/spaces/sp_wh2tq2ocmemj52ln/grants \
  -H 'authorization: Bearer s3cret' \
  -H 'content-type: application/json' \
  -d '{"rights":["read"],"subject":"agent-1"}'

Il est accepté sur /spaces, /handoffs, /mcp, et sur /db/:db/... quand :db est l’espace concerné. Un jeton de lecture sur son propre espace, puis une écriture, une autre base, et un appel sur le cycle de vie d’une base :

Réponses d’une exécution sur barrel_server 1.13.0, une ligne par requête
GET /db/sp_wh2tq2ocmemj52ln         200 OK
PUT /db/sp_wh2tq2ocmemj52ln/doc/x   403 {"error":"forbidden"}
GET /db/demo/doc/a                  403 {"error":"forbidden"}
PUT /db/sp_wh2tq2ocmemj52ln         403 {"error":"forbidden"}

Un jeton mort ou inconnu répond 401 ; un jeton valide sur le mauvais espace ou sans le droit voulu répond 403. Le cycle de vie des bases, _timeline et toute route non associée à un droit répondent toujours 403 à un jeton de capacité.

Requêtes signées

Chaque requête est signée avec une clé Ed25519. Le serveur connaît la clé publique de chaque pair :

{barrel_server, [{auth, #{
    accept  => [bearer, signed],
    signers => #{<<"node1">> => PubKey32},
    skew_ms => 300000}}]}

Le client signe avec la clé privée, définie dans l’app env pour que les configurations de tâches restent sans secrets :

{barrel_docdb, [{sync_signing, #{
    <<"https://edge-1.example.com:8443">> =>
        #{key_id => <<"node1">>, priv_key => Priv32}}}]}

Générez une paire avec crypto:generate_key(eddsa, ed25519).

Ce que couvre une signature v3 :

  • l’horodatage, l’id de clé, un nonce neuf, la méthode, le chemin avec sa query string brute, et le SHA-256 du corps ;
  • les en-têtes qui changent l’effet d’une écriture : content-type, if-match, if-none-match, x-barrel-actor, x-barrel-session, x-barrel-source, x-barrel-hlc, x-barrel-att-origin, x-barrel-digest et x-barrel-att-touch, chacun signé comme présent avec sa valeur ou comme absent.

Comment le serveur la vérifie :

  • Sur chaque route, pour chaque requête signée avec un corps, le corps est comparé au x-barrel-content-sha256 signé avant que le handler s’exécute. Un hachage absent ou faux répond 401 content_hash_mismatch.
  • Un nonce rejoué ou un horodatage hors de skew_ms est refusé.
  • Une requête qui présente une signature est jugée sur elle seule. Une signature en échec répond 401, même si un jeton bearer ou un certificat client aurait laissé passer la requête.
  • Les signatures v1 et v2 répliquent encore les documents, mais sont refusées avec 401 signature_v3_required quand elles écrivent une pièce jointe ou portent l’un des en-têtes ci-dessus. Les clients barrel_docdb 2.1.0 n’envoient que du v3 : mettez donc d’abord à jour les serveurs. Fermez l’ancienne fenêtre avec accept => [signed] et require_nonce => true.

Un proxy placé devant le serveur doit transmettre le chemin, la query string et les en-têtes signés sans les modifier.

Note

La signature authentifie le client et protège chaque requête. Elle ne masque ni la requête ni la réponse, et elle n’authentifie pas le serveur. Utilisez pour cela du HTTPS vérifié.

mTLS

{barrel_server, [
  {listeners, #{http => #{port => 8443, tls => true}}},
  {tls, #{certfile => "server.pem", keyfile => "server.key",
          cacertfile => "ca.pem", verify => verify_peer}},
  {auth, #{accept => [mtls]}}]}

Le client présente son certificat via sync_ssl :

{barrel_docdb, [{sync_ssl, #{
    <<"https://edge-1.example.com:8443">> =>
        [{certfile, "client.pem"}, {keyfile, "client.key"},
         {cacertfile, "ca.pem"}]}}]}
  • Un certificat ne compte que pour une requête sans en-tête Authorization. Si la requête porte un jeton ou une signature, c’est cet identifiant qui décide, et un identifiant en échec répond 401 même avec un bon certificat.
  • mTLS prouve que le certificat remonte à votre autorité de certification, pas quel client l’a envoyé : accept => [mtls] seul donne à chacun de ces clients l’accès à toutes les bases. Combinez-le, par exemple accept => [mtls, signed].
  • mtls est retiré de accept quand la configuration TLS n’a pas verify => verify_peer.
  • HTTP/3 sert du TLS mais ne filtre pas encore par certificat client. Ne comptez pas sur lui pour mTLS.

Une liste accept échoue en position fermée : une liste vide verrouille le serveur.

Identifiants pour la réplication

Le client de réplication lit trois clés de l’app env de barrel_docdb. Chacune associe une URL de base, ou une origine (scheme://host:port), à un identifiant ; l’URL complète est cherchée en premier.

CléValeur
sync_authun jeton bearer
sync_signing#{key_id, priv_key}
sync_sslune liste d’options ssl
{barrel_docdb, [{sync_auth, #{
    <<"http://edge-1.example.com:8080">> => <<"s3cret">>,
    <<"http://edge-2.example.com:8080/db/orders">> =>
        <<"other">>}}]}

Un barrel_rep:replicate/3 ponctuel peut aussi prendre auth, signing ou ssl_options dans la map du point d’accès. Les tâches de réplication les refusent : une configuration de tâche avec auth, signing, ssl_options, headers, ou un utilisateur et un mot de passe dans l’URL renvoie {error, {inline_credentials, Keys}}. Les tâches lisent leurs identifiants dans l’app env à chaque démarrage, pause et reprise. Quand les deux sont définis, la signature l’emporte sur un jeton bearer.

MCP

/mcp n’accepte que des jetons bearer : un jeton global (accès complet) ou un jeton de capacité (limité, outil par outil, à son espace et à ses droits). Il n’accepte ni les requêtes signées ni mTLS. Un appel d’outil refusé revient comme résultat d’outil avec isError: true. Voir Point d’accès MCP.

barrel-lite envoie un jeton bearer. Donnez-lui un jeton de capacité pour son espace, jamais le jeton global, et activez CORS. Voir Démarrage rapide : navigateur.

Traduit de la page anglaise: /docs/security/authentication/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir