OAuth 2.0

In questo documento viene descritto OAuth 2.0, quando utilizzarlo, come acquisire ID client e come utilizzarlo con la libreria client delle API di Google per .NET.

Protocollo OAuth 2.0

OAuth 2.0 è il protocollo di autorizzazione utilizzato dalle API di Google. Dovresti acquisire familiarità con il protocollo leggendo i seguenti link:

• Protocollo di autorizzazione OAuth 2.0
• Utilizzare OAuth 2.0 per accedere alle API di Google

Acquisizione di ID client e secret

Puoi recuperare gli ID client e i secret nella Console API di Google. Esistono diversi tipi di ID client, quindi assicurati di ottenere il tipo corretto per la tua applicazione:

• ID client di applicazioni web
• ID client dell'applicazione installata
• ID client dell'account di servizio

Devi scaricare il secret del client e archiviarlo come client_secrets.json nel progetto in ogni snippet di codice riportato di seguito (tranne l'account di servizio).

Credenziali

Credenziali utente

UserCredential è una classe helper sicura per i thread che utilizza un token di accesso per accedere alle risorse protette. Un token di accesso scade in genere dopo un'ora, dopodiché verrà visualizzato un errore se tenti di utilizzarlo.

UserCredential e AuthorizationCodeFlow si occupano dell'"aggiornamento" automatico del token, il che significa semplicemente ottenere un nuovo token di accesso. Questa operazione viene eseguita utilizzando un token di aggiornamento di lunga durata, che ricevi insieme al token di accesso se utilizzi il parametro access_type=offline durante il flusso del codice di autorizzazione.

Nella maggior parte delle applicazioni, è consigliabile archiviare il token di accesso e il token di aggiornamento delle credenziali in uno spazio di archiviazione permanente. In caso contrario, dovrai mostrare all'utente finale una pagina di autorizzazione nel browser ogni ora, perché il token di accesso scade un'ora dopo che l'hai ricevuto.

Per assicurarti che i token di accesso e di aggiornamento permanano, puoi fornire la tua implementazione di IDataStore oppure utilizzare una delle seguenti implementazioni fornite dalla libreria:

• FileDataStore per .NET assicura che la credenziale sia permanente in un file.

ServiceAccountCredential

ServiceAccountCredential è simile a UserCredential, ma ha una finalità diversa. Google OAuth 2.0 supporta le interazioni server-server, come quelle tra un'applicazione web e Google Cloud Storage. L'applicazione richiedente deve dimostrare la propria identità per ottenere l'accesso a un'API e l'utente finale non deve essere coinvolto. ServiceAccountCredential archivia una chiave privata, che viene utilizzata per firmare una richiesta per ricevere un nuovo token di accesso.

Sia UserCredential che ServiceAccountCredential implementano IConfigurableHttpClientInitializer quindi puoi registrare ciascuno di questi dati come:

• Un gestore di risposte non riuscite, che aggiornerà il token se riceve un codice di stato HTTP 401.
• Un intercettatore, per intercettare l'intestazione Authorization in ogni richiesta.

Applicazioni installate

Esempio di codice tramite l'API Libri:

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();
            ...
        }
    }
}
  

• In questo codice di esempio viene creata una nuova istanza UserCredential chiamando il metodo GoogleWebAuthorizationBroker.AuthorizeAsync. Questo metodo statico ottiene quanto segue:

  • Il client secret (o uno stream per il client secret).
  • Gli ambiti obbligatori.
  • L'identificatore utente.
  • Il token di annullamento per annullare un'operazione.
  • Un datastore facoltativo. Se il datastore non è specificato, il valore predefinito è un FileDataStore con una cartella Google.Apis.Auth predefinita. La cartella viene creata in Environment.SpecialFolder.ApplicationData.

• L'elemento UserCredential restituito da questo metodo è impostato come HttpClientInitializer su BooksService (utilizzando l'inizializzatore). Come spiegato in precedenza, UserCredential implementa un inizializzatore client HTTP.

• Tieni presente che nel codice campione sopra riportato vengono caricate le informazioni del client secret da un file, ma puoi anche:

  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"));
        

Dai un'occhiata all'esempio di Libri.

Applicazioni web (ASP.NET Core 3)

Le API di Google supportano OAuth 2.0 per le applicazioni server web.

Google.Apis.Auth.AspNetCore3 è la libreria consigliata da utilizzare per la maggior parte degli scenari OAuth 2.0 basati su Google nelle applicazioni ASP.NET Core 3. Implementa un gestore di autenticazione OpenIdConnect specifico di Google. Supporta l'autenticazione incrementale e definisce un IGoogleAuthProvider iniettabile per fornire le credenziali Google che possono essere utilizzate con le API di Google.

Questa sezione descrive come configurare e utilizzare Google.Apis.Auth.AspNetCore3. Il codice mostrato qui si basa su Google.Apis.Auth.AspNetCore3.IntegrationTests, un'applicazione ASP.NET Core 3 standard completamente funzionante.

Se vuoi seguire questa documentazione come tutorial, avrai bisogno della tua applicazione ASP.NET Core 3 e di completare questi passaggi come prerequisito.

Prerequisiti

• Installa il pacchetto Google.Apis.Auth.AspNetCore3.
• Stiamo utilizzando l'API Google Drive, quindi devi anche installare il pacchetto Google.Apis.Drive.v3.
• Se non ne hai già uno, crea un progetto Google Cloud. A tale scopo, segui queste istruzioni. Questo sarà il progetto con cui viene identificata la tua app.
• Assicurati di attivare l'API Google Drive. Per abilitare le API, segui queste istruzioni.
• Crea credenziali di autorizzazione che identifichino la tua app su Google. Segui queste istruzioni per creare le credenziali di autorizzazione e scaricare il file client_secrets.json. Due caratteristiche principali:
  • Nota che il tipo di credenziali deve essere Applicazione web.
  • Per eseguire questa app, l'unico URI di reindirizzamento che devi aggiungere è https://localhost:5001/signin-oidc.

Configura la tua applicazione per l'utilizzo di Google.Apis.Auth.AspNetCore3

Google.Apis.Auth.AspNetCore3 è configurato nella classe Startup o in un'alternativa simile che potresti utilizzare. I seguenti snippet vengono estratti da Startup.cs nel progetto Google.Apis.Auth.AspNetCore3.IntegrationTests.

• Aggiungi quanto segue utilizzando l'istruzione al file Startup.cs.

  using Google.Apis.Auth.AspNetCore3;

• Nel metodo Startup.ConfigureServices aggiungi il codice seguente, modifica l'ID client e i segnaposto Client Secret con i valori contenuti nel file client_secrets.json. Puoi caricare questi valori direttamente dal file JSON oppure puoi archiviarli in qualsiasi altro modo sicuro. Dai un'occhiata al metodo ClientInfo.Load nel progetto Google.Apis.Auth.AspNetCore3.IntegrationTests per un esempio di come caricare questi valori direttamente dal file 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};
          });
  }
        

• Nel metodo Startup.Configure, assicurati di aggiungere alla pipeline i componenti middleware di autenticazione e autorizzazione di ASP.NET Core 3, nonché i reindirizzamenti HTTPS:

  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  {
      ...
      app.UseHttpsRedirection();
      ...
  
      app.UseAuthentication();
      app.UseAuthorization();
  
      ...
  }