OAuth2 Authorization Code Grant



Acteurs

Dans la suite, nous considérons les deux principales parties prenantes.
Acteur
Description
Resource Owner
Le détenteur de la ressource sur IntentPlatform. Par exemple, le gestionnaire de patrimoine ou un fournisseur de service.
Client
Le client logiciel, celui qui souhaite accéder aux ressources d'IntentPlatform, au nom de la tierce partie. Par exemple, le cloud ou l'application du fournisseur de service ou de terminaux.

Pour en savoir plus

La documentation officielle du protocole  OAuth 2.0 

Principes et étapes

Nous allons suivre la procédure Authorization Code Grant Flow.
Pré-requis

Resource Owner souhaite déléguer l'accès à ses données à Client, c'est pourquoi il doit avoir à disposition un accès (login, mot de passe) à IntentPlatform
Client doit avoir un compte pour authentifier son logiciel client (CLIENT_ID, CLIENT_SECRET), et pouvoir fournir une URI de redirection OAuth2 Callback URI
#
Etape
Description
Pré-requis
0
Préparation environnement
Pour pouvoir interagir avec IntentPlatform, il est nécessaire de mettre en place, côté Client, un webservice capable de prendre en compte le oauth code renvoyé par IntentPlatform lors de la phase 2.
-
1x
Enregistrement Client
Client prend contact avec Intent pour s'enregistrer et transmettre son URI de redirection.
0
2x
Autorisation
ResourceOwner s'authentifie au travers de Client.
1x
3x
Authentification
Client peut alors s'authentifier à son tour.
2x
4x
Requêtes API
Client émet des requêtes au nom de ResourceOwner.
3x


Le diagramme de séquence suivant résume ces étapes:
  • les traits pleins désignent les interactions avec IntentPlatform, via l'API
  • les traits pointillés désignent les interactions en dehors d'IntentPlatform, de manière indicative non-exhaustive.

Enregistrement de Client

Client s'enregistre sur Intent, il est nécessaire de nous communiquer votre OAuth2 Callback URI. Grâce à cette URI, IntentPlatform pourra renvoyer le code d'autorisation en réponse à l'authentification du Resource Owner.
En retour, vous recevrez les identifiants pour votre client d'application : CLIENT_ID, CLIENT_SECRET.

Enregistrement de ResourceOwner

ResourceOwner s'authentifie via Client.
En général, le client clique sur un lien pour accéder à un widget d'authentification. Il accède à une nouvelle fenêtre (le widget d'authentification) lui permettant de saisir ses identifiants.
Dans le lien, doivent être passés :
response_type
Précise le type de retour que doit faire le serveur d'autorisation. Ici, on utilisera toujours code
code
client_id
L'identifiant du client faisant la requête, ici Client. Fourni par Intent.
tr7228-992883
scope
La liste des accès à demander à l'API Intent. La liste (délimitée par des espaces) sera rappelée lors de l'authentification par le ResourceOwner. Les scopes sont disponibles sur la Reference.
read:devices read:datahub:data
redirect_uri
L'adresse URI (HTTPS) à laquelle la réponse contenant le code d'autorisation sera envoyé. C'est en général l'adresse où se trouve le script d'interprétation de la requête renvoyée par IntentPlatform. L'adresse doit être exactement la même que celle précisée à Intent lors la mise en place du canal.
 https://your.domain/intent-auth/script 
state
(Optionnel) Il est possible de préciser une valeur utile qui sera retournée telle quelle au serveur de réception de Client.
blabla

Exemple HTTP : 
https://accountsandbox.hubintent.com/oauth/authorize
  ?response_type=code
  &client_id=b860a00f-6b84-4bd8-9871-6e1f507d8fe2
  &scope=read:devices write:devices
  &redirect_uri=https://my.domain/intentplatform-auth/script
  &state=blabla
En retour, IntentPlatform redirige le navigateur de ResourceOwner vers le lien OAuth2 Callback URI déclaré, en compagnie d'un code authorization_code.

Exemple HTTP : 
https://my.domain/intentplatform-auth/script?code=863d9af120f2862f252476c7813839a7c59130d3&state=blabla
Cet appel permet au script configuré côté Client de récupérer le code.
Partage d'accès et d'identifiants

Le protocole OAuth2 Authorization Code Grant permet d'accorder un accès au ressource à une tierce partie. Il a été décrit pour éviter d'avoir à transmettre les identifiants d'un utilisateur à un tiers. Seul l'accès est accordé, pas l'authentification.

Authentification de Client

Client peut alors demander un token avec
  • l'url https://accountsandbox.hubintent.com/oauth/token
  • dans le body le code d'autorisation

JSON : 
{
  "code": "{{CODE}}",
  "client_id": "{{CLIENT_ID}}",
  "client_secret": "{{CLIENT_SECRET}}",
  "redirect_uri": "{{REDIRECT_URI}}",
  "grant_type": "authorization_code"
}
En réponse à la requête, Client recevra un access_token de connexion et un refresh_token pour le renouveler à son expiration :
  • le access_token a une durée limitée (ex: 1 heure),
  • le refresh_token permet de renouveler le access_token.

JSON : 
{
  "access_token":"5b97edbddaf8ae0bb0220fe34bd3e88cb0aca813",
  "token_type":"bearer",
  "refresh_token":"b4bf9be50c760e44d02c10798d7c4b969e786769"
}
Renouvellement de token : pour obtenir un nouvel access_token, il est possible de passer par la requête :
cURL : 
curl \
  -X POST \
  -d 'grant_type=refresh_token' \
  -d 'client_id=b860a00f-6b84-4bd8-9871-6e1f507d8fe2' \
  -d 'client_secret=12azerty345hgjghklqi678jljlkljl90' \
  -d 'refresh_token=4ec5cb74cd81da708c635aa67891fafc0794d9cd' \
  "https://accountsandbox.hubintent.com/oauth/token" \
IntentPlatform retourne une réponse similaire à la  première requête d'authentification . Il convient alors de stocker ce refresh_token pour demander un nouveau token à l'expiration du premier.

Requête de Client

Client peut alors émettre des requêtes au nom de Resource Owner.

Scopes

Tous les scopes sont détaillés sur l'API Reference.