2013-04-05 18:11:20 +02:00
|
|
|
|
<page xmlns="http://projectmallard.org/1.0/"
|
|
|
|
|
type="guide" id="api-services" xml:lang="fr">
|
|
|
|
|
|
|
|
|
|
<info>
|
|
|
|
|
<link type="guide" xref="index#api" />
|
|
|
|
|
<revision docversion="0.1" date="2013-04-05" status="draft"/>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<revision docversion="0.3" date="2013-05-01" status="draft"/>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
<credit type="author">
|
|
|
|
|
<name>Frédéric Péters</name>
|
|
|
|
|
<email>fpeters@entrouvert.com</email>
|
|
|
|
|
</credit>
|
|
|
|
|
<credit type="author">
|
|
|
|
|
<name>Benjamin Dauvergne</name>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<email>bdauvergne@entrouvert.com</email>
|
|
|
|
|
</credit>
|
|
|
|
|
<credit type="author">
|
|
|
|
|
<name>Pierre Cros</name>
|
|
|
|
|
<email>pcros@entrouvert.com</email>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
</credit>
|
|
|
|
|
<desc>Remontée d'informations de services vers le portail citoyen</desc>
|
|
|
|
|
</info>
|
|
|
|
|
|
2013-04-21 18:30:25 +02:00
|
|
|
|
<title>Remontée d'informations vers le portail citoyen</title>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<section id="intro">
|
|
|
|
|
<title>Introduction</title>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<p>Le portail citoyen est une plate-forme dans laquelle sont agrégées des
|
|
|
|
|
informations provenant de sources web diverses.</p>
|
|
|
|
|
|
|
|
|
|
<p>Afin de permettre cette remontée d'information pour les services ne
|
|
|
|
|
disposant pas nativement d'une API exposée sur le Web, nous proposons
|
|
|
|
|
d'utiliser celle qui est décrite dans ce document.</p>
|
|
|
|
|
|
|
|
|
|
</section> <!-- #intro -->
|
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
|
|
|
|
<section id="structure">
|
|
|
|
|
<title>Structure de l'information fournie par les services</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>En réponse à la requête du portail citoyen, le service doit fournir une
|
|
|
|
|
information structurée. Cette réponse peut prendre plusieurs formes.</p>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
|
|
|
|
<section id="fils">
|
|
|
|
|
<title>Fils d'info</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>Le portail peut intégrer, sans que cela ne nécessite la moindre
|
|
|
|
|
modification, les fils d'information au format <link
|
2013-05-01 16:09:26 +02:00
|
|
|
|
href="http://en.wikipedia.org/wiki/RSS">RSS</link> et <link
|
2013-05-01 16:25:22 +02:00
|
|
|
|
href="http://en.wikipedia.org/wiki/Atom_(standard)">Atom</link> qui sont
|
|
|
|
|
offerts par les services.</p>
|
|
|
|
|
|
|
|
|
|
</section> <!-- #fils -->
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
|
|
|
|
<section id="html">
|
|
|
|
|
<title>HTML</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>Comme pour les fils d'infos, des blocs de code HTML fournis par les services
|
|
|
|
|
peuvent être intégrés directement dans le portail. À noter toutefois que ce
|
|
|
|
|
HTML doit être "brut" parce qu'il est filtré. Il ne peut pas contenir de
|
|
|
|
|
Javascript par exemple.</p>
|
|
|
|
|
|
|
|
|
|
</section> <!-- #html -->
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
|
|
|
|
<section id="json">
|
|
|
|
|
<title>JSON</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>La réponse du service à la requête du portail peut aussi être faite en
|
|
|
|
|
JSON.</p>
|
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<section id="liste">
|
|
|
|
|
<title>Liste</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>Les données exposées au format JSON doivent être organisées sous forme d'un
|
|
|
|
|
tableau associatif. Les clés (variables) de ce tableau sont les suivantes :</p>
|
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<list>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<item><p><code>title</code> : titre (obligatoire)</p></item>
|
|
|
|
|
<item><p><code>url</code> : URL (obligatoire)</p></item>
|
|
|
|
|
<item><p><code>description</code> : description (facultatif)</p></item>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</list>
|
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<p>La liste des données doit être attachées à une clé nommée <code>data</code>.
|
|
|
|
|
</p>
|
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<p>Exemple :</p>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
<code mime="application/json">
|
2013-05-01 16:25:22 +02:00
|
|
|
|
{ "data": [
|
2013-04-05 18:11:20 +02:00
|
|
|
|
{"title": "Demande de bac pour ordures",
|
|
|
|
|
"url": "https://eservices.example.com/dechets/demande-bac"},
|
|
|
|
|
{"title": "Demande d'acte de naissance",
|
2013-05-01 16:25:22 +02:00
|
|
|
|
"url": "https://eservices.example.com/actes/naissance",
|
|
|
|
|
"Description": "Faites vos démarches sans vous déplacer"}
|
2013-04-05 18:11:20 +02:00
|
|
|
|
]
|
2013-05-01 16:25:22 +02:00
|
|
|
|
}
|
2013-04-05 18:11:20 +02:00
|
|
|
|
</code>
|
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
</section> <!-- #liste -->
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<section id="tableau">
|
|
|
|
|
<title>Tableau</title>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>Le portail citoyen peut aussi recevoir des données qu'il affichera sous
|
2013-05-01 16:34:22 +02:00
|
|
|
|
forme de tableau.</p>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
|
|
|
|
|
<p>La liste des données doit être attachées à une clé nommée <code>data</code>
|
|
|
|
|
et une clé nommée <code>columns</code> peut exister pour fournir les libellés
|
|
|
|
|
des colonnes.
|
|
|
|
|
</p>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
|
|
|
|
<p>Exemple : </p>
|
|
|
|
|
|
|
|
|
|
<code mime="application/json">
|
2013-05-01 16:25:22 +02:00
|
|
|
|
{"data": [
|
|
|
|
|
{"day": "Lundi", "open": "8h", "close": "17h"},
|
|
|
|
|
{"day": "Mardi", "open": "8h", "close": "19h"},
|
|
|
|
|
{"day": "Mercredi", "open": "9h", "close": "17h"}
|
|
|
|
|
],
|
|
|
|
|
"columns": {
|
|
|
|
|
"day": "Jour",
|
|
|
|
|
"open": "Horaire d'ouverture",
|
|
|
|
|
"close": "Horaire de fermeture"}
|
|
|
|
|
}
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</code>
|
|
|
|
|
|
|
|
|
|
<p>Le résultat sur le portail citoyen sera l'affichage du tableau suivant :</p>
|
|
|
|
|
|
|
|
|
|
<table frame="none" rules="none" shade="rows">
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<td><p>Jour</p></td>
|
|
|
|
|
<td><p>Horaire d'ouverture</p></td>
|
|
|
|
|
<td><p>Horaire de fermeture</p></td>
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<tr>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<td><p>Lundi</p></td><td><p>8h</p></td><td><p>17h</p></td>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<td><p>Mardi</p></td><td><p>8h</p></td><td><p>19h</p></td>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
<td><p>Mercredi</p></td><td><p>9h</p></td><td><p>17h</p></td>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</tr>
|
2013-05-01 16:25:22 +02:00
|
|
|
|
</tbody>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
</table>
|
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
</section> <!-- #tableau -->
|
2013-05-01 16:09:26 +02:00
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
</section> <!-- #json -->
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2013-05-01 16:25:22 +02:00
|
|
|
|
</section> <!-- #structure -->
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2015-10-19 10:08:31 +02:00
|
|
|
|
|
|
|
|
|
<section id="requete">
|
|
|
|
|
<title>Requête</title>
|
|
|
|
|
|
|
|
|
|
<p>Le portail effectue des requêtes HTTP GET vers les différents services. Les
|
|
|
|
|
échanges atendus sont conformes au style d'architecture REST.</p>
|
|
|
|
|
|
|
|
|
|
<section id="req-security">
|
|
|
|
|
<title>Protection des accès au service</title>
|
|
|
|
|
|
|
|
|
|
<p>L'accès au service peut être protégé de différentes manières, le portail
|
|
|
|
|
citoyen peut utiliser les mécanismes suivants pour s'authentifier auprès du
|
|
|
|
|
service.</p>
|
|
|
|
|
|
|
|
|
|
<section id="req-security-http-auth">
|
|
|
|
|
<title>Authentification HTTP</title>
|
|
|
|
|
|
|
|
|
|
<p>Le portail citoyen peut utiliser l'authentification HTTP basique (définie
|
|
|
|
|
dans la RFC 2617).</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="req-security-client-cert">
|
|
|
|
|
<title>Authentification par certificat X.509</title>
|
|
|
|
|
|
|
|
|
|
<p>Le portail citoyen peut s'authentifier à l'aide d'un certificat client.</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<!--
|
|
|
|
|
<section id="req-security-oauth2">
|
|
|
|
|
</section>
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
<section id="req-security-shared-secret">
|
|
|
|
|
<title>Authentification par secret partagé</title>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
<p>
|
2015-10-19 10:08:31 +02:00
|
|
|
|
L'URL peut être signée via une clé partagée à configurer des deux cotés de la
|
2013-04-05 18:11:20 +02:00
|
|
|
|
liaison, la signature est du type HMAC; l'algorithme de hash à employer est
|
|
|
|
|
passé en paramètre.
|
|
|
|
|
</p>
|
|
|
|
|
|
2013-04-08 17:42:48 +02:00
|
|
|
|
<note><p>Si le service doit être utilisé par différents requêteurs il est
|
|
|
|
|
recommandé de ne pas utiliser une clé unique; il est ainsi suggéré que l'URL
|
|
|
|
|
attende également un paramètre précisant l'appelant, à travers, par exemple,
|
2013-05-01 16:09:26 +02:00
|
|
|
|
un paramètre supplémentaire <code>apikey</code>.
|
2013-04-08 17:42:48 +02:00
|
|
|
|
</p></note>
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
La signature est à calculer sur la query string encodée complète, en
|
2013-04-05 18:11:20 +02:00
|
|
|
|
enlevant les paramètres terminaux <code>algo</code>, <code>timestamp</code>,
|
|
|
|
|
<code>nonce</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 + '&nonce=" + nonce, clé))
|
|
|
|
|
</code>
|
|
|
|
|
|
|
|
|
|
<list>
|
|
|
|
|
|
|
|
|
|
<item><p><code>timestamp</code> est la date dans la zone GMT au format ISO8601
|
2013-05-01 16:25:22 +02:00
|
|
|
|
en se limitant à la précision des secondes (ex : 2012-04-04T12:34:00Z),
|
|
|
|
|
</p></item>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
<item><p>nonce est une chaîne aléatoire contenant au moins 128 bits d'entropie
|
|
|
|
|
(16 octets aléatoires),</p></item>
|
|
|
|
|
|
2013-04-08 17:42:48 +02:00
|
|
|
|
<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.
|
2013-04-05 18:11:20 +02:00
|
|
|
|
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>&nonce=<var>nonce</var>&signature=<var>signature</var>
|
|
|
|
|
</code>
|
|
|
|
|
|
|
|
|
|
<p>
|
2013-05-01 16:09:26 +02:00
|
|
|
|
Pour la validation il faut contrôler :
|
2013-04-05 18:11:20 +02:00
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<list>
|
|
|
|
|
|
|
|
|
|
<item><p>que la signature regénérée est identique,</p></item>
|
|
|
|
|
|
|
|
|
|
<item><p>que le timestamp est dans une fenêtre étroite par rapport à la date
|
|
|
|
|
courante, il est recommandé d'accepter un écart de trente secondes
|
2013-04-21 18:40:12 +02:00
|
|
|
|
maximum.</p></item>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
2013-05-01 16:09:26 +02:00
|
|
|
|
<item><p>que le nonce n'a encore jamais été vu (associé au timestamp il suffit
|
2013-05-01 16:25:22 +02:00
|
|
|
|
de conserver les nonces pour une durée de 3 ou 4 fois la fenêtre de temps, par
|
|
|
|
|
exemple cinq minutes).</p></item>
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
</list>
|
|
|
|
|
|
|
|
|
|
<note><p>
|
2013-04-08 17:42:48 +02:00
|
|
|
|
Lors de l'utilisation de ces signatures il est important d'utiliser HTTPS pour
|
2013-10-31 10:08:07 +01:00
|
|
|
|
éviter les interceptions et de stocker les nonces pour éviter les rejeux et à
|
2013-04-05 18:11:20 +02:00
|
|
|
|
maintenir une bonne synchronisation des horloges, en utilisant par exemple le
|
|
|
|
|
protocole NTP.
|
|
|
|
|
</p></note>
|
|
|
|
|
|
2015-10-19 10:08:31 +02:00
|
|
|
|
</section> <!-- req-security-shared-secret -->
|
|
|
|
|
</section> <!-- req-security -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section id="req-ident">
|
|
|
|
|
<title>Identification de l'usager</title>
|
|
|
|
|
|
|
|
|
|
<p>L'URI utilisée pour ces requêtes peut contenir des informations identifiant
|
|
|
|
|
l'usager concerné.</p>
|
|
|
|
|
|
|
|
|
|
<section id="saml">
|
|
|
|
|
<title>Identifiant SAML</title>
|
|
|
|
|
|
|
|
|
|
<p>Lorsque le service intègre le protocole de fédération d'identité SAML, la
|
|
|
|
|
requête identifiante utilisera un identifiant SAML, le NameID :</p>
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
https://www.example.com/eservices/pending?NameID=<var>nameid</var>
|
|
|
|
|
</code>
|
|
|
|
|
</section> <!-- #saml -->
|
|
|
|
|
|
|
|
|
|
<section id="adel">
|
|
|
|
|
<title>Adresse électronique</title>
|
|
|
|
|
|
|
|
|
|
<p>Lorsque le service n'intègre pas le protocole de fédération d'identité SAML,
|
|
|
|
|
la requête identifiante utilisera l'adresse électronique de l'utilisateur :</p>
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
https://www.example.com/eservices/pending?email=<var>email</var>
|
|
|
|
|
</code>
|
|
|
|
|
|
|
|
|
|
<note>
|
|
|
|
|
<title>Adresses électroniques identiques</title>
|
|
|
|
|
<p>L'utilisation de cette méthode pour identifier l'utilisateur ne fonctionne
|
|
|
|
|
que si ce dernier a employé la même adresse électronique pour la création du
|
|
|
|
|
compte citoyen et la création du compte sur le service.</p>
|
|
|
|
|
</note>
|
|
|
|
|
</section> <!-- #adel -->
|
|
|
|
|
</section> <!-- #req-ident -->
|
|
|
|
|
|
|
|
|
|
</section> <!-- #requete -->
|
2013-04-05 18:11:20 +02:00
|
|
|
|
|
|
|
|
|
</page>
|