OAuth 2.0

Ce document décrit le protocole OAuth 2.0, quand l’utiliser, comment acquérir des ID client, et comment l'utiliser avec la bibliothèque cliente des API Google pour .NET.

Protocole OAuth 2.0

OAuth 2.0 est le protocole d'autorisation utilisé par les API Google. Pour vous familiariser avec le protocole, consultez les liens suivants:

Acquérir des ID client et des secrets

Vous pouvez obtenir les ID client et les codes secrets dans la console Google APIs. Il existe différents types d'identifiants client, Veillez donc à obtenir le type approprié pour votre application:

<ph type="x-smartling-placeholder">

Dans chacun des extraits de code ci-dessous (à l'exception de celui du compte de service), vous devez télécharger le fichier code secret du client et stockez-le en tant que client_secrets.json dans votre projet.

<ph type="x-smartling-placeholder">

Identifiants

Identifiants utilisateur

UserCredential est une classe d'assistance thread-safe qui permet d'utiliser un jeton d'accès pour accéder à des ressources protégées. Un jeton d'accès expire généralement après une heure, vous obtiendrez une erreur si vous essayez de l'utiliser.

UserCredential et AuthorizationCodeFlow se charge de l'actualisation automatique le jeton, c'est-à-dire obtenir un nouveau jeton d'accès. Pour ce faire, vous devez utiliser un jeton d'actualisation de longue durée, que vous recevez en même temps que le si vous utilisez access_type=offline pendant le flux de code d'autorisation.

Dans la plupart des applications, il est conseillé de stocker le le jeton d'accès de l'identifiant et le jeton d'actualisation dans le stockage persistant. Sinon, vous devrez présenter à l'utilisateur final dans le navigateur toutes les heures, car l'accès Le jeton expire une heure après sa réception.

Pour vous assurer que les jetons d'accès et d'actualisation sont conservés, vous pouvez fournir votre propre implémentation IDataStore, Vous pouvez également utiliser l'une des implémentations suivantes fournies par la bibliothèque:

  • FileDataStore pour .NET garantit que les identifiants seront persistants dans un fichier.

ServiceAccountCredential

ServiceAccountCredential est semblable à UserCredential, mais dans un autre but. Google OAuth 2.0 prend en charge les interactions de serveur à serveur, telles que celles entre une application Web et Google Cloud Storage. L'application à l'origine de la demande doit prouver sa propre identité pour pouvoir accéder à une API, sans impliquer l'utilisateur final. ServiceAccountCredential stocke une clé privée qui permet de signer une requête pour obtenir un nouveau jeton d'accès.

UserCredential et ServiceAccountCredential implémentent tous deux IConfigurableHttpClientInitializer Vous pouvez donc enregistrer chacun d'eux comme suit:

  • Si un gestionnaire de réponses échoue, Il actualisera donc le jeton s'il reçoit un code d'état HTTP 401.
  • Un intercepteur pour intercepter Authorization à chaque requête.

Applications installées

Exemple de code à l'aide de l'API Livres: 

using System;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Books.v1;
using Google.Apis.Books.v1.Data;
using Google.Apis.Services;
using Google.Apis.Util.Store;

namespace Books.ListMyLibrary
{
    /// <summary>
    /// Sample which demonstrates how to use the Books API.
    /// https://developers.google.com/books/docs/v1/getting_started
    /// <summary>
    internal class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Books API Sample: List MyLibrary");
            Console.WriteLine("================================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            UserCredential credential;
            using (var stream = new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read))
            {
                credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
                    GoogleClientSecrets.Load(stream).Secrets,
                    new[] { BooksService.Scope.Books },
                    "user", CancellationToken.None, new FileDataStore("Books.ListMyLibrary"));
            }

            // Create the service.
            var service = new BooksService(new BaseClientService.Initializer()
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Books API Sample",
                });

            var bookshelves = await service.Mylibrary.Bookshelves.List().ExecuteAsync();
            ...
        }
    }
}

  • Dans cet exemple de code, une instance UserCredential est créée en appelant la méthode GoogleWebAuthorizationBroker.AuthorizeAsync. Cette méthode statique permet d'obtenir les éléments suivants:

    • Le code secret du client (ou un flux vers le code secret du client).
    • Champs d'application requis.
    • Identifiant utilisateur.
    • Jeton d'annulation d'une opération.
    • Un data store facultatif. Si le data store n'est pas spécifié, la valeur par défaut est FileDataStore. avec un dossier Google.Apis.Auth par défaut. Le dossier est créé dans Environment.SpecialFolder.ApplicationData.

  • L'élément UserCredential renvoyé par cette méthode est défini en tant que HttpClientInitializer. sur BooksService (à l'aide de l'initialiseur). Comme expliqué ci-dessus, UserCredential implémente une Initialiseur de client HTTP.

  • Notez que dans l'exemple de code ci-dessus, les informations du code secret du client sont chargées à partir d'un fichier, mais vous pouvez aussi effectuer les opérations suivantes: 

    credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
    new ClientSecrets
    {
        ClientId = "PUT_CLIENT_ID_HERE",
        ClientSecret = "PUT_CLIENT_SECRETS_HERE"
    },
    new[] { BooksService.Scope.Books },
    "user",
    CancellationToken.None,
    new FileDataStore("Books.ListMyLibrary"));

