Desencadenador de eventos de autenticación para Azure Functions biblioteca cliente para .NET

  • Artículo

El desencadenador de eventos de autenticación para Azure Functions permite implementar una extensión personalizada para controlar los eventos de autenticación de Azure Active Directory (Azure AD). El desencadenador de eventos de autenticación controla todo el procesamiento de back-end para las solicitudes HTTP entrantes para eventos de autenticación de Azure AD y proporciona al desarrollador:

  • Validación de tokens para proteger la llamada API
  • IntelliSense para el modelo de objetos, la escritura y el IDE
  • Validación entrante y saliente de los esquemas de solicitud y respuesta de la API

Introducción

Instalar el paquete

Instale el desencadenador de eventos de autenticación para Azure Functions con NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --prerelease

Requisitos previos

Autenticar el cliente

Cuando el servicio de eventos de autenticación de Azure AD llama a la extensión personalizada, envía un Authorization encabezado con .Bearer {token} Este token representa un servicio para la autenticación del servicio en el que:

  • El "recurso", también conocido como audiencia, es la aplicación que se registra para representar la API. Esto se representa mediante la aud notificación en el token.
  • El "cliente" es una aplicación de Microsoft que representa el servicio de eventos de autenticación de Azure AD. Tiene un appId valor de 99045fe1-7639-4a75-9d4a-577b6ca3810f. Esto se representa mediante:
    • Notificación azp en el token si la propiedad de la aplicación accessTokenAcceptedVersion está establecida 2en .
    • La appid notificación del token si la propiedad de la aplicación de accessTokenAcceptedVersion recursos está establecida 1 en o null.

Hay tres enfoques para autenticar solicitudes HTTP en la aplicación de funciones y validar el token.

Validación de tokens mediante Azure Functions integración de autenticación de Azure AD

Al ejecutar la función en producción, se recomienda encarecidamente usar la integración de autenticación de Azure AD Azure Functions para validar los tokens entrantes. Establezca la siguiente configuración de la aplicación de función.

  1. Vaya a la pestaña "Autenticación" de la aplicación de funciones.
  2. Haga clic en "Agregar proveedor de identidades".
  3. Seleccione "Microsoft" como proveedor de identidades.
  4. Seleccione "Proporcionar los detalles de un registro de aplicación existente"
  5. Escriba la Application ID propiedad de la aplicación que representa la API en Azure AD.

El emisor y la audiencia permitida dependen de la accessTokenAcceptedVersion propiedad de la aplicación (se puede encontrar en el "Manifiesto" de la aplicación).

