Configuración de un evento de emisión de tokens de proveedor de notificaciones personalizado (versión preliminar)

En este artículo se explica cómo configurar e instalar un proveedor de notificaciones personalizado con un evento de inicio de emisión de tokens. Creará una API de REST mediante Azure Functions en Azure Portal y, a continuación, registrará una extensión de autenticación personalizada. Agregará algunos atributos que espera que la extensión de autenticación personalizada analice desde la API de REST. Para probar la extensión de autenticación personalizada, registrará una aplicación de OpenID Connect de ejemplo para obtener un token y ver las notificaciones.

En el vídeo siguiente se describen los pasos que va a replicar en este artículo para configurar un proveedor de notificaciones personalizado de Microsoft Entra con una aplicación de funciones de Azure:

Requisitos previos

Paso 1: Creación de una aplicación de funciones de Azure

En este paso, crea una API de función de desencadenador HTTP en Azure Portal. La API de función es el origen de las notificaciones adicionales para el token. Siga estos pasos para crear una función de Azure:

  1. Inicie sesión en Azure Portal como al menos un Administrador de aplicaciones y un Administrador de autenticación.

  2. En el menú o la página Inicio de Azure Portal, seleccione Crear un recurso.

  3. Busque y seleccione Aplicación de funciones y seleccione Crear.

  4. En la página Aspectos básicos, cree una aplicación de funciones con la configuración especificada en la tabla siguiente:

    Configuración Valor sugerido Descripción
    Suscripción Su suscripción Suscripción donde se creará la nueva aplicación de funciones.
    Grupo de recursos myResourceGroup Seleccione un grupo de recursos actual o proporcione el nombre para uno nuevo donde creará la aplicación de funciones.
    Nombre de la aplicación de función Nombre único globalmente Nombre que identifica la nueva aplicación de funciones. Los caracteres válidos son a-z (no distingue mayúsculas de minúsculas), 0-9 y -.
    Implementación de código o imagen de contenedor Código Opción para publicar archivos de código o un contenedor de Docker. Para este tutorial, seleccione Code.
    Pila en tiempo de ejecución .NET Lenguaje de programación que prefiere. Para este tutorial, seleccione .NET.
    Versión 6 (LTS) en curso Versión del entorno de ejecución de .NET. En curso indica que puede crear y modificar funciones en el portal, algo que se recomienda para esta guía.
    Región Región preferida Seleccione una región próxima a usted o a otros servicios a los que accedan las funciones.
    Sistema operativo Windows El sistema operativo se selecciona automáticamente en función de la pila en tiempo de ejecución que haya seleccionado.
    Tipo de plan Consumo (sin servidor) Plan de hospedaje que define cómo se asignan los recursos a la Function App.
  5. Seleccione Revisar y crear para revisar la configuración seleccionada para la aplicación y elija Crear. La implementación tarda unos minutos.

  6. Una vez implementada, seleccione Ir al recurso para ver la nueva aplicación de funciones.

1.1 Creación de una función de desencadenador HTTP

Después de crear la aplicación de funciones de Azure, cree una función de desencadenador HTTP. El desencadenador HTTP permite invocar una función con una solicitud HTTP. La extensión de autenticación personalizada de Microsoft Entra hará referencia y llamará a este desencadenador HTTP.

  1. En la página Información general de la aplicación de funciones, seleccione el panel Funciones y seleccione Crear función en Crear en Azure Portal.

  2. En la ventana Crear función, mantenga la propiedad Entorno de desarrollo como Desarrollo en el portal. En Plantilla, seleccione Desencadenador HTTP.

  3. En Detalles de la plantilla, escriba CustomAuthenticationExtensionsAPI para la propiedad Nueva función.

  4. En Nivel de autorización, seleccione Función.

  5. Seleccione Crear.

    Screenshot that shows how to choose the development environment, and template.

