Aplicación web que inicia sesión de usuarios: Configuración del código

Artículo
07/19/2024

En este artículo se describe cómo configurar el código para la aplicación web que inicia la sesión de los usuarios.

Bibliotecas de Microsoft que admiten aplicaciones web

Las siguientes bibliotecas de Microsoft se usan para proteger una aplicación web (y una API 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ública¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Guía de inicio rápido			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Guía de inicio rápido			GA
Java	MSAL4J	msal4j	Guía de inicio rápido			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutorial			GA
Node.js	MSAL Node	msal-node	Guía de inicio rápido			GA
Python	MSAL Python	msal				GA
Python	identity	identity	Guía de inicio rápido			--

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

⁽²⁾ 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:

Los fragmentos de código de este artículo y los siguientes se extraen del capítulo 1 del tutorial incremental de aplicaciones web de ASP.NET Core.

Es posible que desee consultar este tutorial para obtener detalles completos de la implementación.

Archivos de configuración

Las aplicaciones web en las que los usuarios inician sesión con la Plataforma de identidad de Microsoft se configuran mediante archivos de configuración. Estos archivos deben especificar los siguientes valores:

La instancia en la nube si quiere que la aplicación se ejecute en las nubes nacionales, por ejemplo. Entre las diferentes opciones se incluyen;
- https://login.microsoftonline.com/ para la nube pública de Azure
- https://login.microsoftonline.us/ para Azure US Government
- https://login.microsoftonline.de/ para Microsoft Entra Alemania
- https://login.partner.microsoftonline.cn/common para Microsoft Entra China operado por 21Vianet
La audiencia en el id. de inquilino. Las opciones varían en función de si la aplicación es de un solo inquilino o multiinquilino.
- El GUID del inquilino obtenido de Azure Portal para conectar usuarios de su organización. También puede usar un nombre de dominio.
- organizations para iniciar sesión de los usuarios en cualquier cuenta profesional o educativa
- common para iniciar sesión de los usuarios con cualquier cuenta profesional o educativa o cuenta personal de Microsoft
- consumers para iniciar sesión solo a los usuarios con una cuenta personal de Microsoft
El Id. de cliente para la aplicación, tal y como se ha copiado de Azure Portal

También puede ver referencias a la autoridad, una concatenación de los valores de la instancia y del Id. de inquilino.

En ASP.NET Core, estos valores se encuentran en el archivo appsettings.json, en la sección "Microsoft Entra ID".

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

En ASP.NET Core, hay otro archivo (properties\launchSettings.json) que contiene la dirección URL (applicationUrl) y el puerto SSL/TLS (sslPort) de la aplicación, así como diversos perfiles.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

En Azure Portal, los identificadores URI de redirección que se registran en la página Autenticación de la aplicación deben coincidir con estas direcciones URL. En el caso de los dos archivos de configuración anteriores, deben ser https://localhost:44321/signin-oidc. El motivo es que applicationUrl es http://localhost:3110, pero se especifica sslPort (44321). CallbackPath es /signin-oidc, tal y como se define en appsettings.json.

De la misma manera, el URI de cierre de sesión se establecería en https://localhost:44321/signout-oidc.

Nota:

SignedOutCallbackPath debe establecerse en el portal o en la aplicación para evitar conflictos al controlar el evento.

En ASP.NET, la aplicación se configura en las líneas 12 a 15 del archivo appsettings.json.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",
    "ClientId": "[Enter the Client Id here]",
  }
}

En Azure Portal, los identificadores URI de respuesta que se registran en la página Autenticación de la aplicación deben coincidir con estas direcciones URL. Es decir, deben ser https://localhost:44326/.

En Java, la configuración se encuentra en el archivo application.properties, ubicado en src/main/resources.

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

En Azure Portal, los identificadores URI de respuesta que se registran en la página Autenticación de la aplicación deben coincidir con las instancias de redirectUri que define la aplicación. Es decir, deben ser http://localhost:8080/msal4jsample/secure/aad y http://localhost:8080/msal4jsample/graph/me.

Aquí los parámetros de configuración residen en .env.dev como variables de entorno:

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

Estos parámetros se usan para crear un objeto de configuración en el archivo authConfig.js, que finalmente se usará para inicializar el nodo MSAL:

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

