Avertissement: Cette page concerne les anciennes API Google, les API Google Data. Elle ne concerne que les API répertoriées dans l'annuaire des API Google Data, dont la plupart ont été remplacées par de nouvelles API. Pour en savoir plus sur une nouvelle API spécifique, consultez sa documentation. Pour en savoir plus sur l'autorisation des requêtes avec une API plus récente, consultez Authentification et autorisation des comptes Google.

Ce document explique comment utiliser les bibliothèques clientes de l'API Google Data pour se connecter à l'authentification AuthSub de Google.

L'interface AuthSub permet à une application Web d'accéder à un service Google au nom d'un utilisateur. Pour garantir un niveau de sécurité élevé, l'interface AuthSub permet à l'application d'obtenir un jeton d'authentification sans devoir gérer les informations de connexion du compte de l'utilisateur.

Les bibliothèques clientes de l'API Google Data fournissent des méthodes pour vous aider à utiliser AuthSub dans votre application Web. Plus précisément, il existe des méthodes pour créer l'URL de requête, acquérir un jeton d'authentification à usage unique, échanger le jeton à utilisation unique contre un jeton de session et signer la requête.

Remarque : La bibliothèque cliente JavaScript possède sa propre version d'AuthSub : AuthSubJS. Pour en savoir plus sur l'utilisation d'AuthSubJS dans vos applications JavaScript, consultez la page Utiliser l'authentification "AuthSub" avec la bibliothèque cliente JavaScript.

Audience

Ce document est destiné aux programmeurs qui souhaitent que leurs applications Web puissent accéder aux services Google au nom des utilisateurs à l'aide des bibliothèques clientes des API Google Data.

Dans ce document, nous partons du principe que vous connaissez l'interface AuthSub et le processus général d'intégration d'AuthSub à votre application Web. Pour obtenir une description complète du protocole d'AuthSub, consultez la section Authentification AuthSub pour les applications Web.

Utiliser AuthSub et les API Google Data sans les bibliothèques clientes

Si vous souhaitez que votre client d'application Web interagisse avec un service de données Google en utilisant AuthSub comme système d'authentification, vous trouverez toutes les informations nécessaires dans la section Authentification AuthSub pour les applications Web. Si vous ne le souhaitez pas, vous n'avez pas besoin d'utiliser les bibliothèques clientes des API Google Data.

Voici comment votre application peut authentifier un utilisateur à l'aide d'AuthSub:

Votre application construit l'URL AuthSub appropriée, puis envoie l'utilisateur à cette URL pour qu'il puisse se connecter. Le système AuthSub renvoie l'utilisateur à l'URL de votre site que vous avez spécifiée et renvoie un jeton à usage unique. Votre application échange éventuellement ce jeton contre un jeton de session. Votre application envoie ensuite le jeton dans l'en-tête Authorization avec chaque requête envoyée par l'application au service.

Les bibliothèques clientes des API Google Data simplifient ce processus d'autorisation en gérant plusieurs informations à votre place. Ce document explique comment procéder.

Utiliser AuthSub et les API Google Data: exemples de la bibliothèque cliente

Cette section présente un exemple d'utilisation des méthodes de la bibliothèque cliente des API Google Data pour suivre les étapes décrites dans la section Travailler avec AuthSub de la documentation AuthSub.

Dans cet exemple, nous intégrons l'interface AuthSub à une application Web qui interagit avec Google Agenda (même si vous n'avez aucune connaissance de Google Agenda pour suivre l'exemple). L'exemple suppose que l'application Web est hébergée sur example.com.

Choisir le type de jeton à utiliser (session=0 ou session=1)

Vous pouvez choisir d'utiliser des jetons à usage unique (session=0) ou des jetons de session (session=1). Ce document utilise des jetons de session, car ils sont plus utiles dans les applications qui émettent plusieurs requêtes API. Comme indiqué dans la documentation AuthSub, si vous décidez d'utiliser des jetons de session dans votre application Web, vous devez gérer vous-même le stockage de jetons. Ce document ne couvre pas la gestion des jetons. Notez également que les jetons demandés avec session=0 ne peuvent plus être échangés (mis à niveau) contre des jetons de session de longue durée.

