help: explain API access management (#55079)

help/fr/api-auth.page

@@ -9,30 +9,104 @@
     <name>Frédéric Péters</name>
     <email>fpeters@entrouvert.com</email>
   </credit>
-  <desc>Clé d’utilisation, utilisateurs, sessions, signatures, etc.</desc>
+  <desc>Accès aux API, identifiants et clé d’utilisation, utilisateurs, signature, etc.</desc>
 
 </info>
 
 <title>Authentification</title>
 
 <section>
-<title>Usager concerné</title>
+<title>Gestion des accès aux API</title>
 
 <p>
-Pour les appels concernant un usager particulier (tel que la récupération de la
-liste de ses formulaires en cours), l’usager est précisé en ajoutant une query
-string avec un paramètre <code>email</code> (pour trouver l’usager selon son
-adresse électronique) ou un paramètre <code>NameID</code> (pour trouver
-l’usager selon son NameID SAML).
+La création d’accès aux API se fait dans l’espace de paramétrage, dans la
+section « Sécurité », en suivant le lien « Accès aux API ». Le bouton « Nouvel
+accès aux API » permet d’ajouter un accès, et il faut indiquer :
+</p>
+
+<list>
+
+<item><p>Nom : le nom choisi pour l’accès, qui sera affiché dans la page des
+accès ;</p></item>
+
+<item><p>Description : pour se rappeler de l’usage prévu pour cet
+accès ;</p></item>
+
+<item><p>Identifiant d’accès : le nom de l’utilisateur à utiliser pour
+l’authentification HTTP Basic, ou le paramètre <code>orig</code> pour
+l’authentification par signature ;</p></item>
+
+<item><p>Clé d’accès : le mot de passe pour l’authentification HTTP Basic de
+cet utilisateur, ou la clé partagée à utiliser pour l’authentification par
+signature ;</p></item>
+
+<item><p>Rôles : liste des rôles automatiquement obtenus lorsque cet accès est
+utilisé. Par exemple, s’il s’agit de permettre de lister des demandes d’une
+certaine démarche, il faut indiquer un rôle qui permet de voir les demandes.
+Ce rôle est à déterminer selon le paramétrage du formulaire de la démarche
+et/ou de son workflow.</p></item>
+
+</list>
+
+<note><p>Il est conseillé de créer des «rôles techniques» dédiés aux API. Ces
+rôles ne sont jamais donnés à des utilisateurs de la plateforme, ils sont
+utilisés uniquement dans le paramétrage des accès. Typiquement une démarche est
+paramétrée pour qu’un certain rôle technique ait accès à ses demandes, et ce
+même rôle est indiqué dans l’accès aux API dédié.</p></note>
+
+<section>
+<title>Définitions de l’usager concerné</title>
+
+<p>
+Si l’authentification utilisée passe par un accès aux API qui ne donne pas de
+rôle spécifique, alors il faut indiquer dans la query-string un usager qui aura
+les rôles nécessaires.
+</p>
+
+<p>
+C'est aussi nécessaire pour les appels concernant un usager particulier, tel
+que la récupération de la liste de ses formulaires en cours.
+</p>
+
+<p>L’usager est précisé en ajoutant dans la query string :</p>
+
+<list>
+<item><p>soit un paramètre <code>email</code> pour trouver l’usager selon son
+adresse électronique</p></item>
+<item><p>soit un paramètre <code>NameID</code> pour trouver l’usager selon son
+NameID SAML.</p></item>
+</list>
+
+</section>
+</section>
+
+<section>
+<title>Authentification simple HTTP Basic</title>
+
+<p>
+Pour accéder aux API avec l’authentification HTTP Basic classique, il faut
+utiliser le nom d’utilisateur (identifiant d’accès) et le mot de passe (clé
+d’accès) de l’accès configuré ci-dessus.
 </p>
 
 </section>
 
+
+<section>
+<title>Authentification par signature de l’URL</title>
+
+<p>
+Un système d’authentification basé sur une signature ajoutée à la fin de l’URL
+est également disponible. Il peut être jugé plus sécurisé que
+l’authentification HTTP Basic, par ailleurs il assure une protection plus
+explicite contre le rejeu. Ce système est spécifique à Publik/w.c.s.
+</p>
+
 <section id="req-security-shared-secret">
 <title>Signature des requêtes</title>
 
 <p>
-Les appels aux API doivent être signés, cela passe par une clé partagée à
+La signature d’un appel aux API passe par une clé partagée à
 configurer des deux cotés de la liaison, la signature est du type HMAC;
 l’algorithme de hash à employer est passé en paramètre.
 </p>
@@ -87,7 +161,14 @@ La query string définitive est ainsi :
 <title>Configuration des clés partagées</title>
 
 <p>
-Les clés partagées doivent être définies dans le fichier
+La définition des clés se fait lors de la création des accès aux API (voir
+plus haut). Lors de la création d'un nouvel accès, l’identifiant d'accès
+correspond au «orig» et la clé d'accès est la clé de signature. Les rôles sont
+ceux qui seront obtenus lors de l’usage de l’accès.
+</p>
+
+<p>
+Les clés partagées peuvent aussi être définies dans le fichier
 <code>site-options.cfg</code>, dans une section <code>[api-secrets]</code>, par
 exemple :
 </p>
@@ -100,7 +181,7 @@ intranet = 12345
 </section>
 
 <section>
-<title>Exemples de code de signature</title>
+<title>Exemples d'implémentation de l’algorithme de signature</title>
 
 <p>
 Voici des exemples de code pour créer des URLs signées selon l’algorithme
@@ -230,6 +311,7 @@ echo "$signed"
 </code>
 </listing>
 
+</section>
 </section>
 
 </page>