En Azure Portal, los identificadores URI de respuesta que se registran en la página Autenticación de la aplicación deben coincidir con las instancias de redirectUr que define la aplicación (http://localhost:3000/auth/redirect).

Para simplificar este artículo, el secreto de cliente se almacena en el archivo de configuración. En la aplicación de producción, considere la posibilidad de usar un almacén de claves o una variable de entorno. Una opción aún mejor es usar un certificado.

Los parámetros de configuración están definidos en .env como variables de entorno:

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

Se hace referencia a esas variables de entorno en app_config.py:

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

El archivo .env nunca debe estar insertado en el repositorio del control de código fuente, ya que contiene secretos. El ejemplo de inicio rápido incluye un archivo .gitignore que impide que el archivo .env se inserte en el repositorio.

# Environments
.env

Código de inicialización

Las diferencias de código de inicialización dependen de la plataforma. En el caso de ASP.NET Core y ASP.NET, el inicio de sesión de los usuarios se delega en el middleware OpenID Connect. La plantilla de ASP.NET o ASP.NET Core genera aplicaciones web para el punto de conexión de Azure AD v1.0. Se necesita algo de configuración para adaptarlos a la Plataforma de identidad de Microsoft.

En las aplicaciones web de ASP.NET Core (y API web), la aplicación está protegida porque se dispone de un atributo Authorize en los controladores o en las acciones de estos. Este atributo comprueba que el usuario está autenticado. Antes del lanzamiento de .NET 6, el código de inicialización se encontraba en el archivo Startup.cs. Los nuevos proyectos de ASP.NET Core con .NET 6 ya no contienen un archivo Startup.cs. Su lugar lo ocupa el archivo Program.cs. El resto de este tutorial pertenece a .NET 5 o versiones anteriores.

Nota:

Si desea empezar directamente con las nuevas plantillas de ASP.NET Core para la Plataforma de identidad de Microsoft, que aprovecha Microsoft.Identity.Web, puede descargar un paquete NuGet en versión preliminar que contiene plantillas de proyecto para .NET 5.0. Después, una vez instalado, puede crear directamente una instancia de aplicaciones web ASP.NET Core (MVC o Blazor). Para obtener más información, consulte Plantillas de proyecto de aplicaciones web de Microsoft.Identity.Web. Este es el enfoque más sencillo, ya que realizará todos los pasos que se indican a continuación por usted.

Si prefiere iniciar el proyecto con el proyecto web de ASP.NET Core predeterminado actual en Visual Studio o mediante dotnet new mvc --auth SingleOrg o dotnet new webapp --auth SingleOrg, verá código como el siguiente:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

Este código usa el paquete NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI heredado que se usa para crear una aplicación de Azure Active Directory v1.0. En este artículo se explica cómo crear una aplicación de la plataforma de identidad de Microsoft v2.0 que reemplaza ese código.

Agregue los paquetes NuGet Microsoft.Identity.Web y Microsoft.Identity.Web.UI al proyecto. Quite el paquete NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI si aparece.

Actualice el código en ConfigureServices para que use los métodos AddMicrosoftIdentityWebApp y AddMicrosoftIdentityUI.

public class Startup
{
 ...
 // This method gets called by the runtime. Use this method to add services to the container.
 public void ConfigureServices(IServiceCollection services)
 {
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
         .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");

  services.AddRazorPages().AddMvcOptions(options =>
  {
   var policy = new AuthorizationPolicyBuilder()
                 .RequireAuthenticatedUser()
                 .Build();
   options.Filters.Add(new AuthorizeFilter(policy));
  }).AddMicrosoftIdentityUI();

En el método Configure de Startup.cs, habilite la autenticación con una llamada a app.UseAuthentication(); y app.MapControllers();.

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 // more code here
 app.UseAuthentication();
 app.UseAuthorization();

 app.MapRazorPages();
 app.MapControllers();
 // more code here
}

En el código:

El método de extensión AddMicrosoftIdentityWebApp se define en Microsoft.Identity.Web.UI, que;
- Configura las opciones para leer el archivo de configuración (aquí desde la sección "Microsoft Entra ID").
- Configura las opciones de OpenID Connect para que la autoridad sea la Plataforma de identidad de Microsoft.
- Valida el emisor del token.
- Garantiza que las notificaciones correspondientes al nombre se asignan a partir de la notificación preferred_username del token de identificador.
Además del objeto de configuración, se puede especificar el nombre de la sección de configuración mediante una llamada a AddMicrosoftIdentityWebApp. De forma predeterminada, es AzureAd.
AddMicrosoftIdentityWebApp tiene otros parámetros para escenarios avanzados. Por ejemplo, el seguimiento de eventos de middleware de OpenID Connect puede ayudar a solucionar problemas de la aplicación web, si la autenticación no funciona. Al establecer el parámetro opcional subscribeToOpenIdConnectMiddlewareDiagnosticsEvents en true, se mostrará cómo se procesa la información mediante el conjunto de middleware de ASP.NET Core a medida que progresa de la respuesta HTTP a la identidad del usuario en HttpContext.User.
El método de extensión AddMicrosoftIdentityUI se define en Microsoft.Identity.Web.UI. Proporciona un controlador predeterminado para controlar el inicio y cierre de sesión.

Para obtener más información sobre cómo Microsoft.Identity.Web permite crear aplicaciones web, consulte Web Apps en microsoft-identity-web.

El código relacionado con la autenticación en la aplicación web ASP.NET y las API web se encuentra en el archivo App_Start/Startup.Auth.cs.

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

El ejemplo de Java usa Spring Framework. La aplicación está protegida porque se implementa un filtro, que intercepta cada respuesta HTTP. En el inicio rápido de las aplicaciones web de Java, este filtro es AuthFilter en src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

El filtro procesa el flujo de código de autorización de OAuth 2.0 y comprueba si el usuario está autenticado (método isAuthenticated()). Si el usuario no está autenticado, procesa la dirección URL de los puntos de conexión de autorización de Microsoft Entra y redirige el explorador a este identificador URI.

Cuando llega la respuesta, que contiene el código de autorización, adquiere el token con MSAL para Java. Cuando recibe finalmente el token del punto de conexión de token (en el URI de redirección), el usuario ha iniciado sesión.

Para obtener más información, vea el método doFilter() en AuthFilter.java.

Nota:

El código de doFilter() se escribe en un orden ligeramente distinto, pero el flujo es el que se describe.

Vea Plataforma de identidad de Microsoft y flujo de código de autorización de OAuth 2.0 para más información sobre el flujo de código de autorización que desencadena este método.

El ejemplo de Node usa el marco Express. MSAL se inicializa en el controlador de ruta auth :

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

El ejemplo de Python se compila con el marco de Flask, aunque también se podrían usar otros marcos como Django. La aplicación Flask se inicializa con la configuración de la aplicación en la parte superior de app.py:

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

A continuación, el código construye un auth objeto mediante el paquete de identidad.

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Paso siguiente

Inicio y cierre de sesión.

Compartir a través de

Aplicación web que inicia sesión de usuarios: Configuración del código

Bibliotecas de Microsoft que admiten aplicaciones web

Archivos de configuración

Código de inicialización

Paso siguiente

Comentarios

Recursos adicionales