OAuth 2.0

En este documento, se describe OAuth 2.0, cuándo usarlo, cómo adquirir IDs de cliente y cómo usarlo con la biblioteca cliente de la API de Google para .NET.

Protocolo OAuth 2.0

OAuth 2.0 es el protocolo de autorización que usan las APIs de Google. Para familiarizarte con el protocolo, lee los siguientes vínculos:

Adquiere IDs de cliente y secretos

Puedes obtener IDs de cliente y secretos en la Consola de API de Google. Existen diferentes tipos de IDs de cliente, así que asegúrate de obtener el correcto para tu aplicación:

En cada uno de los fragmentos de código que se muestran (excepto el de la cuenta de servicio), debes descargar el secreto cliente y almacenarlo como client_secrets.json en tu proyecto.

Credenciales

Credenciales de usuario

UserCredential es una clase de ayuda segura para subprocesos para usar un token de acceso y acceder a recursos protegidos. Por lo general, un token de acceso caduca después de 1 hora, tras la cual recibirás un error si intentas usarlo.

UserCredential y AuthorizationCodeFlow se encargan de “actualizar” el token automáticamente, lo que significa obtener un token de acceso nuevo. Esto se hace con un token de actualización de larga duración, que recibes junto con el token de acceso si usas el parámetro access_type=offline durante el flujo de código de autorización.

En la mayoría de las aplicaciones, se recomienda almacenar el token de acceso y el token de actualización de la credencial en el almacenamiento persistente. De lo contrario, deberás presentarle al usuario final una página de autorización en el navegador cada hora, ya que el token de acceso vence una hora después de que lo recibes.

Para asegurarte de que los tokens de acceso y actualización persistan, puedes proporcionar tu propia implementación de IDataStore o usar una de las siguientes implementaciones que proporciona la biblioteca:

  • FileDataStore para .NET garantiza que la credencial sea persistente en un archivo.

ServiceAccountCredential

ServiceAccountCredential es similar a UserCredential, pero tiene un propósito diferente. OAuth 2.0 de Google admite interacciones de servidor a servidor, como las que se establecen entre una aplicación web y Google Cloud Storage. La aplicación solicitante debe probar su propia identidad para obtener acceso a una API, y no es necesario que un usuario final esté involucrado. ServiceAccountCredential almacena una clave privada, que se usa para firmar una solicitud y obtener un nuevo token de acceso.

Tanto UserCredential como ServiceAccountCredential implementan IConfigurableHttpClientInitializer, por lo que puedes registrar cada uno de ellos de la siguiente manera:

  • Un controlador de respuesta que no se realizó correctamente, por lo que actualizará el token si recibe un código de estado HTTP 401.
  • Un interceptor para interceptar el encabezado Authorization en cada solicitud

Aplicaciones instaladas

Código de muestra que usa la API de Books: 

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

  • En este código de muestra, se crea una nueva instancia de UserCredential llamando al método GoogleWebAuthorizationBroker.AuthorizeAsync. Este método estático obtiene lo siguiente:

    • El secreto del cliente (o una transmisión al secreto del cliente)
    • Los permisos obligatorios
    • El identificador de usuario.
    • Es el token de cancelación para cancelar una operación.
    • Un almacén de datos opcional. Si no se especifica el almacén de datos, el valor predeterminado es un FileDataStore con una carpeta Google.Apis.Auth predeterminada. La carpeta se crea en Environment.SpecialFolder.ApplicationData.

  • El UserCredential que muestra este método se establece como un HttpClientInitializer en BooksService (con el inicializador). Como se explicó anteriormente, UserCredential implementa un inicializador de cliente HTTP.

  • Ten en cuenta que, en el código de muestra, la información del secreto del cliente se carga desde un archivo, pero también puedes hacer lo siguiente: 

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

Consulta nuestro ejemplo de libros.

Aplicaciones web (ASP.NET Core 3)

Las APIs de Google admiten OAuth 2.0 para aplicaciones de servidor web.

Google.Apis.Auth.AspNetCore3 es la biblioteca recomendada para usar en la mayoría de las situaciones de OAuth 2.0 basadas en Google en aplicaciones de ASP.NET Core 3. Implementa un controlador de autenticación OpenIdConnect específico de Google. Admite la autenticación incremental y define un IGoogleAuthProvider inyectable para proporcionar credenciales de Google que se pueden usar con las APIs de Google.

En esta sección, se describe cómo configurar y usar Google.Apis.Auth.AspNetCore3. El código que se muestra aquí se basa en Google.Apis.Auth.AspNetCore3.IntegrationTests, que es una aplicación estándar de ASP.NET Core 3 que funciona completamente.

Si quieres seguir esta documentación como instructivo, necesitarás tu propia aplicación de ASP.NET Core 3 y completar estos pasos como requisito previo.

