Compartir a través de

Desencadenador de eventos de autenticación para Azure Functions biblioteca cliente para Node

  • Artículo

El desencadenador de eventos de autenticación para Azure Functions controla todo el procesamiento de back-end (por ejemplo, la validación del esquema token/json) para las solicitudes Http entrantes para eventos de autenticación. Además, proporciona al desarrollador un modelo de objetos con control de versiones fuertemente tipado con el que trabajar, lo que significa que el desarrollador no necesita tener ningún conocimiento previo de las cargas json de solicitud y respuesta.

Este marco de proyecto proporciona las siguientes características:

  • 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
  • Control de versiones
  • No es necesario usar código reutilizable.

Introducción

Instalación del paquete npm

npm install @azure/functions-authentication-events

Requisitos previos

Autenticar el cliente

Cuando el servicio de eventos de autenticación de Azure AD llama a la extensión personalizada, enviará un Authorization encabezado con .Bearer {token} Este token representará un servicio a 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 tratar el token. Puede personalizar el comportamiento mediante la configuración de la aplicación como se muestra a continuación o a través del archivo local.settings.json en entornos locales.

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.

  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 se establece 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:

  • 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:

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

Inicio rápido

  • Visual Studio Code
    • Inicie Visual Studio Code.
    • Ejecutar el comando func init . --worker-runtime node de terminal a través de la paleta de comandos
    • Ejecutar el comando func new de terminal a través de la paleta de comandos
    • Siga las indicaciones de creación del proyecto.
    • Ejecutar el comando npm install @azure/functions-authentication-events de terminal a través de la paleta de comandos
    • Ejecutar el comando npm install de terminal a través de la paleta de comandos
    • Ejecutar el comando npm run-script build de terminal a través de la paleta de comandos
  • 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": "node",
    "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

Los conceptos clave del SDK de Azure .NET se pueden encontrar aquí.

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 pase a la versión preliminar, excepto que no haya 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.

  • Abra el proyecto que se creó en el paso anterior. (Inicio rápido)
  • Ejecute la aplicación. func host start
  • 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".
  • Después, 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/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}
  • 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. </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.

Contribuciones

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.