Techniques et code du serveur OAuthSD

Remarque : Il existe également une API HTTP REST + TreeQL.

L’API répond à une unique action « http.api » qui va gérer trois paramètres :

- un format : c’est le nom de l’API réellement implémentée : json, collectionjson.
- un type (ou une collection) : le type des données qu’on veut utiliser : auteurs, users, clients ...
- une ressource : l’identifiant unique d’un contenu (un nombre entier).

Ces trois paramètres sont tout simplement ajoutés à la suite dans l’URL, séparés par des « / ». Seul le premier est toujours obligatoire, les autres sont ajoutés suivant ce que l’on veut manipuler. On se retrouve alors avec trois familles d’Url de requêtes.

Exemple de requête d’action :

La deuxième forme peut également être complétée par des paramètres d’URL. Exemple :

Exemple de requête avec paramètres :

L’API permet d’effectuer les opérations CRUD [1] sur une table de la base de données en fonction de la méthode de la requête HTTP GET, POST, PUT ou DELETE, si toutefois les permissions sont accordées.

L’API s’efforce de répondre à la spécification de sémantique HTTP 1.1.

Types

Pour s’interfacer avec une application de supervision, OAuth SD expose les types :
 oidc_logs,
 users,
 clients
 auteurs.
D’une façon générale, les types correspondent aux tables éponymes.
Sauf exception (voir la constante de configuration API_HTTP_CHAMPS_SENSIBLES), tous les champs d’une table peuvent être manipulés.

Formats

Dans le cadre d’OAuthSD, les objets sont manipulés aux formats suivants :

collectionjson
Ce format est assez lourd, retournant les données sous forme d’arrays associatifs et d’objets, ce qui permet de nombreuses applications. Voir : Collection+JSON.

Exemple : la requête :

retourne :

Format json
Retourne un simple array. Exemple : la requête :

retourne les mêmes éléments sous une forme très compacte :

Le format collectionjson est intéressant en lecture. En écriture, on préférera le format json qui suffit à décrire les objets à enregistrer.

Actions

Suivant le paradigme HTTP Rest, les actions découlent de la méthode HTTP utilisée pour appeler l’API : get, post, put ou delete.

Formes générales des requêtes GET

 Afficher la liste des collections disponibles sous le format indiqué :

 Liste le contenu de la collection "type" :

 Liste les éléments sélectionnés à l’aide des paramètres d’URL indiqués :

 Accès à une ressource précise :

NN est la valeur de l’identifiant (champ id_type, clé unique) de l’enregistrement dans la table.

Requêtes avec POST, PUT et DELETE

Ces requêtes doivent être générées programmatiquement : par exemple avec cURL côté serveur ou en Javascript côté client. On trouve couramment des bibliothèque exposant des fonctions de ce type :

 post_collection($requete, $reponse)
Créer une nouvelle ressource dans la collection (créer un nouvel enregistrement dans la table).

 put_ressource($requete, $reponse)
Ce cas est sensiblement le même que le précédent, à ceci près que l’on travaille sur la modification d’une ressource précise.

 delete_ressource($requete, $reponse)
Supprimer définitivement une ressource.

Pour la transmission des données aux requêtes avec POST et PUT, deux formats sont possibles :
 application/json :

 application/x-www-form-urlencoded :

Actions possibles

Toutes les combinaisons format/type/action ne sont pas disponibles.

En premier lieu, l’accès à l’API est subordonné à l’authentification de l’application cliente et de l’utilisateur final par OAuthSD.

Ensuite, toutes les combinaisons type/action ne sont pas autorisées. Des droits sont définis pour chaque action en fonction du profil de l’auteur (administrateur d’applications) authentifié.

Enfin, certaines actions ne sont pas (ou pas encore) implémentées.

Protection des données

Les données très sensibles (conditionnant la sécurité de l’authentification) sont protégées, elles ne peuvent être vues ni a fortiori modifiées à l’aide de l’API.

Dans l’état actuel, les champs suivants, définis par la constante API_HTTP_CHAMPS_SENSIBLES, ne sont pas transmis : client_secret, client_ip, password’.

clients (Applications clientes)

Requêtes GET

Le type clients permet de nombreuses requêtes GET avec les formats collectionjson et json, notamment avec les paramètres offset et length. La requête suivante est pratique pour générer des tableaux paginés :

