<page xmlns="http://projectmallard.org/1.0/"
      type="topic" id="api-auth" xml:lang="fr">

<info>
  <link type="guide" xref="index#api" />
  <revision docversion="0.1" date="2013-01-04" status="draft"/>
  <revision docversion="0.2" date="2015-12-18" status="draft"/>
  <credit type="author">
    <name>Frédéric Péters</name>
    <email>fpeters@entrouvert.com</email>
  </credit>
  <desc>Clé d'utilisation, utilisateurs, sessions, signatures, etc.</desc>

</info>

<title>Authentification</title>

<section>
<title>Usager concerné</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).
</p>

</section>

<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 à
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>

<note><p>En ce qui concerne l'algorithme de hash, il est préconisé d'utiliser
SHA-256 par respect du <link
href="http://references.modernisation.gouv.fr/rgs-securite">Référentiel Général
de Sécurité (RGS)</link>.</p></note>

<p>
La signature est à calculer sur la query string encodée complète, en
enlevant les paramètres terminaux <code>algo</code>, <code>timestamp</code>,
<code>orig</code> et <code>signature</code>. La formule de calcul de la
signature est la suivante :
</p>

<code>
BASE64(HMAC-HASH(query_string+'algo=HASH&amp;timestamp=' + timestamp + '&amp;orig=" + orig, clé))
</code>

<list>

<item><p><code>timestamp</code> est la date dans la zone GMT au format ISO8601
en se limitant à la précision des secondes (ex : 2012-04-04T12:34:00Z),
</p></item>

<item><p><code>orig</code> est une chaîne de précisant l'émetteur de la
requête,</p></item>

<item><p>algo est une chaîne représentant l'algorithme de hachage utilisé, sont
définis : sha1, sha256, sha512 pour les trois algorithmes correspondant.
L'utilisation d'une valeur différente n'est pas définie.</p></item>

</list>

<p>
La query string définitive est ainsi :
</p>

<code>
<var>qs_initial</var>&amp;algo=<var>algo</var>&amp;timestamp=<var>ts</var>&amp;orig=<var>orig</var>&amp;signature=<var>signature</var>
</code>

</section>

<section>
<title>Configuration des clés partagées</title>

<p>
Les clés partagées doivent être définies dans le fichier
<code>site-options.cfg</code>, dans une section <code>[api-secrets]</code>, par
exemple :
</p>

<code>
[api-secrets]
intranet = 12345
</code>

</section>

</page>
