OpenID Connect OAuth Server dédié

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.