Consultez notre extrait Google Livres.

Applications Web (ASP.NET Core 3)

Assistance pour les API Google <ph type="x-smartling-placeholder"></ph> OAuth 2.0 pour les applications de serveur Web

Le Google.Apis.Auth.AspNetCore3 est la bibliothèque recommandée pour la plupart des bibliothèques basées Scénarios OAuth 2.0 dans les applications ASP.NET Core 3 Il implémente une configuration spécifique à Gestionnaire d'authentification OpenIdConnect. Il prend en charge l'authentification incrémentielle et définit un système IGoogleAuthProvider pour fournir les identifiants Google pouvant être utilisés avec les API Google.

Cette section explique comment configurer et utiliser Google.Apis.Auth.AspNetCore3. Le code affiché est basé sur <ph type="x-smartling-placeholder"></ph> Google.Apis.Auth.AspNetCore3.IntegrationTests, qui est un ASP.NET standard entièrement fonctionnel Application Core 3.

Si vous souhaitez suivre cette documentation sous forme de tutoriel, vous aurez besoin de votre propre fichier ASP.NET votre application Core 3 et d'effectuer ces étapes au préalable.

Prérequis

  • Installez la <ph type="x-smartling-placeholder"></ph> Google.Apis.Auth.AspNetCore3.
  • Nous utilisons l'API Google Drive. Vous allez donc vous devrez également installer Google.Apis.Drive.v3 d'un package.
  • Créez un projet Google Cloud si vous n'en avez pas déjà un. Suivre <ph type="x-smartling-placeholder"></ph> suivez ces instructions. Il s'agit du projet avec lequel votre application est identifiée.
  • Veillez à activer l'API Google Drive. Pour activer les API, procédez comme suit : <ph type="x-smartling-placeholder"></ph> suivez ces instructions.
  • Créez des identifiants d'autorisation qui permettront d'identifier votre application auprès de Google. Suivre <ph type="x-smartling-placeholder"></ph> suivez ces instructions pour créer des identifiants d'autorisation et télécharger client_secrets.json. Deux points forts: <ph type="x-smartling-placeholder">
      </ph>
    • Notez que les identifiants doit être de type Web application (Application Web).
    • Pour exécuter cette application, le seul URI de redirection que vous devez ajouter est https://localhost:5001/signin-oidc

Configurer votre application pour qu'elle utilise Google.Apis.Auth.AspNetCore3

