Crear una API de REST para un evento de inicio de emisión de token en Azure Functions

En este artículo se describe cómo crear una API de REST con un evento de inicio de emisión de tokens mediante Azure Functions en Azure Portal. Cree una aplicación de función de Azure y una función de desencadenador HTTP que pueda devolver notificaciones adicionales para el token.

Requisitos previos

• Conocimientos básicos de los conceptos descritos en Introducción a las extensiones de autenticación personalizadas.
• Una suscripción de Azure con la capacidad de crear funciones de Azure. Si no dispone de una cuenta de Azure, puede registrarse para obtener una evaluación gratuita o usar las ventajas de su Visual Studio Subscription cuando cree una cuenta.
• Un inquilino de Microsoft Entra ID. Puede usar un inquilino de cliente o de personal para esta guía paso a paso.

En este artículo se describe cómo crear una API de REST para un evento de inicio de emisión de tokens mediante la biblioteca NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents y configurarla para la autenticación. Creará una función de desencadenador HTTP en Visual Studio o Visual Studio Code, la configurará para la autenticación y la implementará en Azure Portal, donde se puede acceder a ella a través de Azure Functions.

Requisitos previos

• Conocimientos básicos de los conceptos descritos en Introducción a las extensiones de autenticación personalizadas.
• Una suscripción de Azure con la capacidad de crear funciones de Azure. Si no dispone de una cuenta de Azure, puede registrarse para obtener una evaluación gratuita o usar las ventajas de su Visual Studio Subscription cuando cree una cuenta.
• Un inquilino de Microsoft Entra ID. Puede usar un inquilino de cliente o de personal para esta guía paso a paso.
• Una de las siguientes configuraciones y IDE:
  • Visual Studio con carga de trabajo desarrollo de Azure para Visual Studio configurada.
  • Visual Studio Code, con la extensión Azure Functions habilitada.

Creación de la aplicación Azure Function

En Azure Portal, cree una aplicación de función de Azure y su recurso asociado, antes de continuar con la creación de la función desencadenador HTTP.

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 preselecciona según la selección de la pila en tiempo de ejecución.
   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.

Creación de una función desencadenada por HTTP

Después de crear la aplicación de funciones de Azure, cree una función de desencadenador HTTP dentro de la aplicación. El desencadenador HTTP le permite invocar una función con una solicitud HTTP y la extensión de autenticación personalizada de Microsoft Entra hace referencia a esta.

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.

Edite la función

El código lee el objeto JSON entrante y 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.

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 Microsoft Entra request    
       string correlationId = data?.data.authenticationContext.correlationId;
   
       // Claims to return to Microsoft Entra
       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>();
       }
   }
   

3. En el menú superior, seleccione Obtener la dirección URL de la función y copie el valor de la dirección URL. Esta dirección URL de función se puede usar al configurar una extensión de autenticación personalizada.

Creación y compilación de la aplicación de Azure Function

En este paso, creará una API de función de desencadenador HTTP mediante el IDE, instalará los paquetes NuGet necesarios y copiará en el código de ejemplo. Compile el proyecto y ejecute la función para extraer la dirección URL de la función local.

Creación de la aplicación

Para crear una aplicación de Azure Function, siga estos pasos:

Instalación de paquetes NuGet y compilación del proyecto

Después de crear el proyecto, deberá instalar los paquetes NuGet necesarios y compilar el proyecto.

Incorporación del código de ejemplo

La API de función es el origen de las notificaciones adicionales para el token. Para los fines de este artículo, estamos codificando de forma rígida los valores de la aplicación de ejemplo. En producción, puede capturar información sobre el usuario desde el almacén de datos externo. Consulte la clase WebJobsAuthenticationEventsContext para ver las propiedades existentes.

En el archivo AuthEventsTrigger.cs, reemplace todo el contenido del archivo por el código siguiente:

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
                {
                    // Fetches information about the user from external data store
                    // Add new claims to the token's response
                    request.Response.Actions.Add(
                        new WebJobsProvideClaimsForToken(
                            new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                            new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                            new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                            new WebJobsAuthenticationEventsTokenClaim(
                                "correlationId", 
                                request.Data.AuthenticationContext.CorrelationId.ToString())));
                }
                else
                {
                    // If the request fails, such as in token validation, output the failed request status, 
                    // such as in token validation or response validation.
                    log.LogInformation(request.StatusMessage);
                }
                return request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

Compilar y ejecutar el proyecto localmente

Se ha creado el proyecto y se ha agregado el código de ejemplo. Con el IDE, es necesario compilar y ejecutar el proyecto localmente para extraer la dirección URL de la función local.

Ejecutar la función localmente (recomendado)

Es una buena idea probar la función localmente antes de implementarla en Azure. Podemos usar un cuerpo JSON ficticio que imita la solicitud que Microsoft Entra ID envía a la API de REST. Use la herramienta de prueba de API preferida para llamar directamente a la función.

1. En el IDE, abra local.settings.json y reemplace el código por el siguiente JSON. Podemos establecer "AuthenticationEvents__BypassTokenValidation" en true con fines de prueba locales.

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : true
     }
   }
   

2. Con la herramienta de prueba de API preferida, cree una nueva solicitud HTTP y establezca el método HTTP en POST.

3. Use el siguiente cuerpo JSON que imita la solicitud que Microsoft Entra ID envía a la API de REST.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   
   

4. Seleccione Enviar y debería recibir una respuesta JSON similar a la siguiente:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Implementación de la función y publicación en Azure

La función debe implementarse en Azure mediante nuestro IDE. Compruebe que ha iniciado sesión correctamente en su cuenta de Azure para que se pueda publicar la función.

Configurar la autenticación para la función de Azure

Hay tres maneras de configurar la autenticación para la función de Azure:

• Configurar la autenticación en Azure Portal mediante variables de entorno (recomendadas)
• Configurar la autenticación en el código mediante WebJobsAuthenticationEventsTriggerAttribute
• Autenticación y autorización del servicio de Aplicación de Azure

De forma predeterminada, el código se ha configurado para la autenticación en Azure Portal mediante variables de entorno. Use las pestañas siguientes para seleccionar el método preferido para implementar variables de entorno, o bien, consulte la autenticación y autorización del servicio de Aplicación de Azure integradas. Para configurar variables de entorno, use los siguientes valores:

    [FunctionName("onTokenIssuanceStart")]
    public static WebJobsAuthenticationEventResponse Run(
        [WebJobsAuthenticationEventsTriggerAttribute(
            AudienceAppId = "Enter custom authentication extension app ID here",
            AuthorityUrl = "Enter authority URI here", 
            AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log)