Déterminez si vous souhaitez enregistrer votre application Web (secure=0 ou secure=1)

AuthSub peut être utilisé dans trois modes différents : non enregistré, enregistré et enregistré avec une sécurité renforcée. Dans la suite de ce document, la dernière option sera appelée AuthSub sécurisé. Bien que le mode non enregistré/enregistré soit plus simple à configurer que la méthode AuthSub sécurisée, Google vous encourage à utiliser des jetons sécurisés pour renforcer leur sécurité.

Comment s'inscrire

Si vous sélectionnez Inscription pour les applications Web, votre application bénéficiera des avantages suivants:

1. Un niveau de sécurité plus élevé
2. être approuvé par Google (aucun avertissement ne s'affiche sur la page d'autorisation Google) ;

AuthSub + AuthSub sécurisé

Si vous optez pour une authentification AuthSub sécurisée, vous devrez créer une clé privée RSA et une paire de certificats publics autosignés, en plus de l'enregistrement de votre application Web. Pour obtenir des exemples de création de certificats X.509, consultez Générer des clés et des certificats à utiliser avec le mode enregistré (ci-dessous).

Déterminer la portée de votre accès aux données

Chaque service Google définit une valeur scope qui détermine (voire restreint) l'accès d'un jeton aux données de l'utilisateur. Consultez les questions fréquentes pour obtenir la liste des valeurs scope disponibles.

Comme nous avons décidé d'interagir avec l'API Google Calendar, scope doit être http://www.google.com/calendar/feeds/.

Remarque : Définissez toujours la valeur du champ d'application sur l'URL la plus large possible, sauf si vous devez définir une restriction plus précise. Par exemple, un champ d'application plus restreint tel que scope=http://www.google.com/calendar/feeds/default/allcalendars/full limite l'accès du jeton aux seuls agendas complets/flux. L'utilisation de scope=http://www.google.com/calendar/feeds/ permet d'accéder à tous les flux d'Agenda : http://www.google.com/calendar/feeds/*.

Jetons à plusieurs champs d'application

Pour créer des jetons d'accès à plusieurs API Google Data, séparez chaque champ d'application par un espace encodé au format URL. L'exemple ci-dessous crée un jeton qui aura accès aux données Google Contacts et Google Agenda d'un utilisateur.

scope=http://www.google.com/calendar/feeds/%20http://www.google.com/m8/feeds/

Demander un jeton d'authentification à usage unique

Pour acquérir un jeton AuthSub pour un utilisateur et un service donnés, votre application doit rediriger l'utilisateur vers l'URL AuthSubRequest, qui l'invite à se connecter à son compte Google. (Pour plus d'informations sur l'URL AuthSubRequest, consultez la page Authentification AuthSub pour les applications Web.)

Pour créer l'URL AuthSubRequest dans votre application, utilisez le code suivant pour chaque bibliothèque cliente:

import com.google.gdata.client.*;

String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request secure AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

import com.google.gdata.client.*;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.jsp";
String scope = "http://www.google.com/calendar/feeds/";
boolean secure = false;  // set secure=true to request AuthSub tokens
boolean session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

using Google.GData.Client;

String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(nextUrl, scope, secure, session);

using Google.GData.Client;

String hostedDomain = "example.com";
String nextUrl = "http://www.example.com/RetrieveToken.aspx";
String scope = "http://www.google.com/calendar/feeds/";
bool secure = false; // set secure=true to request secure AuthSub tokens
bool session = true;
String authSubUrl = AuthSubUtil.getRequestUrl(hostedDomain, nextUrl, scope, secure, session);

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session);

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

$hostedDomain = 'example.com';
$nextUrl = 'http://www.example.com/RetrieveToken.php';
$scope = 'http://www.google.com/calendar/feeds/';
$secure = 0;  // set $secure=1 to request secure AuthSub tokens
$session = 1;
$authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($nextUrl, $scope, $secure, $session) . '&hd=' . $hostedDomain;

import gdata.auth

next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session)

import gdata.auth

