Accueil > OpenID Connect OAuth Serveur dédié > Développer > Rafraîchir (actualiser) un jeton d’accès

Rafraîchir (actualiser) un jeton d’accès

Le rafraîchissement (ou l’actualisation) d’un jeton d’accès (Access Token Refresh) permet à une application cliente d’en prolonger la validité. La demande est faite au Point d’extrémité de jeton (Token Endpoint) en mentionnant le type de flux "refresh_token".

Les jetons de rafraîchissement ne sont fournis (et le sont alors systématiquement) que lors de la récupération d’un jeton avec les flux Autorisation via un code (Authorization Code Grant) et Autorisation via un mot de passe (User Credentials, Resource Owner Password Credentials Grant).

Avertissement : Une mauvaise utilisation du jeton de rafraîchissement peut faire perdre tout le bénéfice de sécurité d’OpenID Connect. Voir in fine : "Bonnes pratiques pour la sécurité".

Note : cet article s’applique aussi bien à OpenID Connect qu’à OAuth 2.0.

Forme de la demande de rafraîchissement d’un jeton d’accès

La demande ne doit être effectuée que par la méthode POST.
Les paramètres suivants doivent être postés :
- grant_type : "refresh_token".
- refresh_token : le code de rafraîchissement reçu avec le jeton d’accès.

Le client doit s’authentifier selon l’une des deux méthodes suivantes :

1. HTTP Basic Authentication (client_secret_basic)
Le client doit s’identifier en passant ses identifiants dans une entête Authorization.
Exemple avec PHP cUrl :

PHP

  1. // Identification du client avec HTTP Basic Authentication :
  2. $data = array(
  3.     'grant_type'     => 'refresh_token',
  4.     'refresh_token'  => $refresh_token,
  5. );
  6. $h = curl_init($token_endpoint);
  7. curl_setopt($h, CURLOPT_RETURNTRANSFER, true);
  8. curl_setopt($h, CURLOPT_TIMEOUT, 10);
  9. curl_setopt($h, CURLOPT_POST, true);
  10. curl_setopt($h, CURLOPT_USERPWD, "{$client_id}:{$client_secret}");
  11. curl_setopt($h, CURLOPT_SSL_VERIFYPEER, false);
  12. curl_setopt($h, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded'));
  13. curl_setopt($h, CURLOPT_POSTFIELDS, http_build_query($data));
  14.  
  15. $res = curl_exec($h);
  16.  
  17. if ( is_array(json_decode($res, true) ) ) {
  18.  
  19.     curl_close($h);
  20.     $res = json_decode($res, true);
  21.  
  22. }

Télécharger

2. Identifiants dans le corps de la demande (client_secret_post)
Les informations d’identification du client doivent être postés :
- client_id : l’ID de l’application cliente.
- client_secret : le secret de l’application cliente.
Les valeurs données pour les paramètres client_id et client_secret doivent correspondre aux valeurs définies lors de l’inscription de l’application cliente sur le serveur.

Réponse du serveur

En cas de succès, le serveur retourne une réponse HTTP 200.

Le corps de la réponse contient un tableau portant les informations suivantes :

index type valeur
page JSON array access_token : jeton d’accès

Le Header comporte, comme il se doit, la directive ’Cache-Control : no-cache, no-store’.

 

En cas d’échec, le corps de la réponse contient :

index type valeur
page JSON Array error : titre de l’erreur,
error_description : description de l’erreur

La réponse HTTP ainsi que les valeurs de error et error_description sont données par le tableau suivant :

Réponse error
titre de l’erreur
error_description
description de l’erreur
Explication
400 invalid_request Missing parameter : "refresh_token" is required Paramètre manquant : "refresh_token" est attendu
400 invalid_grant Invalid refresh token Jeton de rafraîchissement non valide
400 invalid_grant Refresh token has expired Le jeton de rafraîchissement a expiré

Ainsi que quelques autres réponses identiques à la demande d’un jeton d’accès.

Exemple de code

SPIP

  1. ...
  2. // Rafraîchir le jeton expiré
  3. $options = array(
  4.     'methode' => 'POST',
  5.     'datas' => array(
  6.         'grant_type' => 'refresh_token',
  7.         'refresh_token' => $_SESSION['oauth_refresh_token'],
  8.         'client_id' => 'XXXXX',                          
  9.         'client_secret' => 'XXXXXXXXXXXXXX',  
  10.     ),      
  11. );
  12.  
  13. $url = "http://oa.dnc.global/oauth/token.php";
  14. $refresh_response = recuperer_url($url,$options);
  15. $refresh_status = (int)$refresh_response['status'];
  16.  
  17. if ( $refresh_status == 200 ) {
  18.     $_SESSION['oauth_access_token'] = $refresh_response['access_token'];
  19.     return true;
  20. } else return false;
  21. ...

Télécharger

Attention :
Pour pouvoir rafraîchir un jeton d’accès, l’application cliente doit avoir été inscrite avec le Grant Type "Refresh Token" :

Bonnes pratiques pour la sécurité

Le jeton d’actualisation permet à l’application de demander au serveur d’émettre directement un nouveau jeton d’accès et/ou un nouveau jeton d’identification, sans avoir à authentifier à nouveau l’utilisateur. Cela fonctionnera tant que le jeton d’actualisation n’a pas été révoqué.

On comprendra qu’il convient de n’utiliser ce jeton que dans une relation serveur-serveur (back channel). C’est pourquoi l’obtention d’un jeton d’actualisation n’est possible qu’avec les flux Autorisation avec Code (Authorization Code Grant) ou Autorisation via mot de passe (User Credentials, Resource Owner Password Credentials Grant) [1] .

Dand le cadre d’OpenID Connect, OAuthSD ne fournira le jeton d’actualisation que si la demande de portée (scope) offline_access a été prédéfinie pour l’application cliente, est demandée dans la requête et a été acceptée par l’utilisateur final.

Compte tenu notamment de la nécessité de transmettre le paramètre client_secret, il est indispensable que l’application cliente stocke et transmette ce jeton de façon la plus sécurisée possible. Il convient d’appliquer les bonnes pratiques suivantes au jeton de rafraîchissement [2], sous peine de détruire la sécurité des flux considérés :
- le jeton de rafraîchissement ne doit pas être enregistré dans un cookie ;
- le jeton de rafraîchissement ne doit pas être passé en paramètre d’URL ;
- le jeton de rafraîchissement ne doit pas être envoyé depuis l’user-agent, c’est à dire dans le canal visible (front channel) par exemple à l’aide de code Javascript.
- ... ?

Notre avis sur le rafraîchissement

Avec le mécanisme SLI, OAuthSD permet de tout faire avec le flux le plus sécurisé : Autorisation via un code (Authorization code grant). En particulier, OAuthSD permet de rafraîchir les jetons à l’aide de la ré-authentification silencieuse (Silent Ré-authentication, SRA) qui offre toutes les garanties de sécurité. Une application en est donnée ici : Avertir de la fin de session OIDC et la prolonger.

Notes

[1Dans la liste déroulante, OAuthSD présente la possibilité d’utiliser le jeton de rafraîchisement conjointement à tous les flux ; bien entendu cela ne fonctionnera que pour les "bons" flux.

[2Ainsi qu’aux autres jetons !