Documents associés
OAuth 2.0 est normalisé en tant que RFC 6749. Un document détaillé est disponible sur https://oauth.net/2. L'authentification HTTP de base est définie dans la section 2 de la RFC 2617.
Présentation
En règle générale, pour permettre aux applications tierces d'accéder à des ressources restreintes telles que les détails du forfait de données et du portefeuille, l'utilisateur final (propriétaire de la ressource) doit partager ses identifiants avec le tiers. Cela crée plusieurs problèmes et limites, tels que le stockage des identifiants, l'authentification par mot de passe, l'accès étendu aux ressources de l'utilisateur final, la fuite de mot de passe, etc. OAuth 2.0 résout ces problèmes en introduisant une couche d'autorisation, ce qui permet de sécuriser et de limiter l'accès aux ressources protégées de l'utilisateur final.
Au lieu d'utiliser les identifiants de l'utilisateur final pour accéder aux ressources protégées telles que les détails du forfait de données, le GTAF obtient un jeton d'accès. Les jetons d'accès sont émis pour GTAF au nom de ses identifiants. Le GTAF utilise ensuite le jeton d'accès pour accéder aux détails du forfait de données hébergés par le DPA.
La figure suivante présente le flux d'informations de manière générale :
Figure 1. Flux OAuth abstrait.
Jetons d'accès
Les jetons d'accès sont les identifiants utilisés par le GTAF pour accéder aux détails du forfait de données à partir du DPA de l'opérateur. Un jeton d'accès est une chaîne représentant une autorisation émise pour le GTAF. La chaîne est généralement opaque pour le GTAF. Les jetons représentent des niveaux et des durées d'accès spécifiques, accordés par l'utilisateur final au transporteur et appliqués par le DPA et le serveur OAuth du transporteur.
Le jeton d'accès fournit une couche d'abstraction, en remplaçant différentes constructions d'autorisation (par exemple, nom d'utilisateur et mot de passe) par un jeton unique compris par le DPA. Cette abstraction permet d'émettre des jetons d'accès plus restrictifs que l'attribution d'autorisation utilisée pour les obtenir, et d'éviter au DPA d'avoir à comprendre un large éventail de méthodes d'authentification.
Les jetons d'accès peuvent avoir différents formats, structures et méthodes d'utilisation (par exemple, des propriétés cryptographiques) en fonction des exigences de sécurité du transporteur. GTAF n'accepte que les jetons d'accès de type porteur définis dans [RFC6750].
Authentification du client
Le GTAF fonctionne comme un "client confidentiel" et peut protéger les mots de passe. Le GTAF n'est actuellement compatible qu'avec l'authentification HTTP de base pour l'authentification auprès du DPA. L'identifiant client est encodé à l'aide de l'algorithme d'encodage "application/x-www-form-urlencoded", et la valeur encodée est utilisée comme nom d'utilisateur. Le mot de passe est encodé à l'aide du même algorithme et utilisé comme mot de passe.
Les clients confidentiels tels que GTAF, qui reçoivent des identifiants client, s'authentifient auprès du serveur OAuth de l'opérateur lorsqu'ils envoient des requêtes au point de terminaison du jeton. L'authentification du client est utilisée pour :\
- Récupérer un client piraté en le désactivant ou en modifiant ses identifiants, ce qui empêche un pirate informatique d'utiliser des jetons d'actualisation volés. Il est beaucoup plus rapide de modifier un seul ensemble d'identifiants client que de révoquer un ensemble complet de jetons d'actualisation.
- Mise en œuvre des bonnes pratiques de gestion de l'authentification, qui nécessitent une rotation périodique des identifiants.
Le GTAF utilise le paramètre de requête "client_id" pour s'identifier lorsqu'il envoie des requêtes au point de terminaison du jeton.
La possibilité de faire tourner les identifiants client est particulièrement importante. Le serveur OAuth doit être en mesure de prendre en charge deux paires d'identifiants simultanément lors de la rotation et doit pouvoir désactiver les identifiants. Dans une rotation d'identifiants typique :
- Le transporteur crée des identifiants sur le serveur OAuth et les transmet de manière sécurisée à son responsable de compte technique.
- Google teste le nouvel identifiant et modifie la configuration GTAF pour l'utiliser.
- Google informe l'opérateur que les anciens identifiants peuvent être désactivés.
- Le transporteur désactive les identifiants et en informe Google.
- Google vérifie que les anciens identifiants ne sont plus opérationnels.
Le serveur OAuth doit être en mesure de prendre en charge le processus de rotation ci-dessus.
Point de terminaison du jeton
Le point de terminaison de jeton est utilisé par le GTAF pour obtenir un jeton d'accès en présentant son jeton d'actualisation ou d'autorisation. Le point de terminaison du jeton est utilisé avec chaque attribution d'autorisation, à l'exception du type d'attribution implicite (puisqu'un jeton d'accès est émis directement).
Voici quelques points à prendre en compte lors de la configuration d'un point de terminaison de jeton :
- L'emplacement du point de terminaison du jeton doit être indiqué dans la documentation du service.
- L'URI du point de terminaison peut inclure un composant de requête au format "application/x-www-form-urlencoded", qui doit être conservé lorsque vous ajoutez des paramètres de requête supplémentaires. L'URI du point de terminaison ne doit pas inclure de composant de fragment.
- Étant donné que les requêtes envoyées au point de terminaison du jeton entraînent la transmission d'identifiants en texte clair (dans la requête et la réponse HTTP), le serveur OAuth de l'opérateur doit utiliser TLS pour envoyer des requêtes au point de terminaison du jeton.
- Le GTAF utilise la méthode HTTP "POST" lorsqu'il demande un jeton d'accès.
- Les paramètres envoyés sans valeur doivent être traités comme s'ils étaient omis de la requête. Le serveur OAuth doit ignorer les paramètres de requête non reconnus. Les paramètres de requête et de réponse ne doivent pas être inclus plusieurs fois.
- GTAF n'accepte que les jetons d'accès de type "porteur".
Niveau d'accès du jeton d'accès
Les points de terminaison d'autorisation et de jeton permettent au client de spécifier le champ d'application de la demande d'accès à l'aide du paramètre de requête "scope". À son tour, le serveur d'autorisation utilise le paramètre de réponse "scope" pour informer le client du champ d'application du jeton d'accès émis.
La valeur du paramètre "scope" est exprimée sous la forme d'une liste de chaînes sensibles à la casse et séparées par des espaces. Les chaînes sont définies par le serveur d'autorisation. Si la valeur contient plusieurs chaînes délimitées par des espaces, leur ordre n'a pas d'importance et chaque chaîne ajoute une plage d'accès supplémentaire au champ d'application demandé.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
GTAF n'exige pas que le champ d'application soit implémenté, mais prend en charge cette fonctionnalité. Pour en savoir plus, consultez la section 3.3 de la RFC 6749.
Émettre un jeton d'accès
Si la demande de jeton d'accès envoyée par le GTAF est valide et autorisée, le serveur OAuth émet un jeton d'accès et un jeton d'actualisation facultatif. Si la requête échoue l'authentification du client ou n'est pas valide, le serveur OAuth renvoie une réponse d'erreur, comme décrit dans la section suivante.
Réponse indiquant une réussite
Lorsque le GTAF envoie une requête, le serveur OAuth émet un jeton d'accès et un jeton d'actualisation facultatif, puis construit la réponse en ajoutant les paramètres suivants au corps de l'entité de la réponse HTTP avec un code d'état 200 (OK) : \
- access_token: : OBLIGATOIRE. Jeton d'accès émis par le serveur OAuth. GTAF s'attend à ce que le point de terminaison du jeton renvoie un jeton du porteur.
- expires_in: : OBLIGATOIRE. Durée de vie du jeton d'accès en secondes. Par exemple, la valeur "3600" indique que le jeton d'accès expirera une heure après la génération de la réponse. Si elle est omise, le serveur OAuth doit fournir le délai d'expiration par d'autres moyens ou documenter la valeur par défaut.
- token_type: : OBLIGATOIRE. Type de jeton émis. Pour en savoir plus sur les différents types de jetons, consultez la section 7.1 de la RFC 6749. Cette valeur n'est pas sensible à la casse. Au moment de la rédaction de cet article, GTAF n'accepte que les jetons porteurs.
- refresh_token: : FACULTATIF. Le jeton d'actualisation, qui peut être utilisé pour obtenir de nouveaux jetons d'accès à l'aide de la même autorisation.
- scope : FACULTATIF, si implémenté et identique au champ d'application demandé par le GTAF ; sinon, OBLIGATOIRE.
Les paramètres sont inclus dans le corps de l'entité de la réponse HTTP à l'aide de "application/json". Les paramètres sont sérialisés dans une structure JSON (JavaScript Object Notation) en ajoutant chaque paramètre au niveau de structure le plus élevé. Les noms de paramètres et les valeurs de chaîne sont inclus en tant que chaînes JSON. Les valeurs numériques sont incluses en tant que nombres JSON. L'ordre des paramètres n'a pas d'importance et peut varier.
Le serveur d'autorisation DOIT inclure le champ d'en-tête de réponse HTTP "Cache-Control" avec la valeur "no-store" dans toute réponse contenant des jetons, des identifiants ou d'autres informations sensibles, ainsi que le champ d'en-tête de réponse "Pragma" avec la valeur "no-cache".
Par exemple :
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Voici quelques points importants à prendre en compte :
- Le GTAF ignore les noms de valeurs non reconnus dans la réponse.
- La taille des jetons et des autres valeurs reçues du serveur OAuth n'est pas définie.
- Le GTAF doit éviter de faire des hypothèses sur la taille des valeurs. Le serveur OAuth doit documenter la taille de toute valeur qu'il émet.
Réponse d'erreur
Si une demande d'autorisation échoue pour une raison quelconque (par exemple, si l'URI de redirection est manquant, non valide ou ne correspond pas, ou si l'identifiant client est manquant ou non valide), le serveur OAuth doit répondre avec un code d'état HTTP 400 (Bad Request), sauf indication contraire, et doit inclure au moins l'un des paramètres listés dans la section "Réponse et codes d'erreur".
Autorisation dans GTAF
Une attribution d'autorisation est un identifiant représentant l'autorisation de l'utilisateur final (pour accéder à ses ressources protégées, telles que les informations sur le solde de données) utilisé par le GTAF pour obtenir un jeton d'accès.
Le GTAF utilise le type d'attribution client_credentials. Dans le type d'autorisation client_credentials, GTAF demande un jeton à l'aide d'une requête HTTP POST et de l'authentification HTTP de base. Toutes les requêtes sont envoyées via TLS (c'est-à-dire HTTPS), et GTAF ne peut pas s'intégrer à un serveur OAuth sans certificat TLS valide. GTAF est capable de transmettre un champ d'application de jeton configurable et transmettra un champ d'application vide si aucun n'est configuré.
GTAF s'attend à ce qu'un jeton d'accès soit renvoyé avec une valeur "expires_in" (durée de vie). La valeur expires_in doit être d'au moins 900 secondes et ne doit pas dépasser quelques heures. La demande d'un nouveau jeton ne doit pas entraîner l'expiration anticipée des jetons existants.
Pour en savoir plus sur les différents types d'autorisation, consultez la section 1.3 de la RFC 6749.
Exemple de requête et de réponse
Supposons que le GTAF présente la configuration suivante pour un serveur OAuth :
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Remarque : Le code secret du client pour une DPA réelle doit être beaucoup plus sécurisé que celui indiqué dans l'exemple.
Pour générer la chaîne d'autorisation, l'ID client, ":" et le mot de passe sont concaténés et encodés en base64. Vous pouvez reproduire cela dans une interface de ligne de commande comme suit :
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
GTAF envoie ensuite une requête HTTPS POST au serveur OAuth à l'aide de ces identifiants, du type d'autorisation client_credentials et du champ d'application configuré. Dans l'exemple, la requête de GTAF ressemble à celle générée par :
$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'
Les en-têtes utilisés par GTAF ne correspondront pas à ceux envoyés par curl, bien que l'en-tête d'autorisation soit identique.
GTAF attend une réponse au format suivant :
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
Voici un exemple de réponse valide :
{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}
Remarque : La réponse doit être un fichier JSON valide.
Réponse et codes d'erreur
Si une demande d'autorisation de GTAF échoue pour l'une des raisons indiquées dans la section "Réponse d'erreur", le serveur OAuth doit répondre avec un code d'état HTTP 400 (Bad Request), sauf indication contraire, et inclure l'un des paramètres suivants dans la réponse :
Par exemple : \
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
GTAF s'attend à ce que le serveur OAuth accepte les réponses d'erreur suivantes :
| Code d'erreur | Réponse | Motif |
| HTTP 400 | invalid_request | La requête ne contient pas de paramètre obligatoire, inclut une valeur de paramètre non acceptée (autre que le type d'autorisation), répète un paramètre, inclut plusieurs identifiants, utilise plusieurs mécanismes pour l'authentification avec le GTAF ou est mal formée. |
| HTTP 401 | invalid_client | L'authentification du client a échoué (par exemple, client inconnu, aucune authentification client incluse ou méthode d'authentification non acceptée). Le serveur OAuth peut renvoyer un code d'état HTTP 401 (Non autorisé) pour indiquer les schémas d'authentification HTTP compatibles. Si le client a tenté de s'authentifier via le champ d'en-tête de requête "Authorization", le serveur OAuth doit répondre avec un code d'état HTTP 401 (Non autorisé) et inclure le champ d'en-tête de réponse "WWW-Authenticate" correspondant au schéma d'authentification utilisé par le client. |
| HTTP 500 | Échec du serveur OAuth |
Pour en savoir plus sur les autres réponses pouvant être utilisées pour le débogage, consultez la section 5.2 de la RFC 6749.