Compartir vía


Aplicación web que llama a las API web: Configuración del código

En el artículo anterior, has registrado una aplicación en Microsoft Entra. Este artículo te mostrará cómo configurar el código de aplicación y a modificar la aplicación web para que no solo inicie la sesión de los usuarios, sino que también llame a las API web. La aplicación que crees usa el flujo de código de autorización OAuth 2.0 para iniciar la sesión del usuario. Este flujo tiene dos pasos:

  1. Solicitud de un código de autorización. Esta parte delega a la Plataforma de identidad de Microsoft un diálogo privado con el usuario. Durante ese diálogo, el usuario inicia sesión y da su consentimiento al uso de las API web. Cuando este diálogo privado finaliza correctamente, la aplicación web recibe un código de autorización en el URI de redirección.
  2. Solicite un token de acceso para la API mediante el canje del código de autorización.

Requisitos previos

Bibliotecas de Microsoft que admiten aplicaciones web

Las bibliotecas de Microsoft siguientes admiten aplicaciones web:

Lenguaje/marco de trabajo Proyecto en
GitHub
Paquete Introducción
iniciado
Inicio de sesión de usuarios Acceso a API web Disponible con carácter general (GA) o
Versión preliminar pública1
.NET MSAL.NET Microsoft.Identity.Client La biblioteca no puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
.NET Microsoft.IdentityModel Microsoft.IdentityModel Library cannot request ID tokens for user sign-in.2 Library cannot request access tokens for protected web APIs.2 GA
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web Guía de inicio rápido La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
Java MSAL4J msal4j Guía de inicio rápido La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory Tutorial La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
Node.js MSAL Node msal-node Guía de inicio rápido La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
Python MSAL Python msal La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. GA
Python identity identity Guía de inicio rápido La biblioteca puede solicitar tokens de id. para el inicio de sesión de usuario. La biblioteca puede solicitar tokens de acceso para las API web protegidas. --

(1) Los términos de licencia universal de Online Services se aplican a las bibliotecas que están en versión preliminar pública.

(2) La biblioteca Microsoft.IdentityModel solo valida los tokens, no puede solicitar tokens de id. ni de acceso.

Seleccione la pestaña correspondiente a la plataforma que le interese:

Secretos de cliente o certificados de cliente

Dado que la aplicación web ahora llama a una API web de nivel inferior, proporciona un secreto de cliente o un certificado de cliente en el archivo appsettings.json. También puedes agregar una sección que especifique:

  • La dirección URL de la API web de nivel inferior.
  • Los ámbitos necesarios para llamar a la API.

En el ejemplo siguiente, la sección GraphBeta especifica esta configuración.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Nota

Puedes proponer una colección de credenciales de cliente, incluida una solución sin credenciales, como la federación de identidades de carga de trabajo para Azure Kubernetes. Las versiones anteriores de Microsoft.Identity.Web expresaron el secreto de cliente en una sola propiedad "ClientSecret" en lugar de "ClientCredentials". Esto sigue siendo compatible con versiones anteriores, pero no puedes usar la propiedad "ClientSecret" y la colección "ClientCredentials".

En lugar de un secreto de cliente, puedes proporcionar un certificado de cliente. En el fragmento de código siguiente se muestra el uso de un certificado almacenado en Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Advertencia

Si olvidas cambiar Scopes a una matriz, cuando intentes usar IDownstreamApi los ámbitos aparecerán como nulos, y IDownstreamApi intentará una llamada anónima (sin autenticar) a la API descendente, lo cual resultará en un 401/unauthenticated.

Microsoft.Identity.Web proporciona varias maneras de describir certificados, tanto mediante configuración como mediante código. Para más información, consulta Microsoft.Identity.Web: uso de certificados en GitHub.

Selecciona el archivo Startup.cs.

La aplicación web tiene que adquirir un token para la API de nivel inferior. Para especificarlo, agrega la línea .EnableTokenAcquisitionToCallDownstreamApi() después de .AddMicrosoftIdentityWebApp(Configuration). Esta línea expone el servicio IAuthorizationHeaderProvider, que puedes usar en las acciones del controlador y la página. Sin embargo, como ves en las dos opciones siguientes, se puede hacer de forma más sencilla. También debes elegir una implementación de la caché de tokens, por ejemplo .AddInMemoryTokenCaches(), en Startup.cs:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Los ámbitos que se pasan a EnableTokenAcquisitionToCallDownstreamApi son opcionales y permiten que la aplicación web solicite los ámbitos y el consentimiento del usuario a esos ámbitos cuando inicie sesión. Si no especificas los ámbitos, Microsoft.Identity.Web habilita una experiencia de consentimiento incremental.