hosted_domain = 'example.com'
next = 'http://www.example.com/RetrieveToken.pyc'
scope = 'http://www.google.com/calendar/feeds/'
secure = False  # set secure=True to request secure AuthSub tokens
session = True
auth_sub_url = gdata.auth.GenerateAuthSubRequestUrl(next, scope, secure=secure, session=session, domain=hosted_domain)

Une fois l'URL "suivante" créée, votre application peut l'utiliser de différentes manières pour envoyer l'utilisateur au gestionnaire AuthSubRequest. L'approche la plus courante consiste à afficher une page indiquant à l'utilisateur qu'il doit suivre un lien pour autoriser votre application à accéder à son compte Google, puis à joindre l'URL de la requête au lien. Par exemple, vous pouvez générer la chaîne suivante dans votre application Web:

String authorizationUrl =
        "<p>MyApp needs access to your Google Calendar account to read your Calendar feed. " +
        "To authorize MyApp to access your account, <a href=\"" + authSubUrl + "\">log in to your account</a>.</p>";

L'utilisateur suit le lien vers la page AuthSub de Google et se connecte. Le système AuthSub redirige ensuite l'utilisateur vers votre application à l'aide de l'URL "suivante" que vous avez fournie.

Extraire le jeton à usage unique

Lorsque Google effectue une redirection vers votre application, le jeton est ajouté à l'URL "next" en tant que paramètre de requête. Dans les exemples ci-dessus, une fois que l'utilisateur s'est connecté, Google le redirige vers une URL telle que http://www.example.com/RetrieveToken?token=DQAADKEDE. Votre application doit extraire la valeur du jeton de son paramètre de requête d'URL.

Si votre application définit un cookie d'authentification dans le navigateur de l'utilisateur avant de l'envoyer au système AuthSub, lorsque Google effectue une redirection vers l'URL "suivante", votre application peut lire le cookie d'authentification afin d'identifier l'utilisateur qui est arrivé sur cette URL. Vous pouvez utiliser un tel cookie pour associer un ID utilisateur dans votre application au jeton AuthSub extrait de Google.

Les bibliothèques clientes fournissent des méthodes pratiques pour extraire le jeton à usage unique:

String singleUseToken = AuthSubUtil.getTokenFromReply(httpServletRequest.getQueryString());

String singleUseToken = Request.QueryString["token"];
// or
String singleUseToken = AuthSubUtil.getTokenFromReply(new Uri(Request.QueryString));

$singleUseToken = $_GET['token'];

current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url)

f = open('/path/to/yourRSAPrivateKey.pem')
rsa_key = f.read()
f.close()
current_url = 'http://' + req.hostname + req.unparsed_uri
# Unlike the other calls, extract_auth_sub_token_from_url() will create an AuthSubToken or SecureAuthSubToken object.
# Use str(single_use_token) to return the token's string value.
single_use_token = gdata.auth.extract_auth_sub_token_from_url(current_url, rsa_key=rsa_key)

Demander un jeton de session

Le jeton que vous récupérez à partir de l'URL est toujours un jeton à usage unique. L'étape suivante consiste à mettre à niveau ce jeton pour un jeton de session de longue durée à l'aide de l'URL AuthSubSessionToken, comme décrit dans la documentation complète sur l'authentification AuthSub pour les applications Web. Si vous utilisez l'authentification AuthSub sécurisée, vous devez définir votre clé privée RSA avant d'effectuer l'échange. Voici quelques exemples d'utilisation de chaque bibliothèque cliente:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, null);

// ready to interact with Calendar feeds

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

java.security.PrivateKey privateKey =
    AuthSubUtil.getPrivateKeyFromKeystore("AuthSubExample.jks", "privKeyPa$$word", "AuthSubExample", "privKeyPa$$word");
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, privateKey);

CalendarService calendarService = new CalendarService("google-ExampleApp-v1.0");
calendarService.setAuthSubToken(sessionToken, privateKey);

// ready to interact with Calendar feeds

using Google.GData.Client;
using Google.GData.Calendar;

String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, null).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

using Google.GData.Client;
using Google.GData.Calendar;

