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.
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. Ne pas oublier qu’un utilisateur peut révoquer l’accés à ses données via la page de configuration de Phraseanet à n’importe quel moment.
Avec oAuth2.0, pour recevoir les accés à l’API phraseanet, toutes les applications ont besoins d’enregistrer au moins leur nom et une URL de ‘redirection’ dans Phraseanet.
Une fois l’application enregistrée, Phraseanet fournira un identifiant et un mot de passe qui identifie l’application nouvellement créée auprés de Phraseanet.
L’enregistrement d’une nouvelle application utilisant l’API Phraseanet se fait dans la page de configuration d’un compte. On accéde à cette page en cliquant sur son identifiant dans la bar de menu de Phraseanet.
Il y a trois manières différentes d’utiliser l’API Phraseanet.
Le développeur doit rediriger l’utilisateur final vers le point d’authorisation 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).
L’utilisateur final s’identifie sur Phraseanet et le navigateur est redirigé vers redirect_uri.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REGISTERED_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://example.com/callback/?code=49ce2762ff5413607ae936b2ca6e409e
Exemple d’URI en erreur.
https://example.com/callback/?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 utilisateur finale et Phraseanet, cet échange est fait côté serveur.
Les paramètres pour le point du token d’accès sont les 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 d’authentification.
mandatory string - La même URI de redirection fournie lors de l’application tierce.
mandatory string - Le code rétourné par le point d’authorization.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
https://SERVER_NAME/api/oauthv2/token
?client_id=YOUR_CLIENT_ID
&grant_type=authorization_code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&code=CODE
La réponse est au format JSON.
{
access_token: YOUR_ACCESS_TOKEN
}
Rediriger les utilisateurs qui désirent authoriser l’accés à leurs données à votre application en cliquant sur le lien suivant.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=token
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
Si l’utilisateur accepte, il est redirigé à l’adresse suivante. Le token d’accés est alors disponible dans l’URL.
https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_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 internets à 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 parti du protocole oAuth2.0.
Lorsque cette url de redirection est utilisée, Phraseanet affiche la réponse d’autorisation dans un champ texte avec des instructions pour l’utilisateur de copier et de coller le code dans votre application.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code
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://SERVER_NAME/api/v1/baskets/list/?oauth_token=YOUR_ACCESS_TOKEN
Pour obtenir directement un jeton d’accés, utiliser les informations d’indentification 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 le jeton d’autorisation d’accès.
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.
Voir aussi
Voir aussi la RFC oAuth v2 draft #10.
https://SERVER_NAME/api/oauthv2/token
?client_id=YOUR_CLIENT_ID
&grant_type=password
&username=johndoe
&password=A3ddj3w