Google.Apis.Auth.AspNetCore3 est configuré dans la classe Startup ou une classe similaire que vous pourriez utiliser. Les extraits suivants sont extraits de <ph type="x-smartling-placeholder"></ph> Startup.cs dans le projet Google.Apis.Auth.AspNetCore3.IntegrationTests.

  • Ajoutez la directive d'utilisation suivante à votre fichier Startup.cs. 
    using Google.Apis.Auth.AspNetCore3;
  • Dans la méthode Startup.ConfigureServices, ajoutez le code suivant et modifiez Les espaces réservés correspondant au numéro et au code secret du client avec les valeurs contenues dans le client_secrets.json. Vous pouvez charger ces valeurs directement à partir du fichier JSON ou vous pouvez les stocker de toute autre manière sécurisée. Consultez le <ph type="x-smartling-placeholder"></ph> ClientInfo.Load dans Google.Apis.Auth.AspNetCore3.IntegrationTests pour obtenir un exemple de chargement de ces valeurs directement à partir du fichier JSON. 
    public void ConfigureServices(IServiceCollection services)
{
    ...

    // This configures Google.Apis.Auth.AspNetCore3 for use in this app.
    services
        .AddAuthentication(o =>
        {
            // This forces challenge results to be handled by Google OpenID Handler, so there's no
            // need to add an AccountController that emits challenges for Login.
            o.DefaultChallengeScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
            // This forces forbid results to be handled by Google OpenID Handler, which checks if
            // extra scopes are required and does automatic incremental auth.
            o.DefaultForbidScheme = GoogleOpenIdConnectDefaults.AuthenticationScheme;
            // Default scheme that will handle everything else.
            // Once a user is authenticated, the OAuth2 token info is stored in cookies.
            o.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        })
        .AddCookie()
        .AddGoogleOpenIdConnect(options =>
        {
            options.ClientId = {YOUR_CLIENT_ID};
            options.ClientSecret = {YOUR_CLIENT_SECRET};
        });
}
  • Dans la méthode Startup.Configure, veillez à ajouter l'authentification ASP.NET Core 3. et des composants middleware d'autorisation au pipeline, ainsi que les redirections HTTPS: 
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

    app.UseAuthentication();
    app.UseAuthorization();

    ...
}
    <ph type="x-smartling-placeholder">

Utiliser les identifiants de l'utilisateur pour accéder aux API Google en son nom

Vous êtes maintenant prêt à ajouter à vos manettes des méthodes d'action qui nécessitent des identifiants utilisateur pour d'accéder aux API Google en leur nom. L'extrait de code suivant montre comment répertorier les fichiers du le compte Google Drive de l'utilisateur authentifié. Notez deux choses principalement:

  • L'utilisateur doit non seulement être authentifié, mais aussi avoir accordé l'autorisation https://www.googleapis.com/auth/drive.readonly à votre application, ce qui que vous spécifiez via l'attribut GoogleScopedAuthorize.
  • Nous utilisons le mécanisme standard d'injection de dépendances d'ASP.NET Core 3 pour recevoir une IGoogleAuthProvider que nous utilisons pour obtenir les identifiants de l'utilisateur.

Le code:

  • Commencez par ajouter les directives d'utilisation suivantes à votre contrôleur. 
    using Google.Apis.Auth.AspNetCore3;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;
  • Ajoutez l'action de la manette, comme suit (et accompagnez-la d'une simple vue qui reçoit un modèle IList<string>): 
    /// <summary>
/// Lists the authenticated user's Google Drive files.
/// Specifying the <see cref="GoogleScopedAuthorizeAttribute"> will guarantee that the code
/// executes only if the user is authenticated and has granted the scope specified in the attribute
/// to this application.
/// </summary>
/// <param name="auth">The Google authorization provider.
/// This can also be injected on the controller constructor.</param>
[GoogleScopedAuthorize(DriveService.ScopeConstants.DriveReadonly)]
public async Task<IActionResult> DriveFileList([FromServices] IGoogleAuthProvider auth)
{
    GoogleCredential cred = await auth.GetCredentialAsync();
    var service = new DriveService(new BaseClientService.Initializer
    {
        HttpClientInitializer = cred
    });
    var files = await service.Files.List().ExecuteAsync();
    var fileNames = files.Files.Select(x => x.Name).ToList();
    return View(fileNames);
}