Pour assurer la sécurité de l’authentification :
 les donnée sensibles "client_secret" et "client_ip" ne seront pas retournées,
 les paires de clés publiques/privées associées ne peuvent être atteintes,

Edition : requêtes POST, PUT, DELETE

Exemple d’écriture d’un nouvel enregistrement en PHP avec cURL. Les données sont transmises au format application/x-www-form-urlencoded [2] :

En HTML cela équivaudrait à :

En cas de succès, la table clients est mise à jour et l’API retourne dans le corps de la réponse un array Json avec le client_id et l’id_client (index unique de la table clients) :

En cas de duplication, la réponse suivante est retournée :

users (Utilisateurs finaux)

Le type users permet de nombreuses requêtes GET avec les formats collectionjson et json, notamment avec les paramètres offset et length. La requête suivante est pratique pour générer des tableaux paginés :

Notez que la donnée sensible "password" ne sera pas retournée.

Enregistrement d’un utilisateur final sur le serveur OIDC

Le type users permet l’écriture (requêtes POST, PUT et DELETE).

Pour fonctionner, le contrôleur Authorize du serveur serveur OIDC n’a besoin que d’un username (ou d’un e-mail) et d’un mot de passe. Le contrôleur exploite également le contenu des autres champs fournis s’ils existent dans la table users et ne sont pas nuls.
En particulier, le champ scope peut être utilisé pour transmettre des autorisations propres à l’utilisateur.

Pour assurer la sécurité de l’authentification :
 lors de l’écriture, le secret client transmis en clair est enregistré sous forme de password_hash avec l’algorithme PASSWORD_BCRYPT.

auteurs (Administrateurs d’applications ou "superviseurs")

oidc_logs (événements)

Le type oidc_logs n’autorise que les requêtes suivantes, sous les formats json et collectionjson :

 Les événements étant triés par date décroissante, retourne length evenements depuis le rang 0 (donc les derniers événements) :

 Les événements étant triés par date décroissante, retourne length evenements depuis le rang offset :

 Les événements étant triés par date décroissante, retourne length événements autour du plus proche du temps indiqué par le timeserial ts :

 Retourne les évènements entre les timeserials tmin et tmax :

Notes :
 Il est interdit de lister l’ensemble de la collection.
 length est limité à 10000, sans génération d’erreur.

Sécurisation de l’accès à l’API

Deux configurations sont envisagées :
 Le serveur qui porte l’API est accessible uniquement par des applications de confiance à travers un canal sûr (par exemple au sein d’un réseau local d’entreprise bien isolé). Dans ce cas, la constante API_HTTP_AUTHENTICATE est fixée à ’false’ et des vérifications simples sont effectuées sur l’IP et/ou le domaine du client origine de la requête. Les constantes API_HTTP_CLIENT_IP et API_HTTP_CLIENT_HOST définissent les valeurs attendues.
 Le serveur se trouve sur un réseau public. Dans ce cas, la constante API_HTTP_AUTHENTICATE est fixée à ’true’ et l’application cliente doit s’authentifier avec le protocole OAuth 2.0. Pour ce faire, l’application cliente devra être enregistrée sur ce ce serveur OAuthSD avec les flux Authorization Code et Client Credentials. Notez que les contraintes définies par les constantes API_HTTP_CLIENT_IP et API_HTTP_CLIENT_HOST s’appliquent également.

Lorsqu’une application cliente veut accéder à l’API au nom d’un utilisateur final :
 l’application authentifie son utilisateur final avec le flux Authorization Code,
 si l’utilisateur final est authentifié, et seulement dans ce cas, l’application demande une autorisation d’accès en son nom propre avec le flux Client Credentials, puis passe le jeton d’accès obtenu dans l’appel à l’API,
 l’API vérifie le jeton d’accès par introspection.

En fait, l’API peut aussi bien valider un jeton d’accès qu’un jeton d’identification. L’application cliente peut donc s’authentifier directement avec le jeton d’identité obtenu avec le flux Authorization Code.

Lorsqu’une application cliente veut accéder à l’API en son nom propre :
 l’application demande une autorisation d’accès avec le flux Client Credentials, puis passe le jeton d’accès obtenu dans l’appel à l’API,
 l’API vérifie le jeton d’accès par introspection.

Le jeton peut être passé à l’API sous le nom ’token’ par les méthode POST ou GET, mais il est recommandé d’utiliser la méthode Auth Bearer.

