L’API Phraseanet v1 n’est accessible que par le protocole oAuth2.0. OAauth2.0 permet l’accés à une API sécurisée d’une manière simple et standard.
Pour le développement en PHP, il est recommandé d’utiliser la Phraseanet PHP SDK. Pour les autres langages, des librairies sont consultables dans oAuth2.0 libraries.
Un code d’autorisation représente l’autorisation du propriétaire de la ressource (pour accéder à ses ressources protégées). il est utilisé par le client pour obtenir un jeton d’accès.
Le jetons d’accès est un code d’identification utilisées pour accéder aux ressources protégées d’un utilisateur de Phraseanet.
Pour obtenir une demande d’autorisation d’accés aux ressources d’un utilisateur Phraseanet le développeur doit rediriger l’utilisateur final vers l’URL d’autorisation.
https://exemple.instance.phrasea.net/api/oauthv2/authorize
avec les paramètres suivants :
mandatory string - Le client ID reçu de Phraseanet lors de la création de l’application tierce.
optional string - Le client secret reçu de Phraseanet lors de la création de l’application tierce.
mandatory string - L’un des types de reponse.
mandatory string - La même URI de redirection fournie lors de l’application tierce.
optional string - Une chaîne de caractère non prédictible (Sert à proteger contre les attaques CSRF).
Exemple de redirection via un navigateur internet.
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=YOUR_RESPONSE_TYPE
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier avec Phraseanet</a>
Une demande d’autorisation peut renvoyer un code d’autorisation de trois manières différentes en fonction du paramètre “response_type” qui est fournit dans l’URL d’autorisation.
Renvoi un code d’autorisation dans un paramètre de l’URI de redirection fournie lors de la création d’une application tierce.
Requête
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier avec Phraseanet</a>
Réponse
https://YOUR_REGISTERED_REDIRECT_URI/?code=AUTHORISATION_CODE
De manière implicite, renvoi un jeton d’accés présent sous forme d’un fragment de l’URI de redirection.
Voir cas d’utilisation : application ajax.
Requête
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=token
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier avec Phraseanet</a>
Réponse
https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
Renvoi à la fois un code d’autorisation dans l’URI de redirection ainsi qu’un fragment contenant un jeton d’accés.
Requête
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code_and_token
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier avec Phraseanet</a>
Réponse
https://YOUR_REGISTERED_REDIRECT_URI/?code=AUTHORISATION8CODE#access_token=ACCESS_TOKEN
Il existe différentes manières de récupérer un jeton d’accés pour accéder aux ressources de Phraseanet.
Voir les Cas d’utilisation.
Pour obtenir une jeton d’accés aux ressources d’un utilisateur Phraseanet le développeur doit effectuer une requête HTTP vers l’URL d’accés.
https://exemple.instance.phrasea.net/api/oauthv2/token
Les paramètres pour l’URL du token d’accès varient selon le type d’authentification demandé par le dévéleppeur.
L’API Phraseanet supporte deux méthodes d’authentification.
Cette méthode nécessite l’obtention au prélabale d’un code d’autorisation.
Voir Obtenir un code d’autorisation.
Paramètres
mandatory string - Le client ID reçu de Phraseanet lors de la création de l’application tierce.
optional string - Le client secret reçu de Phraseanet lors de la création de l’application tierce.
mandatory string - authorization_code
mandatory string - La même URI de redirection fournie lors de l’application tierce.
mandatory string - Le code rétourné par le point d’autorisation.
curl --data
"client_id=YOUR_CLIENT_ID
&grant_type=authorization_code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&code=CODE" https://exemple.instance.phrasea.net/api/oauthv2/token
La réponse est au format JSON.
{
access_token: YOUR_ACCESS_TOKEN
}
Cette méthode ne nécessite pas l’obtention d’un code d’autorisation mais l’identifiant et le mot de passe Phraseanet du propriétaire de la ressource.
Avertissement
Attention, cette méthode ne doit être utilisée que lorsqu’il y a un degré élevé de confiance entre le propriétaire de la ressource et le client.
Paramètres
mandatory string - Le client ID reçu de Phraseanet lors de la création de l’application tierce.
optional string - Le client secret reçu de Phraseanet lors de la création de l’application tierce.
mandatory string - password
mandatory string - La même URI de redirection fournie lors de l’application tierce.
mandatory string - L’identifiant Phraseanet du proriétaire de la ressource.
mandatory string - Le mot de passe Phraseanet du proriétaire de la ressource.
curl --data
"client_id=YOUR_CLIENT_ID
&grant_type=password
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&username=USERNAME
&password=PASSWORD" https://exemple.instance.phrasea.net/api/oauthv2/token
La réponse est au format JSON.
{
access_token: YOUR_ACCESS_TOKEN
}
Le développeur doit rediriger l’utilisateur final vers le point d’autorisation pour obtenir un code d’autorisation.
Voir Obtenir un code d’autorisation.
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier</a>
L’utilisateur final s’identifie sur Phraseanet et le navigateur est redirigé vers redirect_uri.
Si l’authentification est correcte, un paramètre code est disponible dans l’URI de retour, à côté du paramètre state (si fourni).
Si l’authentification est incorrecte, un paramètre error est présent.
Exemple d’URI après succès d’authentification :
https://YOUR_REGISTERED_REDIRECT_URI/?code=49ce2762ff5413607ae936b2ca6e409e
Exemple d’URI en erreur.
https://YOUR_REGISTERED_REDIRECT_URI/?error=Invalid+user
Une fois que le développeur a récupéré le code, il doit être échangé contre un token oauth en utilisant le point du token d’accès. Tandis que l’étape précédente résulte de l’interaction entre l’utilisateur final et Phraseanet, cet échange est fait côté serveur.
Voir obtenir un jeton d’accés.
curl --data "client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&grant_type=authorization_code
&code=a7udj6y880" https://exemple.instance.phrasea.net/api/oauthv2/token
Ce flux est destiné aux applications mobiles et de bureau qui veulent accéder à des données utilisateurs.
Le flux d’authentification des applications natives est identique aux flux des applications internet à une exception prés. Il faut spécifier une URL de redirection spéciale urn: ietf: wg: oauth: 2.0: oob. “oob” est l’acronyme de “out of band” et le reste de la chaîne identifie l’URL comme faisant partie du protocole oAuth2.0.
Lorsque cette url de redirection est utilisée, Phraseanet affiche le code d’autorisation dans un champ texte avec comme instruction pour l’utilisateur de copier et de coller ce code dans l’application.
<a href="https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=urn:ietf:wg:oauth:2.0:oob">Cliquer ici pour vous
authentifier</a>
Une fois que le développeur a récupéré le code, il doit être échangé contre un token oauth en utilisant l’url du token d’accès. Cet échange est fait par l’intermédiaire de l’application cliente.
Voir obtenir un jeton d’accés.
curl --data "client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&grant_type=authorization_code
&code=a7udj6y880" https://exemple.instance.phrasea.net/api/oauthv2/token
Le développeur doit rediriger l’utilisateur final vers le point d’autorisation et récupére à l’issue de la redirection non pas un code d’autorisation mais directement un token d’accés de manière implicite.
Voir obtenir un token via une demande d’autorisation.
<a href="https://exemple.instance.phrasea.net/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=token
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI">Cliquer ici pour vous
authentifier</a>
Si l’utilisateur accepte, il est redirigé à l’adresse suivante :
https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
Le token d’accés est alors disponible dans le fragment de l’URL de redirection.
Pour obtenir directement un jeton d’accés, utiliser les informations d’identification de l’utilisateur qui détient les ressources Phraseanet (cf un identifiant et un mot de passe).
Cette méthode évite le besoin d’avoir à stocker un code d’autorisation.
L’opération consiste à effectuer une requête sur l’url du token d’accés afin de récupérer un jeton valide.
curl --data "client_id=YOUR_CLIENT_ID
&grant_type=password
&username=johndoe
&password=A3ddj3w" https://exemple.instance.phrasea.net/api/oauthv2/token
Note
Ce type d’authentification n’est active que si l’application cliente enregistrée auprés de Phraseanet authorise ce type d’authentification.
Le token d’accés peut être utiliser pour appeler une ressource protégée en incluant celui-ci dans les paramétres de la requête ou bien dans un en-tête ‘Authorization’. Par exemple :
curl https://exemple.instance.phrasea.net/api/v1/baskets/list/?oauth_token=YOUR_ACCESS_TOKEN
Note
A cet instant, le jeton d’authentification n’a pas de date d’expiration, cependant, il faut être préparer à cette éventualité dans le futur. Cependant un utilisateur peut révoquer l’accès à ses données via la page de configuration de Phraseanet à n’importe quel moment.