Inicio rápido: Protección de una API web de ASP.NET Core con la plataforma de identidad de Microsoft

Artículo
02/21/2024

¡Bienvenido! Probablemente esta no sea la página que esperaba. Mientras trabajamos en una corrección, este vínculo debería llevarle al artículo correcto:

Inicio rápido: Llamada a una API web de ASP.NET Core protegida por la plataforma de identidad de Microsoft

Lamentamos las molestias y agradecemos su paciencia mientras trabajamos para resolverlo.

En el siguiente inicio rápido se usa un ejemplo de código de API web de ASP.NET Core para demostrar cómo restringir el acceso a los recursos a las cuentas autorizadas. El ejemplo admite la autorización de cuentas personales de Microsoft y cuentas de cualquier organización de Microsoft Entra.

Requisitos previos

Cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Inquilino de Microsoft Entra
Requisito mínimo del SDK de .NET 6.0
Visual Studio 2022 o Visual Studio Code

Paso 1: Registro de la aplicación

En primer lugar, registre la API web en el inquilino de Microsoft Entra y agregue un ámbito siguiendo estos pasos:

Inicie sesión en el Centro de administración de Microsoft Entra al menos como Administrador de aplicaciones.
Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.
Seleccione Nuevo registro.
En Nombre, escriba un nombre de la aplicación. Por ejemplo, escriba AspNetCoreWebApi-Quickstart. Los usuarios de la aplicación verán este nombre, que puede cambiar más tarde.
Seleccione Registrar.
En Administrar, seleccione Exponer una API>Agregar un ámbito. Acepte el valor predeterminado de URI de id. de la aplicación, para lo que debe seleccionar Guardar y continuar, y escriba los siguientes datos:

Nombre de ámbito: access_as_user
¿Quién puede dar el consentimiento? : Administradores y usuarios
Nombre para mostrar del consentimiento del administrador: Access AspNetCoreWebApi-Quickstart
Descripción del consentimiento del administrador: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Nombre para mostrar del consentimiento del usuario: Access AspNetCoreWebApi-Quickstart
Descripción del consentimiento del usuario: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Estado: Enabled

Seleccione Agregar ámbito para completar la adición del ámbito.

Paso 2: Descarga del proyecto de ASP.NET Core

Descargue la solución de ASP.NET Core de GitHub.

Nota

Actualmente, el ejemplo de código tiene como destino ASP.NET Core 3.1. El ejemplo se puede actualizar para usar .NET Core 6.0 y se describe en los pasos siguientes: Actualice el código de ejemplo a ASP.NET Core 6.0. Este inicio rápido quedará en desuso en un futuro próximo y se actualizará para usar .NET 6.0.

Paso 3: Configuración del proyecto de ASP.NET Core

En este paso, el código de ejemplo se configurará para que funcione con el registro de la aplicación que se creó anteriormente.

Extraiga el archivo .zip en una carpeta local cercana a la raíz del disco para evitar errores causados por limitaciones de longitud de ruta de acceso en Windows. Por ejemplo, en C:\Azure-Samples.
Abra la solución en la carpeta webapi en el editor de código.
En appsettings.json, reemplace los valores de ClientId y TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here es el identificador (cliente) de la aplicación registrada.
- Reemplace Enter_the_Tenant_Info_Here por una de las opciones siguientes:
  - Si la aplicación admite Solo las cuentas de este directorio organizativo, reemplace este valor por el identificador de directorio (inquilino) (un GUID) o por el nombre del inquilino (por ejemplo, contoso.onmicrosoft.com). El identificador de directorio (inquilino) se puede encontrar en la página Información general de la aplicación.
  - Si la aplicación admite cuentas de cualquier directorio organizativo, reemplace este valor por organizations.
  - Si la aplicación admite Todos los usuarios de cuentas Microsoft, establezca el valor en common.

Para esta guía de inicio rápido, no cambie ningún otro valor del archivo appsettings.json.

Paso 4: actualizar el código de ejemplo a ASP.NET Core 6.0

Para actualizar este ejemplo de código a ASP.NET Core 6.0 de destino, siga estos pasos:

Abra webapi.csproj
Quite la línea siguiente:

<TargetFramework>netcoreapp3.1</TargetFramework>

Agregue la siguiente línea en su lugar:

<TargetFramework>netcoreapp6.0</TargetFramework>

Este paso garantizará que el ejemplo tenga como destino el marco de .NET Core 6.0.

Paso 5: Ejecución de la muestra

Abra un terminal y cambie el directorio a la carpeta del proyecto.
```
cd webapi
```
Ejecute el siguiente comando para compilar la solución:

dotnet run

Si la compilación se ha realizado correctamente, se muestra la siguiente salida:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Funcionamiento del ejemplo

Clase Startup

El middleware Microsoft.AspNetCore.Authentication usa una clase Startup que se ejecuta cuando se inicializa el proceso de hospedaje. En su método ConfigureServices , se llama al método de extensión AddMicrosoftIdentityWebApi proporcionado por Microsoft.Identity.Web.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

El método AddAuthentication() configura el servicio para agregar la autenticación basada en JwtBearer.

La línea que contiene .AddMicrosoftIdentityWebApi agrega la autorización de la plataforma de identidad de Microsoft a la API web. Después se configura para validar los tokens de acceso emitidos por la plataforma de identidad de Microsoft según la información de la sección AzureAD del archivo de configuración appsettings.json:

Clave appsettings.json	Descripción
`ClientId`	Id. de la aplicación (cliente) registrada.
`Instance`	El punto de conexión del servicio de token de seguridad (STS) para que el usuario se autentique. Normalmente, este valor es `https://login.microsoftonline.com/`, que indica la nube pública de Azure.
`TenantId`	Nombre o id. del inquilino (un GUID), o bien `common`, para el inicio de sesión de usuarios con cuentas profesionales o educativas o cuentas personales de Microsoft.

El método Configure() contiene dos métodos importantes, app.UseAuthentication() y app.UseAuthorization(), que habilitan su funcionalidad con nombre:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Protección de un controlador, del método de un controlador o de una página de Razor

Los métodos de controlador o controlador se pueden proteger mediante el atributo [Authorize]. Este atributo restringe el acceso al controlador o los métodos al permitir únicamente usuarios autenticados. Si el usuario aún no se ha autenticado, se puede iniciar un desafío de autenticación para acceder al controlador.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Validación del ámbito en el controlador

El código de la API comprueba que los ámbitos necesarios están en el token mediante HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Ayuda y soporte técnico

Si necesita ayuda, desea informar de un problema o desea obtener información sobre las opciones de soporte técnico, consulte Opciones de ayuda y soporte técnico para desarrolladores.

Pasos siguientes

El siguiente repositorio de GitHub contiene las instrucciones de ejemplo de código de API web de ASP.NET Core y más ejemplos que muestran cómo lograr lo siguiente:

Agregar autenticación a una nueva API web de ASP.NET Core.
Llamar a la API web desde una aplicación de escritorio.
Llamar a las API de bajada como Microsoft Graph y otras API de Microsoft.

Tutoriales de API web de ASP.NET Core en GitHub