Options

Les options suivantes sont définies dans le fichier collectionjsonoauthsd_options.php :

/* Cette API permet l’accès à la plupart des données manipulées par SPIP, les
types correspondant aux tables éponymes de la base de données. Cependant, autant
pour des raisons pratiques que de sécurité, les types servis sont limités à ceux
qui seront définis ici.
Si la chaine est ’’, tous les types seront autorisés.
Attention : le type est au singulier !*/
define(’API_HTTP_TYPES_AUTORISES’,’oidc_log,user,client,auteur,credential’) ;

/* S’agissant d’un serveur d’authentification, certaines données sont particulièrement
sensibles et doivent rester sanctuarisées.*/
define(’API_HTTP_CHAMPS_SENSIBLES’,’client_secret,client_ip,password’) ;

/* Si l’API doit être accessible autrement que par un client de confiance par
un canal sûr, il faut authentifier l’origine de la requête.
Cette constante peut aussi être fixée à false pendant le développement */
define(’API_HTTP_AUTHENTICATE’, false) ;

/* Si API_HTTP_AUTHENTICATE est fixé à true, l’authentification du client requiert
un jeton d’identité valide. Celui-ci contient la déclaration sub égale à l’id du
client (client_id). Si la constante suivante est non nulle, sub devra être égal à
la valeur indiquée. */
define(’API_HTTP_CLIENT_ID’, ’’) ;

/* Si API_HTTP_AUTHENTICATE a été fixé à false, il convient d’appliquer tout ou
partie des vérifications suivantes : */
define(’API_HTTP_CLIENT_IP’, ’’) ; // Vérifier que la requête vient de l’IP indiquée si non nulle
define(’API_HTTP_CLIENT_HOST’, ’’) ; // Vérifier que la requête vient du host indiqué si non nul

/* Si la requête ne définit pas le paramètre limit, les requêtes acceptant le
paramètre limit utiliseront la valeur suivante par défaut :*/
define (’API_DEFAULT_LENGTH’, 100) ;

/* Nombre maximum de lignes que peut retourner une requête (dans le cas où le paramètre
limit n’est pas requis, comme quand la requête n’accepte que les paramètres tmin et/ou tmax) :*/
define (’API_MAX_ITEMS_RETURNED’, 1000) ;

Utilisation de l’API par OAuthSD lui-même

OAuthSD utilise l’API notamment pour :
 La présentation des événements : charger les données de la table oidc_logs avec Ajax pour les présenter en scrolling continu. Voir le tableau de la page Statistiques.
 Permettre la supervision du serveur par une application extérieure.

Remarque : Cette API pourrait remplacer l’API HTTP REST à moyen terme.

Sécurisation de l’accès à l’API et transmission du rôle de l’utilisateur final

La sécurisation de l’accès à l’API HTTP REST + TreeQL est effectué à l’aide d’un jeton d’identité au format JWT émis par l’application cliente.

Ce jeton transmet le rôle de l’utilisateur au moyen de la déclaration ’scope’ prenant l’une des valeurs ’admin’, ’writer’, ’reader’ and ’none’. Pour cela (voir Définition des scopes OIDC et généralités sur leur utilisation par les applications) :
 l’application cliente doit utiliser OIDC et initialiser le flux d’autorisation avec code avec la demande d’autorisation (requested_scope) ’scope=privileges’,
 L’application cliente doit avoir été enregistrée avec la valeur ’privileges’ dans la liste de Scopes disponibles (Available scopes),
 une valeur parmi ’admin’, ’writer’, ’reader’ and ’none’ doit avoir été enregistrée dans la table users pour l’utilisateur final considéré.

Le jeton peut être passé dans l’URL (méthode GET), par POST ou par la méthode Authorization : Bearer.

Exemple d’appel avec la méthode GET :

L’API valide le jeton JWT par introspection. OAuthSD garantit ainsi l’authenticité de l’application cliente. Voir : Vérification de l’origine de la requête reçue par un serveur de ressource.

En cas d’erreur d’authentification, l’API retourne un code HTTP 403 Forbidden et un corps vide.

Limitation de l’accès aux tables et aux champs

 seules les tables ’users’, ’clients’, ’scopes’, ’oidc_logs’ sont accessibles.