1.2 Edición de la función

  1. En el menú, en Desarrollador, seleccione Código y prueba.

  2. Reemplace todo el código por el siguiente fragmento de código y, a continuación, seleccione Guardar.

    #r "Newtonsoft.Json"
    using System.Net;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Extensions.Primitives;
    using Newtonsoft.Json;
    public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
    {
        log.LogInformation("C# HTTP trigger function processed a request.");
        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        dynamic data = JsonConvert.DeserializeObject(requestBody);
    
        // Read the correlation ID from the Azure AD  request    
        string correlationId = data?.data.authenticationContext.correlationId;
    
        // Claims to return to Azure AD
        ResponseContent r = new ResponseContent();
        r.data.actions[0].claims.CorrelationId = correlationId;
        r.data.actions[0].claims.ApiVersion = "1.0.0";
        r.data.actions[0].claims.DateOfBirth = "01/01/2000";
        r.data.actions[0].claims.CustomRoles.Add("Writer");
        r.data.actions[0].claims.CustomRoles.Add("Editor");
        return new OkObjectResult(r);
    }
    
    public class ResponseContent{
        [JsonProperty("data")]
        public Data data { get; set; }
        public ResponseContent()
        {
            data = new Data();
        }
    }
    
    public class Data{
        [JsonProperty("@odata.type")]
        public string odatatype { get; set; }
        public List<Action> actions { get; set; }
        public Data()
        {
            odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
            actions = new List<Action>();
            actions.Add(new Action());
        }
    }
    
    public class Action{
        [JsonProperty("@odata.type")]
        public string odatatype { get; set; }
        public Claims claims { get; set; }
        public Action()
        {
            odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
            claims = new Claims();
        }
    }
    
    public class Claims{
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string CorrelationId { get; set; }
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string DateOfBirth { get; set; }
        public string ApiVersion { get; set; }
        public List<string> CustomRoles { get; set; }
        public Claims()
        {
            CustomRoles = new List<string>();
        }
    }
    

    El código comienza leyendo el objeto JSON entrante. Microsoft Entra ID envía el objeto JSON a la API. En este ejemplo, lee el valor del id. de correlación. A continuación, el código devuelve una colección de notificaciones personalizadas, incluido el CorrelationId original, la ApiVersion de la función de Azure, DateOfBirth y CustomRoles que se devuelve a Microsoft Entra ID.

  3. En el menú superior, seleccione Obtener la dirección URL de la función y copie el valor de la dirección URL. En el siguiente paso, se usa la dirección URL de la función y se hace referencia a ella como {Function_Url}. Es recomendable dejar abierta la ventana de Azure Portal, ya que se usará de nuevo en pasos posteriores.

Paso 2: Registrar una extensión de autenticación personalizada

Ahora configurará una extensión de autenticación personalizada, que usará Microsoft Entra ID para llamar a la función de Azure. La extensión de autenticación personalizada contiene información sobre el punto de conexión de la API de REST, las notificaciones que analiza desde la API de REST y cómo autenticarse en la API de REST. Siga estos pasos para registrar una extensión de autenticación personalizada:

  1. En la página Principal de Azure Portal, seleccione Microsoft Entra ID y seleccione Aplicaciones empresariales.
  2. Seleccione Extensiones de autenticación personalizadas y, después, seleccione Crear una extensión personalizada.
  3. En Aspectos básicos, seleccione el tipo de evento TokenIssuanceStart y seleccione Siguiente.
  4. En Configuración de punto de conexión, rellene las siguientes propiedades:
    • Nombre: nombre de la extensión de autenticación personalizada. Por ejemplo, Evento de emisión de tokens.
    • Dirección URL de destino: {Function_Url} de la dirección URL de la función de Azure.
    • Descripción: descripción de la extensión de autenticación personalizada.
  5. Seleccione Next (Siguiente).
  6. En Autenticación de API, seleccione la opción Crear un nuevo registro de aplicación para crear un registro de aplicación que represente a la aplicación de funciones.
  7. Asigne un nombre a la aplicación; por ejemplo, API de eventos de autenticación de Azure Functions.
  8. Seleccione Next (Siguiente).
  9. En Notificaciones, escriba los atributos que espera que la extensión de autenticación personalizada analice desde la API de REST y que se combinarán con el token. Agregue las siguientes notificaciones:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  10. Seleccione Siguiente y Crear para registrar la extensión de autenticación personalizada y el registro de aplicación asociado.