protected AsymmetricAlgorithm getRsaKey()
{
  X509Certificate2 cert = new X509Certificate2("C:/MyAspSite/test_cert.pfx", "privKeyPa$$word");
  RSACryptoServiceProvider privateKey = cert.PrivateKey as RSACryptoServiceProvider;
  return privateKey;
}

AsymmetricAlgorithm rsaKey = getRsaKey();
String sessionToken = AuthSubUtil.exchangeForSessionToken(singleUseToken, rsaKey).ToString();

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "google-ExampleApp-v1.0");
authFactory.Token = (String) sessionToken;
authFactory.PrivateKey = rsaKey;

CalendarService calendarService = new CalendarService(authFactory.ApplicationName);
calendarService.RequestFactory = authFactory;

// ready to interact with Calendar feeds

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken);

// Create a Calendar service object and set the session token for subsequent requests
$calendarService = new Zend_Gdata_Calendar(null, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_Calendar');

$client = new Zend_Gdata_HttpClient();
$client->setAuthSubPrivateKeyFile('/path/to/myrsakey.pem', null, true);
$sessionToken = Zend_Gdata_AuthSub::getAuthSubSessionToken($singleUseToken, $client);

$calendarService = new Zend_Gdata_Calendar($client, 'google-ExampleApp-v1.0');
$calendarService->setAuthSubToken($sessionToken);

// ready to interact with Calendar feeds

import gdata.calendar
import gdata.calendar.service

calendar_service = gdata.calendar.service.CalendarService()
calendar_service.UpgradeToSessionToken(single_use_token)  # calls gdata.service.SetAuthSubToken() for you

# ready to interact with Calendar feeds

Remarque : Lorsque vous utilisez AuthSub sécurisé, votre clé privée n'est pas envoyée sur le réseau. Les bibliothèques clientes envoient la signature unique générée en signant la requête avec votre clé, et non avec la clé elle-même.

Utiliser le jeton de session

Vous pouvez utiliser le jeton de session pour authentifier les requêtes auprès du serveur en le plaçant dans l'en-tête "Authorization", comme décrit dans la documentation AuthSub.

Une fois que vous avez défini votre jeton de session, vous pouvez utiliser les appels standards de la bibliothèque cliente des API Google Data pour interagir avec le service, sans avoir à vous soucier du jeton. Pour en savoir plus, consultez la documentation de la bibliothèque cliente et le guide du développeur des API de données Google pour le service et le langage avec lesquels vous interagissez.

Récupérer des informations sur un jeton de session

Si vous souhaitez vérifier que votre client et le serveur s'accordent sur les paramètres du jeton, vous pouvez le transmettre au gestionnaire AuthSubTokenInfo, qui renvoie un ensemble de paires nom/valeur contenant des informations sur le jeton.

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, null);

Map<String, String> tokenInfo = AuthSubUtil.getTokenInfo(sessionToken, privateKey);

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, null);

Dictionary<String, String> tokenInfo = AuthSubUtil.GetTokenInfo(sessionToken, privateKey);

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken);

$tokenInfo = Zend_Gdata_AuthSub::getAuthSubTokenInfo($sessionToken, $client);

token_info = calendar_service.AuthSubTokenInfo()

Révoquer un jeton de session

Les jetons de session AuthSub n'expirent pas. Votre client peut les conserver aussi longtemps que nécessaire.

Par conséquent, lorsque votre client a terminé d'utiliser le jeton de session, il peut le révoquer à l'aide du gestionnaire AuthSubRevokeToken, comme décrit dans la documentation AuthSub.

Par exemple, si vous souhaitez gérer les jetons de façon classique, votre client peut obtenir un jeton au début de la session d'un utilisateur et le révoquer à la fin de la session de l'utilisateur.

Pour révoquer un jeton, utilisez la commande suivante dans chaque bibliothèque cliente:

AuthSubUtil.revokeToken(sessionToken, null);

AuthSubUtil.revokeToken(sessionToken, privateKey);

AuthSubUtil.revokeToken(sessionToken, null);

AuthSubUtil.revokeToken(sessionToken, privateKey);

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken);