Requisitos previos

  • Instala el paquete Google.Apis.Auth.AspNetCore3.
  • Usamos la API de Google Drive, por lo que también deberás instalar el paquete Google.Apis.Drive.v3.
  • Crea un proyecto de Google Cloud si aún no tienes uno. Para ello, sigue estas instrucciones. Este será el proyecto con el que se identificará tu app.
  • Asegúrate de habilitar la API de Google Drive. Para habilitar las APIs, sigue estas instrucciones.
  • Crea credenciales de autorización que identifiquen tu app para Google. Sigue estas instrucciones para crear credenciales de autorización y descargar el client_secrets.json archivo. Dos aspectos destacados:
    • Ten en cuenta que el tipo de credenciales debe ser Aplicación web.
    • Para ejecutar esta app, el único URI de redireccionamiento que debes agregar es https://localhost:5001/signin-oidc.

Configura tu aplicación para usar Google.Apis.Auth.AspNetCore3

Google.Apis.Auth.AspNetCore3 se configura en la clase Startup o en una alternativa similar que puedas estar usando. Los siguientes fragmentos se extraen de Startup.cs en el proyecto Google.Apis.Auth.AspNetCore3.IntegrationTests.

  • Agrega la siguiente directiva using a tu archivo Startup.cs. 
    using Google.Apis.Auth.AspNetCore3;
  • En el método Startup.ConfigureServices, agrega el siguiente código y cambia los marcadores de posición del ID de cliente y el secreto de cliente por los valores que se encuentran en el archivo client_secrets.json. Puedes cargar estos valores directamente desde el archivo JSON o almacenarlos de cualquier otra manera segura. Consulta el método ClientInfo.Load en el proyecto Google.Apis.Auth.AspNetCore3.IntegrationTests para ver un ejemplo de cómo cargar estos valores directamente desde el archivo 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};
        });
}
  • En el método Startup.Configure, asegúrate de agregar los componentes de middleware de autenticación y autorización de ASP.NET Core 3 a la canalización, así como los redireccionamientos de HTTPS: 
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...
    app.UseHttpsRedirection();
    ...

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

    ...
}

Usar la credencial del usuario para acceder a las APIs de Google en su nombre

Ya puedes agregar métodos de acción a tus controladores que requieran la credencial del usuario para acceder a las APIs de Google en su nombre. En el siguiente fragmento, se muestra cómo mostrar una lista de los archivos de la cuenta de Google Drive del usuario autenticado. Ten en cuenta dos aspectos principales:

  • El usuario no solo debe estar autenticado, sino que también debe haber otorgado el permiso https://www.googleapis.com/auth/drive.readonly a tu aplicación, que especificas con el atributo GoogleScopedAuthorize.
  • Usamos el mecanismo de inserción de dependencias estándar de ASP.NET Core 3 para recibir un IGoogleAuthProvider que usamos para obtener las credenciales del usuario.

El código:

  • Primero, agrega las siguientes directivas de uso a tu controlador. 
    using Google.Apis.Auth.AspNetCore3;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;
  • Agrega la acción del controlador de la siguiente manera (y acompáñala con una vista que reciba un modelo 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);
}

Y estos son los conceptos básicos. Puedes consultar HomeController.cs en el proyecto Google.Apis.Auth.AspNetCore3.IntegrationTests para descubrir cómo puedes lograr lo siguiente:

  • Solo autenticación de usuarios, sin permisos específicos
  • Salida de usuarios
  • Autorización incremental con código Observa que la muestra muestra la autorización incremental con atributos.
  • Examina los permisos otorgados
  • Examina los tokens de acceso y actualización
  • Fuerza la actualización del token de acceso. Ten en cuenta que no tienes que hacerlo por tu cuenta, ya que Google.Apis.Auth.AspNetCore3 detectará si el token de acceso venció o está por vencer y lo actualizará automáticamente.

Cuenta de servicio

Las APIs de Google también admiten cuentas de servicio. A diferencia de la situación en la que una aplicación cliente solicita acceso a los datos de un usuario final, las cuentas de servicio proporcionan acceso a los datos de la propia aplicación cliente.

Tu aplicación cliente firma la solicitud de un token de acceso con una clave privada descargada de la Consola de API de Google. Después de crear un ID de cliente nuevo, debes elegir un tipo de aplicación de cuenta de servicio y, luego, puedes descargar la clave privada. Consulta nuestra muestra de cuenta de servicio con la API de 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();
        }
    }
}

En este ejemplo, se crea un ServiceAccountCredential. Se establecen los permisos necesarios y se realiza una llamada a FromCertificate, que carga la clave privada desde el X509Certificate2 determinado. Al igual que en todos los demás códigos de muestra, la credencial se establece como HttpClientInitializer.