Una vez creada la extensión de autenticación personalizada, debe conceder permisos a la API. La extensión de autenticación personalizada usa client_credentials para autenticarse en la aplicación de funciones de Azure mediante el permiso Receive custom authentication extension HTTP requests.

  1. Abra la página Información general de la nueva extensión de autenticación personalizada. Tome nota del Identificador de aplicación en Autenticación de API, ya que será necesario al agregar un proveedor de identidades.

  2. En Autenticación de API, seleccione Conceder permiso.

  3. Se abre una nueva ventana y, una vez iniciada, solicita permisos para recibir solicitudes HTTP de extensión de autenticación personalizadas. Esto permite que la extensión de autenticación personalizada se autentique en la API. Seleccione Aceptar.

    Screenshot that shows how grant admin consent.

Paso 3: Configurar una aplicación OpenID Connect para recibir tokens enriquecidos

Para obtener un token y probar la extensión de autenticación personalizada, puede usar la aplicación https://jwt.ms. Es una aplicación web de Microsoft que muestra el contenido descodificado de un token (el contenido del token nunca sale del explorador).

3.1 Registro de una aplicación web de prueba

Siga estos pasos para registrar la aplicación web jwt.ms:

  1. En la página Principal de Azure Portal, seleccione Registros de aplicaciones.

  2. Seleccione Nuevo registro.

  3. Escriba un Nombre para la aplicación. Por ejemplo, Mi aplicación de prueba.

  4. En Tipos de cuenta admitidos, seleccione Solo las cuentas de este directorio organizativo.

  5. En la lista desplegable Seleccionar una plataforma, en URI de redirección, seleccione Web y escriba https://jwt.ms en el cuadro de texto Dirección URL.

  6. Seleccione Registrar para completar el registro de la aplicación.

    Screenshot that shows how to select the supported account type and redirect URI.

  7. En la página Información general del registro de la aplicación, copie el Identificador de aplicación (cliente). Al id. de la aplicación se hace referencia como {App_to_enrich_ID} en pasos posteriores. En Microsoft Graph, se hace referencia a él mediante la propiedad appId.

    Screenshot that shows how to copy the application ID.

3.2 Habilitación del flujo implícito

La aplicación de prueba jwt.ms usa el flujo implícito. Habilite el flujo implícito en el registro de Mi aplicación de prueba:

  1. En Administrar, seleccione Autenticación.
  2. En Flujos de concesión implícita e híbridos, seleccione la casilla de verificación Tokens de id. (usados para flujos híbridos e implícitos).
  3. Seleccione Guardar.

3.3 Habilitación de la aplicación para una directiva de asignación de notificaciones

Una directiva de asignación de notificaciones se usa para seleccionar los atributos devueltos de la extensión de autenticación personalizada que se asignan al token. Para permitir que se aumenten los tokens, debe habilitar explícitamente el registro de la aplicación para aceptar notificaciones asignadas:

  1. En el registro de Mi aplicación de prueba, en Administrar, seleccione Manifiesto.
  2. En el manifiesto, busque el atributo acceptMappedClaims y establezca el valor en true.
  3. Establecer accessTokenAcceptedVersion en 2.
  4. Seleccione Guardar para guardar los cambios.

El siguiente fragmento de código JSON muestra cómo configurar estas propiedades.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

Advertencia