Si la accessTokenAcceptedVersion propiedad está establecida 2en : 6. Establezca appId Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (')

Si la accessTokenAcceptedVersion propiedad está establecida 1 en o null: 6. Establezca el Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentificadorUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' si usa un nombre de dominio personalizado.

De forma predeterminada, el desencadenador de eventos de autenticación validará que la integración de la autenticación de Azure Functions está configurada y comprobará que el cliente del token está establecido 99045fe1-7639-4a75-9d4a-577b6ca3810f en (a través de las azp notificaciones o appid del token).

Si quiere probar la API con algún otro cliente que no sea el servicio de eventos de autenticación de Azure AD, como el uso de Postman, puede configurar una configuración de aplicación opcional :

  • AuthenticationEvents__CustomCallerAppId : el guid del cliente deseado. Si no se proporciona, 99045fe1-7639-4a75-9d4a-577b6ca3810f se supone.

Hacer que el desencadenador valide el token

En entornos o entornos locales que no están hospedados en el servicio Azure Functions, el desencadenador puede realizar la validación del token. Establezca la siguiente configuración de la aplicación en el archivo local.settings.json :

  • AuthenticationEvents__TenantId : el identificador de inquilino
  • AuthenticationEvents__AudienceAppId : el mismo valor que "Audiencia permitida" en la opción 1.
  • AuthenticationEvents__CustomCallerAppId (opcional): el guid del cliente deseado. Si no se proporciona, 99045fe1-7639-4a75-9d4a-577b6ca3810f se supone.

Archivo de ejemplo local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Sin validación de tokens

Si desea no autenticar el token durante el desarrollo local, establezca la siguiente configuración de aplicación en el archivo local.settings.json :

  • AuthenticationEvents__BypassTokenValidation : el valor de true hará que el desencadenador no compruebe si hay una validación del token.

Inicio rápido

  • Visual Studio 2019

    • Inicio de Visual Studio
    • Seleccione "Crear un nuevo proyecto"
    • En el área de búsqueda de plantillas, busque "AzureAuthEventsTrigger".
    • Asigne al proyecto un nombre de proyecto significativo, ubicación, solución y nombre de solución.

  • Visual Studio Code

    • Inicie Visual Studio Code.
    • Ejecute el comando "Create Azure Authentication Events Trigger Project" (Crear proyecto de desencadenador de eventos de autenticación de Azure) mediante la paleta de comandos.
    • Siga las indicaciones de creación del proyecto.

  • Tenga en cuenta que, en una primera ejecución, puede tardar un tiempo en descargar los paquetes necesarios.

  • Para el turno de desarrollo de la validación de tokens para pruebas:

  • Agregue la clave de aplicación AuthenticationEvents__BypassTokenValidation a la sección "Valores" del archivo local.settings.json y establezca su valor en true. Si no tiene un archivo local.settings.json en el entorno local, cree uno en la raíz de la aplicación de funciones.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Una vez cargado el proyecto, puede ejecutar el código de ejemplo y verá que la aplicación del desarrollador de Azure Functions carga el punto de conexión.

Conceptos clave

.NET SDK

Puede encontrar los conceptos clave del SDK de .NET de Azure aquí.

Extensiones personalizadas de Azure AD

Las extensiones personalizadas permiten controlar eventos de Azure AD, integrarse con sistemas externos y personalizar lo que sucede en la experiencia de autenticación de aplicaciones. Por ejemplo, un proveedor de notificaciones personalizado es una extensión personalizada que permite enriquecer o personalizar tokens de aplicación con información de sistemas externos que no se pueden almacenar como parte del directorio de Azure AD.

Desencadenador de eventos de autenticación

El desencadenador de eventos de autenticación permite ejecutar una función cuando se envía un evento de autenticación desde el servicio de eventos de Azure AD.

Enlace de salida del desencadenador de eventos de autenticación

El enlace de salida del desencadenador de eventos de autenticación permite a una función enviar acciones de eventos de autenticación al servicio de eventos de Azure AD.

Documentación

  • Una de las funciones se ha publicado, hay algunas buenas lecturas sobre el registro y las métricas que se pueden encontrar aquí.

  • Para obtener documentación de API, consulte (Link TBD) (Vínculo TBD)

  • Una vez que esto se mueve a la versión preliminar, excepto que no hay cambios importantes y sería tan sencillo como quitar el origen de NuGet que apunta a la versión preliminar privada.

Ejemplos

Para probar el aumento de tokens, haga lo siguiente.

  • Inicie Visual Studio.
  • Abra el proyecto que se creó en el paso anterior. (Inicio rápido)
  • Ejecute la aplicación. (F5)
  • Una vez iniciada la aplicación del desarrollador de Azure Functions, copie la dirección URL de escucha que se muestra con el inicio de la aplicación.
  • Nota: Todas las funciones de autenticación se muestran en el caso de que tengamos un agente de escucha de función registrado denominado "OnTokenIssuanceStart".
  • El punto de conexión de la función será una combinación de la dirección URL y la función de escucha, por ejemplo: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)&function=OnTokenIssuanceStart"
  • Publique la siguiente carga con algo como Postman o Fiddler.
  • Se pueden encontrar los pasos para usar Postman (Link TBD)
{
  "type":"microsoft.graph.authenticationEvent.TokenIssuanceStart",
  "source":"/tenants/{tenantId}/applications/{resourceAppId}",
  "data":{
    "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
    "tenantId": "30000000-0000-0000-0000-000000000003",
    "authenticationEventListenerId1": "10000000-0000-0000-0000-000000000001",
    "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002",
    "authenticationContext1":{
      "correlationId": "20000000-0000-0000-0000-000000000002",
      "client": {
        "ip": "127.0.0.1",
        "locale": "en-us",
        "market": "en-au"
      },
      "authenticationProtocol": "OAUTH2.0",
      "clientServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000001",
        "appId": "40000000-0000-0000-0000-000000000002",
        "appDisplayName": "Test client app",
        "displayName": "Test client application"
      },
      "resourceServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000003",
        "appId": "40000000-0000-0000-0000-000000000004",
        "appDisplayName": "Test resource app",
        "displayName": "Test resource application"
      },
      "user": {
        "companyName": "Nick Gomez",
        "country": "USA",
        "createdDateTime": "0001-01-01T00:00:00Z",
        "displayName": "Dummy display name",
        "givenName": "Example",
        "id": "60000000-0000-0000-0000-000000000006",
        "mail": "test@example.com",
        "onPremisesSamAccountName": "testadmin",
        "onPremisesSecurityIdentifier": "DummySID",
        "onPremisesUserPrincipalName": "Dummy Name",
        "preferredDataLocation": "DummyDataLocation",
        "preferredLanguage": "DummyLanguage",
        "surname": "Test",
        "userPrincipalName": "testadmin@example.com",
        "userType": "UserTypeCloudManaged"
      }
    }
  }
}
  • Debería ver esta respuesta:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Solución de problemas

  • Visual Studio Code
    • Si se ejecuta en Visual Studio Code, obtendrá un error a lo largo de las líneas del emulador de Azure Storage local no está disponible, puede iniciar el emulador manualmente. (Nota: El emulador de Azure Storage ya está en desuso y el reemplazo sugerido es Azurite)
    • Si usa Visual Studio Code en Mac, use Azurite.
    • Si ve el siguiente error en Windows (es un error) al intentar ejecutar el proyecto creado.
    • Esto se puede resolver mediante la ejecución de este comando en PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine , puede encontrar más información sobre esto aquí y aquí

Pasos siguientes

Para más información sobre el SDK de Azure, consulte este sitio web.

Publicar

  • Siga las instrucciones que se indican aquí para crear y publicar el Aplicación de Azure. https://learn.microsoft.com/azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure
  • Para determinar el punto de conexión de publicación publicado, combine el punto de conexión de la función de Azure que creó, enrute al código de escucha y al código de escucha; para ello, vaya a la aplicación de funciones de Azure, seleccione "Claves de aplicación" y copie el valor de AuthenticationEvents_extension.
  • Por ejemplo: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart"
  • Asegúrese de que el entorno de producción tiene la configuración de aplicación correcta para la autenticación de tokens.
  • Una vez más, puede probar la función publicada publicando la carga anterior en el nuevo punto de conexión.

Contribuir

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.