L’authentification de l’utilisateur final conduit à définir les rôles ’admin’, ’writer’, ’reader’ et ’none’. Le rôle ’admin’ peut effectuer l’ensemble des opérations.

Pour le rôle "writer" :
 dans la table ’public_keys’, la seule opération permise est la lecture de la clé clé publique.
 dans la table ’oauth_clients’, l’accès au champ password est interdit.
 dans la table ’oauth_users’, l’accès au champ client_secret est interdit.

Pour le rôle ’reader’ :
 les restriction d’accès sont les mêmes que le rôle ’writer’,
 seules les opérations ’read’ et ’list’ sont autorisées.

Le rôle ’none’ ne peut que lire la table ’oidc_logs’.

Opérations CRUD + List : Référence de l’API

Voyez également :
 https://oa.dnc.global/http.api/spec/swagger/static/
 https://editor.swagger.io/?url=https://oa.dnc.global/http.api/api.php/openapi

Sélections avancées

Sur les opérations de liste, vous pouvez appliquer des filtres et des jointures.

Les exemples suivants supposent la table suivante :

Filtres

Les filtres fournissent une fonctionnalité de recherche sur les appels de liste, en utilisant le paramètre "filter". Vous devez spécifier le nom de la colonne, une virgule, le type de correspondance, une autre virgule et la valeur que vous souhaitez filtrer.

Types de match supportés :

"cs" : contient une chaîne (la chaîne contient une valeur)
"sw" : commence par (chaîne commence par valeur)
"ew" : se termine par (chaîne se termine par valeur)
"eq" : égal (la chaîne ou le nombre correspond exactement)
"lt" : inférieur à (nombre inférieur à la valeur)
"le" : inférieur ou égal (le nombre est inférieur ou égal à la valeur)
"ge" : supérieur ou égal (le nombre est supérieur ou égal à la valeur)
"gt" : supérieur à (nombre supérieur à la valeur)
"bt" : entre (le nombre est entre deux valeurs séparées par une virgule)
"in" : in (le nombre ou la chaîne est dans une liste de valeurs séparées par des virgules)
"is" : est null (le champ contient la valeur "NULL")

Vous pouvez annuler tous les filtres en ajoutant un caractère "n", afin que "eq" devienne "neq". Exemples d’utilisation du filtre :

Filtres multiples

Les filtres peuvent être appliqués en répétant le paramètre "filter" dans l’URL. Par exemple l’URL suivante :

GET / records / categories ? Filter = id, gt, 1 & filter = id, lt, 3

demandera toutes les catégories "où id> 1 et id <3". Si vous vouliez "où id = 2 ou id = 4", vous devriez écrire :

GET / enregistrements / catégories ? Filter1 = id, eq, 2 & filter2 = id, eq, 4

Comme vous le voyez, nous avons ajouté un numéro au paramètre "filter" pour indiquer que "OR" au lieu de "AND" doit être appliqué. Notez que vous pouvez également répéter "filter1" et créer un "ET" dans un "OU". Comme vous pouvez également aller plus loin en ajoutant une lettre (a-f), vous pouvez créer presque n’importe quel arbre de conditions relativement complexe.

Notes :
 Vous ne pouvez filtrer que sur la table demandée (pas sur la table incluse) et les filtres ne sont appliqués qu’aux appels de liste.

Sélection de colonne

Par défaut, toutes les colonnes sont sélectionnées. Avec le paramètre "include", vous pouvez sélectionner des colonnes spécifiques. Vous pouvez utiliser un point pour séparer le nom de la table du nom de la colonne. Plusieurs colonnes doivent être séparées par des virgules. Un astérisque ("*") peut être utilisé comme caractère générique pour indiquer "toutes les colonnes". Semblable à "include", vous pouvez utiliser le paramètre "exclude" pour supprimer certaines colonnes :

GET / enregistrements / catégories / 1 ? Include = nom
GET /records/categories/1 ?include=categories.name
GET /records/categories/1 ?exclude=categories.id

Sortie :

Notes :
 Les colonnes utilisées pour inclure des entités associées sont automatiquement ajoutées et ne peuvent pas être omises de la sortie.

Tri

Avec le paramètre "order", vous pouvez trier. Par défaut, le tri s’effectue par ordre croissant, mais en spécifiant "desc", cela peut être inversé :

GET / records / categories ? Order = nom, desc

GET / enregistrements / catégories ? Order = id, desc & order = name