No establezca la propiedad acceptMappedClaims en true para las aplicaciones multiinquilino, ya que puede permitir que actores malintencionados creen directivas de asignación de notificaciones para la aplicación. En su lugar, configure una clave de firma personalizada.

Continúe con el paso siguiente, Asignar un proveedor de notificaciones personalizado a la aplicación.

Paso 4: Asignación de un proveedor de notificaciones personalizado a la aplicación

Para que los tokens se emitan con notificaciones entrantes de la extensión de autenticación personalizada, debe asignar un proveedor de notificaciones personalizado a la aplicación. Esto se basa en la audiencia del token, por lo que el proveedor debe asignarse a la aplicación cliente para recibir reclamaciones en un token de identificación, y a la aplicación de recursos para recibir reclamaciones en un token de acceso. El proveedor de notificaciones personalizado se basa en la extensión de autenticación personalizada configurada con el agente de escucha de eventos de inicio de emisión de tokens. Puede elegir si se asignan al token todas las notificaciones del proveedor de notificaciones personalizados o un subconjunto de ellas.

Siga estos pasos para conectar Mi aplicación de prueba con la extensión de autenticación personalizada:

Para asignar la extensión de autenticación personalizada como origen del proveedor de notificaciones personalizado:

  1. En la página Principal de Azure Portal, seleccione Aplicaciones empresariales.

  2. En Administrar, seleccione Todas las aplicaciones y, a continuación, seleccione Mi aplicación de prueba en la lista.

  3. En la página Información general de Mi aplicación de prueba, vaya a Administrar y seleccione Inicio de sesión único.

  4. En Atributos y reclamaciones, seleccione Editar.

    Screenshot that shows how to configure app claims.

  5. Expanda el menú Configuración avanzada.

  6. Junto a Proveedor de notificaciones personalizado, seleccione Configurar.

  7. Expanda el cuadro desplegable Proveedor de notificaciones personalizado y seleccione el Evento de emisión de tokens que creó antes.

  8. Seleccione Guardar.

A continuación, asigne los atributos del proveedor de notificaciones personalizado, que deben emitirse en el token como notificaciones:

  1. Seleccione Agregar nueva notificación para agregar una nueva notificación. Proporcione un nombre para la notificación que desea emitir; por ejemplo dateOfBirth.

  2. En Origen, seleccione Atributo y elija customClaimsProvider.dateOfBirth en el cuadro desplegable Atributo de origen.

    Screenshot that shows how to add a claim mapping to your app.

  3. Seleccione Guardar.

  4. Repita este proceso para agregar los atributos customClaimsProvider.customRoles, customClaimsProvider.apiVersion y customClaimsProvider.correlationId, y el nombre correspondiente. Es recomendable que el nombre de la notificación coincida con el nombre del atributo.

Paso 5: Protección de la función de Azure

La extensión de autenticación personalizada de Microsoft Entra usa el flujo de servidor a servidor para obtener un token de acceso que se envía en el encabezado HTTP Authorization a la función de Azure. Al publicar la función en Azure, especialmente en un entorno de producción, debe validar el token enviado en el encabezado de autorización.

Para proteger la función de Azure, siga estos pasos con el fin de integrar la autenticación de Microsoft Entra, para validar los tokens entrantes con el registro de aplicación de la API de eventos de autenticación de Azure Functions.registro de aplicaciones. Elija una de las pestañas siguientes en función del tipo de inquilino.

Nota:

Si la aplicación de funciones de Azure se hospeda en un inquilino de Azure diferente del inquilino en el que está registrada la extensión de autenticación personalizada, elija la pestaña Open ID Connect.

5.1 Usar un proveedor de identidades de Microsoft Entra