$wasRevoked = Zend_Gdata_AuthSub::AuthSubRevokeToken($sessionToken, $client);

calendar_service.RevokeAuthSubToken()

Ressources et exemples supplémentaires

• Exemples AuthSub sur le blog Conseils de l'API Google Data
• Exemple AuthSub de la bibliothèque cliente Python
• Exemple AuthSub de la bibliothèque cliente Java
• Article Utiliser AuthSub avec la bibliothèque cliente .NET
• Article Utiliser l'authentification "AuthSub" avec la bibliothèque cliente JavaScript

Haut de page

Générer une clé privée à signature automatique et un certificat public à utiliser avec AuthSub sécurisé

La clé privée est utilisée pour générer une signature, qui doit être incluse à chaque requête. Google utilise la clé publique intégrée au certificat pour valider la signature. La clé publique doit être une clé RSA de 1 024 bits encodée dans un certificat X.509 au format PEM. Le certificat doit être envoyé à Google au moment de l'enregistrement.

Les sections suivantes fournissent des exemples de génération de clés et de certificats à l'aide de deux outils spécifiques: l'utilitaire OpenSSL et l'utilitaire Java de keytool.

Ces exemples ne sont pas spécifiques aux API Google Data. Vous pouvez utiliser les mêmes utilitaires pour générer des clés, quel que soit votre objectif.

Pour les exemples suivants, nous partons du principe que votre entreprise s'appelle "Mon_Entreprise" et qu'elle se trouve à Mountain View, en Californie (États-Unis), avec le nom de domaine example.com.

Générer des clés avec OpenSSL

Pour créer une paire de clés RSA et le certificat correspondant, vous pouvez utiliser la commande suivante:

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

Avertissement: L'inclusion du paramètre -nodes crée une clé privée sans mot de passe. Toutefois, pour plus de sécurité, nous vous conseillons d'omettre ce paramètre.

Le paramètre -sha1 indique que la clé sera utilisée pour générer des signatures SHA1.

Le paramètre -subj spécifie l'identité de l'application que le certificat représente.

Le paramètre -keyout spécifie le fichier qui contiendra les clés. Ce fichier contient des informations sensibles. Il doit être protégé et ne doit être partagé avec personne.

Le paramètre -out spécifie le fichier qui contiendra le certificat au format PEM (qui peut être envoyé à Google lors de l'enregistrement).

Générer des clés pour le client .NET

Le framework .NET ne comprend pas les clés ni les certificats stockés au format PEM. Une étape supplémentaire est donc nécessaire une fois le fichier .pem créé :

openssl pkcs12 -export -in test_cert.pem -inkey myrsacert.pem -out myrsacert.pfx -name "Testing Certificate"

Cette étape génère un fichier PFX à partir de votre clé privée et de votre certificat. Ce fichier peut être importé dans la bibliothèque cliente .NET pour signer numériquement les requêtes adressées aux API Google Data.

Générer des clés pour le client Java

Le client Java accepte les clés privées au format PKCS#8. Après avoir généré une clé/un certificat en suivant les instructions ci-dessus, créez un fichier .pk8 à partir du fichier .pem généré:

openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8

Vous pouvez également utiliser le magasin de clés Java et l'utilitaire keytool pour créer une paire de clés RSA et le certificat correspondant. Exécutez la commande ci-dessous :

# Generate the RSA keys and certificate
keytool -genkey -v -alias Example -keystore ./Example.jks\
  -keyalg RSA -sigalg SHA1withRSA\
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

Avertissement : "changeme" n'est pas un bon mot de passe. Il s'agit d'un exemple.

Le paramètre -dname spécifie l'identité de l'application que le certificat représente. Le paramètre -storepass spécifie le mot de passe pour protéger le keystore. Le paramètre -keypass spécifie le mot de passe destiné à protéger la clé privée.

Pour écrire le certificat dans un fichier pouvant être utilisé dans l'outil ManageDomains, utilisez la commande suivante:

# Output the public certificate to a file
keytool -export -rfc -keystore ./Example.jks -storepass changeme \
  -alias Example -file mycert.pem

Haut de page