Sortie :

Notes :
 Vous pouvez trier sur plusieurs champs en utilisant plusieurs paramètres "ordre". Vous ne pouvez pas commander sur des colonnes "jointes".

Taille limite

Le paramètre "size" limite le nombre d’enregistrements renvoyés. Ceci peut être utilisé pour les N premières listes avec le paramètre "order" (utilisez l’ordre décroissant).

GET / records / categories ? Order = id, desc & size = 1

Sortie :

Notes :
 Si vous souhaitez également connaître le nombre total d’enregistrements, vous pouvez utiliser le paramètre "page".

Pagination

Le paramètre "page" contient la page demandée. La taille de page par défaut est 20, mais peut être ajustée (par exemple à 50).

GET / records / categories ? Order = id & page = 1

GET / records / categories ? Order = id & page = 1,50

Sortie :

Notes :
 les pages non commandées ne pouvant pas être paginées, elles seront classées par clé primaire.

Jointures

Supposons que vous ayez une table des publications qui comporte des commentaires (formulés par les utilisateurs) et que les publications puissent avoir des balises. Les exemples suivants supposent le jeu de tables suivant :

Lorsque vous souhaitez répertorier les publications avec leurs commentaires, les utilisateurs et les balises, vous pouvez demander deux chemins "arborescents" :

messages -> commentaires -> utilisateurs
posts -> post_tags -> tags
Ces chemins ont la même racine et cette demande peut être écrite au format URL comme suit :

GET / records / posts ? Join = commentaires, utilisateurs & tags = join

Ici, vous êtes autorisé à laisser de côté la table intermédiaire qui lie les publications aux balises. Dans cet exemple, les trois types de relation de table (hasMany, belongsTo et hasAndBelongsToMany) sont en jeu :

"post" a beaucoup de "commentaires"
"commentaire" appartient à "utilisateur"
"post" a et appartient à beaucoup de "tags"

Cela peut entraîner les données JSON suivantes :

Vous voyez que les relations "belongsTo" sont détectées et la valeur de la clé étrangère est remplacée par l’objet référencé. Dans le cas de "hasMany" et "hasAndBelongsToMany", le nom de la table est utilisé comme nouvelle propriété de l’objet.

Opérations par lots

Lorsque vous souhaitez créer, lire, mettre à jour ou supprimer, vous pouvez spécifier plusieurs valeurs de clé primaire dans l’URL. Vous devez également envoyer un tableau au lieu d’un objet dans le corps de la demande pour créer et mettre à jour.

Pour lire un enregistrement de cette table, la demande peut être écrite au format URL sous la forme suivante :

GET / records / posts / 1,2

Le résultat peut être :

De même, lorsque vous souhaitez effectuer une mise à jour par lot, la demande au format URL est écrite comme suit :

PUT / records / posts / 1,2

Où "1" et "2" sont les valeurs des clés primaires des enregistrements que vous souhaitez mettre à jour. Le corps devrait contenir le même nombre d’objets qu’il y a de clés primaires dans l’URL :

Ceci ajuste les titres des messages. Et les valeurs de retour sont le nombre de lignes définies :

1,1

Ce qui signifie qu’il y avait deux opérations de mise à jour et que chacune d’entre elles avait défini une ligne. Les opérations en mode batch utilisent des transactions de base de données, de sorte qu’elles réussissent ou échouent (les transactions réussies sont renvoyées).

Structure générale des formulaires

Le corps des formulaires présente la structure HTML suivante :

Adaptation de la charte graphique

Styles par défaut

Par défaut, les styles des formulaires d’identification sont définis dans la section head de chacun d’eux.

Fichier my.css

S’il existe un fichier /my.css à la racine du serveur, celui-ci est adopté comme feuille de style.

Ce fichier pourra être utilisé pour insérer un logo de l’organisation. Le champ #top est sans doute bien adapté à recevoir une image en background.

Champ css de la table Clients

Qu’il s’agisse de la feuille de style ou du défaut, les styles peuvent être complétés ou surchargés par le contenu du champ css de la table clients. Dans l’exemple ci-dessous, la variable $thecss contient les données de ce champ.

Ces styles intervenant en final, ils l’emportent sur les précédents.

Exemple

Voici par exemple les définitions de styles du formulaire de login :

PHP

Formulaire d’identification avec GhostKeys