Use estos pasos para agregar Microsoft Entra como proveedor de identidades a la aplicación de funciones de Azure.

  1. En Azure Portal, busque la aplicación de funciones que publicó antes y selecciónela.

  2. En Configuración, seleccione Autenticación.

  3. Seleccione Agregar proveedor de identidades.

  4. Seleccione Microsoft como proveedor de identidades.

  5. Seleccione Personal como tipo de inquilino.

  6. En Registro de aplicación, seleccione Seleccionar un registro de aplicación existente en este directorio para el Tipo de registro de la aplicación y seleccione la API de eventos de autenticación de Azure Functions que creó antes al registrar el proveedor de notificaciones personalizado.

  7. Escriba la siguiente dirección URL del emisor, https://login.microsoftonline.com/{tenantId}/v2.0, donde {tenantId} es el identificador de inquilino del inquilino del personal.

  8. En Solicitudes no autenticadas, seleccione HTTP 401 No autorizado como proveedor de identidades.

  9. Anule la selección de la opción Almacén de tokens.

  10. Seleccione Agregar para agregar autenticación a la función de Azure.

    Screenshot that shows how to add authentication to your function app while in a workforce tenant.

5.2 Usar el proveedor de identidades de OpenID Connect

Si ha configurado el proveedor de identidades de Microsoft, omita este paso. De lo contrario, si la función de Azure está hospedada en un inquilino diferente al inquilino en el que está registrada la extensión de autenticación personalizada, siga estos pasos para proteger la función:

Deberá crear un secreto de cliente para el registro de aplicaciones de la API de eventos de autenticación de Azure Functions.

  1. En la página Principal de Azure Portal, seleccione Microsoft Entra ID>Registros de aplicaciones
  2. Seleccione el registro de aplicación de la API de eventos de autenticación de Azure Functionsque creó antes.
  3. Seleccione Certificates & secrets>Client secrets>New client secret (Certificados y secretos > Secretos de cliente > Nuevo secreto de cliente).
  4. Seleccione una expiración para el secreto o especifique una duración personalizada, agregue una descripción y seleccione Agregar.
  5. Registre el valor del secreto para usarlo en el código de la aplicación cliente. Este valor secreto no se volverá a mostrar una vez que abandone esta página.

A continuación, agregaremos el proveedor de identidades de OpenID Connect a la aplicación de funciones de Azure.

  1. Busque y seleccione la aplicación de funciones que publicó anteriormente.

  2. En Configuración, seleccione Autenticación.

  3. Seleccione Agregar proveedor de identidades.

  4. Seleccione OpenID Connect como proveedor de identidades.

  5. Proporcione un nombre, como Contoso Microsoft Entra ID.

  6. En Entrada de metadatos, escriba la siguiente URL en el cuadro Dirección URL del documento. Reemplace por el {tenantId} identificador de inquilino de Microsoft Entra.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
    
  7. En Registro de aplicación, escriba el id. de la aplicación (id. de cliente) del registro de aplicación de la API de eventos de autenticación de Azure Functionsque creó antes.

  8. Vuelva a la función de Azure y, en Registro de aplicación, escriba el Secreto de cliente.

  9. Anule la selección de la opción Almacén de tokens.

  10. Seleccione Agregar para agregar el proveedor de identidades de OpenID Connect.


Paso 6: Probar la aplicación

Para probar el proveedor de notificaciones personalizado, siga estos pasos:

  1. Abra un nuevo explorador privado, vaya a la siguiente dirección URL e inicie sesión.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345
    
  2. Reemplace {tenantId} por el id. del inquilino, el nombre del inquilino o uno de los nombres de dominio comprobados. Por ejemplo, contoso.onmicrosoft.com.

  3. Reemplace {App_to_enrich_ID} por el identificador de cliente de Mi aplicación de prueba.

  4. Recorra el flujo de usuario de inicio de sesión que ha configurado y acepte los permisos solicitados.

  5. Después de iniciar sesión, se le muestra el token descodificado en https://jwt.ms. Compruebe que aparecen las notificaciones de la función de Azure en el token descodificado; por ejemplo, dateOfBirth.

Consulte también