1.5 Authentification

1.5.1 Authentification par cookie de session

L'accès à l'api requiert une session valide préexistante et préalablement ouverte à l'aide des mécanismes d'authentification de Dynacase (voir manuel de référence de Dynacase Core).

L'api n'est pas utilisable en mode "anonyme" ou "invité".

L'utilisation de l'api dans le cadre d'une interface issue d'une action ne nécessite pas d'autorisation particulière. Le cookie de session est transmis naturellement par le navigateur.

1.5.2 Authentification par jeton d'authentification

L'accès à l'api peut être autorisé à l'aide d'un jeton d'authentification.

Le jeton peut être indiqué dans le header HTTP :

GET api/v1/documents/9.json
Authorization: DcpOpen e2bb65612c70e7ac78d5ccbfe12aa234

Le terme "DcpOpen" est le "HTTP Authentication Scheme" pour identifier le mode d'autorisation.

Il peut être indiqué aussi dans le paramètre GET dcpopen-authorization

GET api/v1/documents/9.json?dcpopen-authorization=e2bb65612c70e7ac78d5ccbfe12aa234

Si un cookie de session est aussi utilisé, il sera ignoré. Le jeton est prioritaire sur le cookie de session.

1.5.2.1 Obtenir un jeton pour l'api

Le jeton d'accès peut être obtenu avec la méthode suivante :

string Dcp\HttpApi\V1\Authent::getAuthorizationToken(
                                    \Account $userAccount,
                                    array    $routes ,
                                    int      $expireDelay = -1, 
                                    bool     $oneshot = false)

Cette méthode retourne un jeton : une chaîne de caractères composée de caractères hexadécimaux (0-9a-f).

$userAccount (Account): Utilisateur identifié pour ce jeton: Les groupes ou rôles ne sont pas autorisés.
$expireDelay (int): Délai de validité du jeton en secondes.: Mettre "-1" (ou false) pour indiquer un délai infini.
$oneshot (bool): Mettre "true" pour indiquer que le jeton sera valide une seule fois: Le jeton est supprimé une fois consommée.
$routes (array): Tableau des routes autorisées: Indique sous forme d'expressions régulières les routes autorisées avec ce jeton la partie /api/v1, ne fait pas partie de la vérification.
De manière facultative, la méthode HTTP (GET, PUT, POST, DELETE) peut préfixer la route afin de limiter à une méthode donnée. Par défaut, les 4 méthodes sont autorisées. Note : un tableau vide n'autorise aucune route.

Une route peut être notée de différentes manières :

Simple expression régulière
- %^/documents/[0-9]+(.json)?$%
Expression régulière plus une méthode
- PUT %^/documents/[0-9]+(.json)?$%

Route avec contrainte de paramètre d'url

[
    "route" => "%^/vendor/my/logs$%",
    "methods" => ["GET"],
    "query" => ["level" => "warning"]
]

Dans ce dernier exemple, la route vers les logs de niveau "waring" sera autorisée seulement:

api/v1/vendor/logs?level=warning

1.5.2.2 Exemple de routes

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe"

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken($john, ["%.*%"]);
print $t; // > cad68f8e1848f12df16e44857c595f9a72124f41

Cet exemple autorise toutes les routes à vie pour l'utilisateur "john.doe".

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe" limité aux données de documents.

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken(
    $john, 
    [
      "%^/documents/[0-9]+(.json)?$%",
      "%^/families/[^/]+/[0-9]+(.json)?$%"
    ]);

Ici les routes autorisées peuvent être :

api/v1/documents/1234
api/v1/documents/5234.json
api/v1/families/employee/6234.json

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe" limité à la consultation des données de documents.

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken(
    $john, 
    [
      "GET %^/documents/[0-9]+(.json)?$%",
      "GET %^/families/[^/]+/[0-9]+(.json)?$%"
    ]);

1.5.2.3 Utilisation du jeton

En ligne de commande : à l'aide du programme curl :

curl  -H "Authorization: DcpOpen 8e05b60aac3f67447ab4e352a524633839924eda" http://www.example.net/api/v1/documents/12

En ligne de commande : à l'aide du programme wget :

wget http://www.example.net/api/v1/documents/12?dcpopen-authorization=cb713422beb7745f9567710ce011039fabf49224 -O 12.json

Sur un client web en javascript avec jQuery :

var token="8e05b60aac3f67447ab4e352a524633839924eda";
 
$.ajax({
  dataType: "json",
  url: "api/v1/documents/12",
  headers: {
    "Authorization":"DcpOpen " + token
  }
}).done(function (data) {
     console.log("Response", data);
}).fail(function () {
     console.error("Fail", arguments);
});

En PHP :

$token="8e05b60aac3f67447ab4e352a524633839924eda";
$url="http://www.example.net/api/v1/documents/12";
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Authorization: DcpOpen $token\r\n" 
  )
);
 
$context = stream_context_create($opts);
 
$file = file_get_contents($url, false, $context);
print $file;

1.5.3 Authentification par login et mot de passe

Cette authentification est basée sur l'authentification HTTP basic.

L'accès peut être effectué en indiquant le login et le mot de passe dans le header HTTP.

GET api/v1/documents/9.json
Authorization: Basic am9obi5kb2U6c2VjcmV0

Dans ce cas, celui-ci doit contenir la méthode utilisée (Basic) suivi de la représentation en Base64 du nom de l'utilisateur et du mot de passe séparés par le caractère « : » (deux-points).

L'accès peut être effectué via une url comportant le login est le mot passe

GET http://john.doe:secret@example.net/api/v1/documents/1234

Ce type d'authentification ne comporte pas d'autorisation particulière comme pour les jetons. Toute route est accessible en fonction des droits de l'utilisateur identifié.

Si un cookie de session est aussi utilisé, il sera ignoré. L'utilisation du login et du mot de passe est prioritaire.

Par contre, la requête HTTP contient un header "Authorization" avec la méthode "DcpOpen" et que l'url contient le login et le mot de passe alors, ce sera la méthode "Dcp" qui sera utilisée et non la méthode "Basic".

Note : On ne peut pas avoir 2 headers "Authorization" dans la requête.

1.5.3.1 Utilisation du mode basic

En ligne de commande : à l'aide du programme curl :

Avec les informations en clair :

curl   --user  "john.doe:secret" "http://www.example.net/api/v1/documents/12"
curl   "http://john.doe:secret@www.example.net/api/v1/documents/12"

Note : Dans ce cas curl utilise les informations de connexion pour écrire dans le header la clef "Authorization" avec la méthode "basic" d'authentification. Le programme "wget" ne supporte pas cette notation d'url avec les mots de passe.

Avec les informations encodées.

curl  -H "Authorization: Basic am9obi5kb2U6c2VjcmV0" http://www.example.net/api/v1/documents/12

Sur un client web en javascript avec jQuery :

var login="john.doe";
var password="secret";
 
$.ajax({
  dataType: "json",
  url: "api/v1/documents/12",
  headers: {
    "Authorization":"Basic " + btoa(login + ":" + password)
  }
}).done(function (data) {
     console.log("Response", data);
}).fail(function () {
     console.error("Fail", arguments);
});

En php :

$url="http://john.doe:secret@www.example.net/api/v1/documents/12";
 
$f=file_get_contents($url);
print $f;

Source : authent.md Dynacase Platform 3.2 | API HTTP Core Manuel de référence, version 1.0 édition 3, © Anakeen Labs <labs@anakeen.com>