Remontée d'informations vers le portail citoyen

Frédéric Péters fpeters@entrouvert.com Benjamin Dauvergne bdauvergne@entrouvert.com Pierre Cros pcros@entrouvert.com Remontée d'informations de services vers le portail citoyen Remontée d'informations vers le portail citoyen

Introduction

Le portail citoyen est une plate-forme dans laquelle sont agrégées des informations provenant de sources web diverses.

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.

Structure de l'information fournie par les services

En réponse à la requête du portail citoyen, le service doit fournir une information structurée. Cette réponse peut prendre plusieurs formes.

Fils d'info

Le portail peut intégrer, sans que cela ne nécessite la moindre modification, les fils d'information au format RSS et Atom qui sont offerts par les services.

HTML

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.

JSON

La réponse du service à la requête du portail peut aussi être faite en JSON.

Liste

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 :

title : titre (obligatoire)

url : URL (obligatoire)

description : description (facultatif)

La liste des données doit être attachées à une clé nommée data.

Exemple :


{ "data": [
   {"title": "Demande de bac pour ordures",
    "url": "https://eservices.example.com/dechets/demande-bac"},
   {"title": "Demande d'acte de naissance",
    "url": "https://eservices.example.com/actes/naissance",
    "Description": "Faites vos démarches sans vous déplacer"}
  ]
}

Tableau

Le portail citoyen peut aussi recevoir des données qu'il affichera sous forme de tableau.

La liste des données doit être attachées à une clé nommée data et une clé nommée columns peut exister pour fournir les libellés des colonnes.

Exemple :


{"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"}
}

Le résultat sur le portail citoyen sera l'affichage du tableau suivant :

Jour	Horaire d'ouverture	Horaire de fermeture
Lundi	8h	17h
Mardi	8h	19h
Mercredi	9h	17h

Requête

Le portail effectue des requêtes HTTP GET vers les différents services. Les échanges atendus sont conformes au style d'architecture REST.

Protection des accès au service

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.

Authentification HTTP

Le portail citoyen peut utiliser l'authentification HTTP basique (définie dans la RFC 2617).

Authentification par certificat X.509

Le portail citoyen peut s'authentifier à l'aide d'un certificat client.

Authentification par secret partagé

L'URL peut être signée via 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.

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, un paramètre supplémentaire apikey.

En ce qui concerne l'algorithme de hash, il est préconisé d'utiliser SHA-256 par respect du Référentiel Général de Sécurité (RGS).

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


BASE64(HMAC-HASH(query_string+'algo=HASH&timestamp=' + timestamp + '&nonce=" + nonce, clé))

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

nonce est une chaîne aléatoire contenant au moins 128 bits d'entropie (16 octets aléatoires),

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.

La query string définitive est ainsi :


qs_initial&algo=algo&timestamp=ts&nonce=nonce&signature=signature

Pour la validation il faut contrôler :

que la signature regénérée est identique,

que le timestamp est dans une fenêtre étroite par rapport à la date courante, il est recommandé d'accepter un écart de trente secondes maximum.

que le nonce n'a encore jamais été vu (associé au timestamp il suffit de conserver les nonces pour une durée de 3 ou 4 fois la fenêtre de temps, par exemple cinq minutes).

Lors de l'utilisation de ces signatures il est important d'utiliser HTTPS pour éviter les interceptions et de stocker les nonces pour éviter les rejeux et à maintenir une bonne synchronisation des horloges, en utilisant par exemple le protocole NTP.

Identification de l'usager

L'URI utilisée pour ces requêtes peut contenir des informations identifiant l'usager concerné.

Identifiant SAML

Lorsque le service intègre le protocole de fédération d'identité SAML, la requête identifiante utilisera un identifiant SAML, le NameID :


https://www.example.com/eservices/pending?NameID=nameid

Adresse électronique

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 :


https://www.example.com/eservices/pending?email=email

Adresses électroniques identiques

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.