Et voici les bases. Vous pouvez consulter <ph type="x-smartling-placeholder"></ph> HomeController.cs du projet Google.Apis.Auth.AspNetCore3.IntegrationTests pour découvrir comment:

  • Authentification des utilisateurs uniquement, sans champ d'application spécifique
  • Fonctionnalité de déconnexion
  • Autorisation incrémentielle via le code. Notez que l'extrait ci-dessus indique via des attributs.
  • Examiner les niveaux d'accès actuellement accordés
  • Examiner les jetons d'accès et d'actualisation
  • Forcez l'actualisation du jeton d'accès. Notez que vous n'avez pas à le faire vous-même, car Google.Apis.Auth.AspNetCore3 détectera si le jeton d'accès a expiré ou est sur le point d'expirer et l'actualisera automatiquement.

Compte de service

Les API Google sont également compatibles Comptes de service : Contrairement au scénario dans lequel une application cliente demande l'accès aux données d'un utilisateur final, les comptes de service permettent d'accéder aux données de l'application cliente.

Votre application cliente signe la demande de jeton d'accès à l'aide d'une clé privée téléchargée. depuis la console Google APIs. Après avoir créé un ID client, vous devez choisir un "Compte de service" type d'application, puis vous pouvez télécharger la clé privée. Consultez notre <ph type="x-smartling-placeholder"></ph> exemple de compte de service avec l'API Google Plus. 

using System;
using System.Security.Cryptography.X509Certificates;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Plus.v1;
using Google.Apis.Plus.v1.Data;
using Google.Apis.Services;

namespace Google.Apis.Samples.PlusServiceAccount
{
    /// <summary>
    /// This sample demonstrates the simplest use case for a Service Account service.
    /// The certificate needs to be downloaded from the Google API Console
    /// <see cref="https://console.cloud.google.com/">
    ///   "Create another client ID..." -> "Service Account" -> Download the certificate,
    ///   rename it as "key.p12" and add it to the project. Don't forget to change the Build action
    ///   to "Content" and the Copy to Output Directory to "Copy if newer".
    /// </summary>
    public class Program
    {
        // A known public activity.
        private static String ACTIVITY_ID = "z12gtjhq3qn2xxl2o224exwiqruvtda0i";

        public static void Main(string[] args)
        {
            Console.WriteLine("Plus API - Service Account");
            Console.WriteLine("==========================");

            String serviceAccountEmail = "SERVICE_ACCOUNT_EMAIL_HERE";

            var certificate = new X509Certificate2(@"key.p12", "notasecret", X509KeyStorageFlags.Exportable);

            ServiceAccountCredential credential = new ServiceAccountCredential(
               new ServiceAccountCredential.Initializer(serviceAccountEmail)
               {
                   Scopes = new[] { PlusService.Scope.PlusMe }
               }.FromCertificate(certificate));

            // Create the service.
            var service = new PlusService(new BaseClientService.Initializer()
            {
                HttpClientInitializer = credential,
                ApplicationName = "Plus API Sample",
            });

            Activity activity = service.Activities.Get(ACTIVITY_ID).Execute();
            Console.WriteLine("  Activity: " + activity.Object.Content);
            Console.WriteLine("  Video: " + activity.Object.Attachments[0].Url);

            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }
    }
}

L'exemple de code ci-dessus crée ServiceAccountCredential Les champs d'application requis sont définis, et un appel à FromCertificate est effectué. qui charge la clé privée à partir du X509Certificate2 donné. Comme dans tous les autres exemples de code, l'identifiant est défini sur HttpClientInitializer.