Documents associés
OAuth 2.0 est conforme à la norme RFC 6749. Un document détaillé est disponible à l'adresse https://oauth.net/2. L'authentification de base HTTP est définie dans la section 2 de la RFC 2617.
Présentation
Généralement, pour permettre aux applications tierces d'accéder à des ressources restreintes, telles que les détails du forfait 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 mots de passe, etc. OAuth2.0 résout ces problèmes en introduisant une couche d'autorisation et en sécurisant et en limitant 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, la GTAF obtient un jeton d'accès. Les jetons d'accès sont émis pour le GTAF au nom des identifiants du GTAF. La GTAF utilise ensuite le jeton d'accès pour accéder aux détails du forfait de données hébergés par l'APD.
La figure suivante fournit un flux d'informations de haut niveau:
Figure 1. Flux OAuth abstrait.
Jetons d'accès
Les jetons d'accès sont les identifiants utilisés par la GTAF pour accéder aux détails du forfait de données 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 la GTAF. Les jetons représentent des champs d'application et des durées d'accès spécifiques. Ils sont accordés par l'utilisateur final à l'opérateur, et appliqués par l'APD et le serveur OAuth de l'opérateur.
Le jeton d'accès fournit une couche d'abstraction, qui remplace différentes constructions d'autorisation (par exemple, le nom d'utilisateur et le mot de passe) par un jeton unique compris par l'APD. Cette abstraction permet d'émettre des jetons d'accès plus restrictifs que l'autorisation d'accès utilisée pour les obtenir, ainsi que de supprimer les DPA requis pour comprendre un large éventail de méthodes d'authentification.
Les jetons d'accès peuvent adopter différents formats, structures et méthodes d'utilisation (par exemple, des propriétés cryptographiques) en fonction des exigences de sécurité de l'opérateur. GTAF n'est compatible qu'avec les jetons d'accès de type de support définis dans le document [RFC6750].
Authentification du client
La GTAF fonctionne en tant que "client confidentiel" et peut protéger les mots de passe. La GTAF n'est actuellement compatible qu'avec l'authentification HTTP Basic pour s'authentifier auprès du DPA. L'identifiant du client est encodé à l'aide de l'algorithme d'encodage "application/x-www-form-urlencoded" et la valeur encodée sert de nom d'utilisateur. Le mot de passe est encodé à l'aide du même algorithme et à la place du 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 tout en envoyant des requêtes au point de terminaison du jeton. L'authentification client est utilisée pour: \
- Récupération d'un client compromis en le désactivant ou en modifiant ses identifiants, ce qui empêche un pirate informatique d'utiliser abusivement 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.
- Implémenter les bonnes pratiques de gestion de l'authentification, qui nécessitent une rotation périodique des identifiants
La GTAF utilise le paramètre de requête &clienttid pour s'identifier lorsqu'il envoie des requêtes au point de terminaison du jeton.
La rotation des identifiants client est particulièrement importante. Le serveur OAuth doit être compatible avec deux paires d'identifiants simultanées pendant la rotation et doit pouvoir désactiver les identifiants. Dans une rotation classique des identifiants:
- L'opérateur crée des identifiants sur le serveur OAuth et les transmet à son responsable de compte technique de manière sécurisée.
- Google teste les nouveaux identifiants et modifie sa configuration afin d'utiliser ces derniers.
- Google informe l'opérateur que les anciens identifiants peuvent être désactivés.
- L'opérateur désactive les identifiants et informe Google
- Google vérifie que les anciens identifiants ne sont plus opérationnels
Le serveur OAuth doit être compatible avec le processus de rotation ci-dessus.
Point de terminaison du jeton
Le point de terminaison du jeton permet à la GTAF d'obtenir un jeton d'accès en présentant son jeton d'autorisation ou d'actualisation. Le point de terminaison du jeton est utilisé avec chaque autorisation accordée, à l'exception du type d'attribution implicite (étant donné qu'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" et devant être conservé lors de l'ajout de 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 adressé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 le protocole TLS pour envoyer des requêtes au point de terminaison du jeton.
- La GTAF utilise la méthode HTTP POST lors de la demande de jeton d'accès.
- Les paramètres envoyés sans valeur doivent être traités comme 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'est compatible qu'avec les jetons d'accès de type "support".
Portée 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" (portée) pour informer le client de la portée du jeton d'accès émis.
La valeur du paramètre de champ d'application est exprimée sous la forme d'une liste de chaînes délimitées par des espaces et sensibles à la casse. Les chaînes sont définies par le serveur d'autorisation. Si la valeur contient plusieurs chaînes séparées par un espace, leur ordre n'a pas d'importance, et chaque chaîne ajoute une plage d'accès supplémentaire au niveau d'accès demandé.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
Il n'est pas nécessaire de mettre en œuvre le champ d'application de la GTAF, mais elle est compatible avec cette fonctionnalité. Pour en savoir plus, consultez la section 3.3 du document 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 réussie
Lorsque la 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. Le GTAF s'attend à ce que le point de terminaison du jeton renvoie un jeton de support.
- 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 expire une heure après la génération de la réponse. En cas d'omission, 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 du document RFC 6749. Cette valeur n'est pas sensible à la casse. Au moment de la rédaction de ce document, le GTAF n'accepte que les jetons de support.
- refresh_token : facultatif. Jeton d'actualisation, qui peut être utilisé pour obtenir de nouveaux jetons d'accès avec la même autorisation.
- scope : facultatif (s'il est implémenté et identique au champ d'application requis par le GTAF, sinon).
Les paramètres sont inclus dans le corps de l'entité de la réponse HTTP à l'aide de l'application/json. Les paramètres sont sérialisés dans une structure JSON (JavaScript Object Notation) en ajoutant chaque paramètre au niveau de la structure la plus élevée. Les noms de paramètres et les valeurs de chaîne sont inclus sous forme de chaînes JSON. Les valeurs numériques sont incluses sous la forme de 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 "Cache-Control" avec la valeur "no-store" dans toutes les réponses 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:
- La GTAF ignore les noms de valeurs non reconnus dans la réponse.
- La taille des jetons et d'autres valeurs reçues du serveur OAuth n'est pas définie.
- La GTAF doit éviter de formuler des hypothèses sur les tailles des valeurs. Le serveur OAuth doit documenter la taille de toute valeur qu'il émet.
Réponse d'erreur
Si une requête d'autorisation échoue pour une raison quelconque, telle que l'URI de redirection manquant, non valide ou non concordant, ou si l'identifiant client est manquant ou non valide, le serveur OAuth doit renvoyer un code d'état HTTP 400 (Requête incorrecte), sauf indication contraire, et doit inclure au moins l'un des paramètres répertoriés dans la section Codes d'erreur et de réponse.
Autorisation d'autorisation dans GTAF
Une autorisation 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 de solde de données) utilisée par la GTAF pour obtenir un jeton d'accès.
La GTAF utilise le type d'attribution client_credentials. Dans le type d'attribution client_credentials, la GTAF demande un jeton à l'aide d'une requête HTTP POST et de l'authentification de base HTTP. Toutes les requêtes sont envoyées via le protocole TLS (c'est-à-dire, HTTPS) et GTAF ne peuvent pas s'intégrer à un serveur OAuth sans certificat TLS valide. GTAF est capable de transmettre un champ d'application de jeton configurable et transmet un champ d'application vide s'il n'est pas configuré.
Le GTAF s'attend à ce qu'un jeton d'accès soit renvoyé avec une valeur "expires_in"" (durée de vie). La valeur expire_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'attributions, consultez la section 1.3 du document RFC 6749.
Exemple de requête et de réponse
Supposons que le GTAF dispose de 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 un DPA réel doit être bien plus sécurisé que celui présenté 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 le répliquer 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'attribution client_credentials et du champ d'application configuré. Pour cet exemple, la requête 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.
Le GTAF attend une réponse sous la forme suivante:
{
"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 au format 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 "Error Response", le serveur OAuth doit renvoyer un code d'état HTTP 400 (Requête incorrecte), sauf indication contraire, et inclure l'un des paramètres suivants dans la réponse:
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 | Response (Réponse) | Motif |
| HTTP 400 | requête non valide | Il manque un paramètre obligatoire dans la demande, inclut une valeur de paramètre non compatible (autre que le type d'attribution), répète un paramètre, inclut plusieurs identifiants, utilise plusieurs mécanismes d'authentification auprès du GTAF ou présente un autre format incorrect. |
| HTTP 401 | client_non valide | Échec de l'authentification du client (par exemple, client inconnu, aucune authentification client incluse ou méthode d'authentification incompatible). 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 par 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.