Microsoft.Identity.Web ofrece dos mecanismos para llamar a una API web desde una aplicación web sin tener que adquirir un token. La opción que elijas dependerá de si deseas llamar a Microsoft Graph o a otra API.

Opción 1: Llamada a Microsoft Graph

Si deseas llamar a Microsoft Graph, Microsoft.Identity.Web le permite usar directamente GraphServiceClient (expuesto por el SDK de Microsoft Graph) en las acciones de la API. Para exponer Microsoft Graph:

  1. Agrega el paquete NuGet Microsoft.Identity.Web.GraphServiceClient a tu proyecto.

  2. Agrega .AddMicrosoftGraph() después de .EnableTokenAcquisitionToCallDownstreamApi() en el archivo Startup.cs. .AddMicrosoftGraph() tiene varias invalidaciones. Cuando se utiliza la invalidación que toma una sección de la configuración como parámetro, el código se convierte en:

    using Microsoft.Identity.Web;
    
    public class Startup
    {
      // ...
      public void ConfigureServices(IServiceCollection services)
      {
      // ...
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
                   .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
       // ...
      }
      // ...
    }
    

Opción 2: Llamada a una API web de nivel inferior que no sea Microsoft Graph

Si deseas llamar a una API distinta de Microsoft Graph, Microsoft.Identity.Web le permite usar la interfaz IDownstreamApi en sus acciones de API. Para usar esta interfaz:

  1. Agrega el paquete NuGet Microsoft.Identity.Web.DownstreamApi al proyecto.

  2. Agrega .AddDownstreamApi() después de .EnableTokenAcquisitionToCallDownstreamApi() en el archivo Startup.cs. .AddDownstreamApi() tiene dos argumentos y se muestra en el fragmento de código siguiente:

    • Nombre de un servicio (API), que se usa en las acciones del controlador para hacer referencia a la configuración correspondiente
    • una sección de configuración que representa los parámetros usados para llamar a la API web de bajada.
    using Microsoft.Identity.Web;
    
    public class Startup
    {
      // ...
      public void ConfigureServices(IServiceCollection services)
      {
      // ...
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
                   .AddDownstreamApi("MyApi", Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
       // ...
      }
      // ...
    }
    

Resumen

Al igual que con las API web, puedes elegir varias implementaciones de la memoria caché de tokens. Para obtener más información, consulta Microsoft.Identity.Web: serialización de la memoria caché de tokens en GitHub.

En la imagen siguiente se muestran las distintas posibilidades de Microsoft.Identity.Web y su efecto en el archivo Startup.cs:

Diagrama de bloques que muestra las opciones de configuración del servicio en startup punto c s para llamar a una API web y especificar una implementación de la caché de tokens

Nota:

Para comprender por completo los ejemplos de código que se indican a continuación, familiarízate con los aspectos básicos de ASP.NET Core y, en particular, con la inserción de dependencias y las opciones.

El código que canjea el código de autorización.

Microsoft.Identity.Web simplifica el código mediante la definición de la configuración correcta de OpenID Connect, la suscripción al evento recibido del código y el canje del código. No es necesario ningún código adicional para canjear el código de autorización. Vea Código fuente de Microsoft.Identity.Web para obtener información detallada sobre cómo funciona esto.

En lugar de un secreto de cliente, la aplicación cliente confidencial también puede demostrar su identidad mediante un certificado de cliente o una aserción de cliente. El uso de aserciones de cliente es un escenario avanzado, que se detalla en Aserciones de cliente.

Memoria caché de tokens

Importante

La implementación de la caché de tokens para aplicaciones web o API web es distinta a la implementación de las aplicaciones de escritorio, que a menudo están basadas en archivos. Por motivos de seguridad y rendimiento, es importante asegurarse de que, para las aplicaciones web y las API web, haya una caché de tokens por cuenta de usuario. Es preciso serializar la caché de tokens de cada cuenta.

En el tutorial de ASP.NET Core se usa la inserción de dependencias para permitir decidir la implementación de la caché de tokens en el archivo Startup.cs de la aplicación. Microsoft.Identity.Web incluye varios serializadores de caché de tokens pregenerados que se describen en Serialización del almacenamiento en caché de los tokens. Una posibilidad interesante es elegir las cachés de memoria distribuidas de ASP.NET Core:

// Use a distributed token cache by adding:
    services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(
                initialScopes: new string[] { "user.read" })
            .AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

Para información detallada sobre los proveedores de cachés de tokens, vea también el artículo Serialización de la caché de tokens de Microsoft.Identity.Web y el tutorial de la fase de las aplicaciones web de Tutoriales de aplicación web de ASP.NET Core | Cachés de tokens.

Paso siguiente

En este momento, cuando el usuario inicia sesión, un token se almacena en la caché de tokens. A continuación, veremos cómo se usa en otras partes de la aplicación web.