98 lines
2.8 KiB
Plaintext
98 lines
2.8 KiB
Plaintext
<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&timestamp=' + timestamp + '&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>&algo=<var>algo</var>&timestamp=<var>ts</var>&orig=<var>orig</var>&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>
|