Déclencheur d’événements d’authentification pour Azure Functions bibliothèque cliente pour Node

Article
04/05/2023

Le déclencheur d’événement d’authentification pour Azure Functions gère tout le traitement back-end (par exemple, validation de schéma jeton/json) pour les requêtes Http entrantes pour les événements d’authentification. Et fournit au développeur un modèle objet fortement typé et versionné à utiliser, ce qui signifie que le développeur n’a pas besoin de connaître au préalable les charges utiles json de la requête et de la réponse.

Cette infrastructure de projet fournit les fonctionnalités suivantes :

Validation de jeton pour la sécurisation de l’appel d’API
Modèle objet, saisie et intellisense IDE
Validation entrante et sortante des schémas de requête et de réponse d’API
Gestion de version
Pas besoin de code réutilisable.

Prise en main

Installer le package npm

npm install @azure/functions-authentication-events

Prérequis

Outils de fonction Azure
Azure Function Core Tools
Si vous utilisez Visual Studio Code, les extensions suivantes :
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Authentifier le client

Lorsque le service d’événements d’authentification Azure AD appelle votre extension personnalisée, il envoie un Authorization en-tête avec un Bearer {token}. Ce jeton représente un service pour l’authentification dans laquelle :

La « ressource », également appelée audience, est l’application que vous inscrivez pour représenter votre API. Cela est représenté par la aud revendication dans le jeton.
Le « client » est une application Microsoft qui représente le service d’événements d’authentification Azure AD. Elle a la appId99045fe1-7639-4a75-9d4a-577b6ca3810fvaleur . Ceci est représenté par :
- Revendication azp dans le jeton si votre propriété d’application accessTokenAcceptedVersion a la valeur 2.
- Revendication appid dans le jeton si la propriété de votre application de accessTokenAcceptedVersion ressources a la 1 valeur ou null.

Il existe trois approches pour traiter le jeton. Vous pouvez personnaliser le comportement à l’aide des paramètres d’application comme indiqué ci-dessous ou via le fichier local.settings.json dans les environnements locaux.

Valider des jetons à l’aide de Azure Functions’intégration de l’authentification Azure AD

Lors de l’exécution de votre fonction en production, il est vivement recommandé d’utiliser l’intégration d’authentification Azure Functions Azure AD pour valider les jetons entrants.

Accédez à l’onglet « Authentification » de votre application de fonction
Cliquez sur « Ajouter un fournisseur d’identité »
Sélectionnez « Microsoft » comme fournisseur d’identité
Sélectionnez « Fournir les détails d’une inscription d’application existante »
Entrez le Application ID de l’application qui représente votre API dans Azure AD

L’émetteur et l’audience autorisée dépendent de la accessTokenAcceptedVersion propriété de votre application (se trouve dans le « Manifeste » de l’application).

Si la propriété a la accessTokenAcceptedVersion2valeur : 6. Définissez appId Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (')

Si la propriété a la accessTokenAcceptedVersion1 valeur ou null: 6. Définissez l’identificateurUri Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known as). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' si vous utilisez un nom de domaine personnalisé.

Par défaut, le déclencheur d’événement d’authentification valide que l’intégration de l’authentification de fonction Azure est configurée et qu’il case activée que le client dans le jeton est défini 99045fe1-7639-4a75-9d4a-577b6ca3810f sur (via les azp revendications ou appid dans le jeton).

Si vous souhaitez tester votre API sur un autre client qui n’est pas un service d’événements d’authentification Azure AD, comme l’utilisation de Postman, vous pouvez configurer un paramètre d’application facultatif :

AuthenticationEvents__CustomCallerAppId : le guid de votre client souhaité. S’il n’est pas fourni, 99045fe1-7639-4a75-9d4a-577b6ca3810f est supposé.

Faire valider le jeton par le déclencheur

Dans les environnements locaux ou les environnements qui ne sont pas hébergés dans le service Azure Function, le déclencheur peut effectuer la validation du jeton. Définissez les paramètres d’application suivants :

AuthenticationEvents__TenantId : votre ID de locataire
AuthenticationEvents__AudienceAppId : la même valeur que « Audience autorisée » dans l’option 1.
AuthenticationEvents__CustomCallerAppId (facultatif) : guid du client souhaité. S’il n’est pas fourni, 99045fe1-7639-4a75-9d4a-577b6ca3810f est supposé.

Un exemple de fichierlocal.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"
  }
}

Aucune validation de jeton

Si vous souhaitez ne pas authentifier le jeton en cours de développement local, définissez le paramètre d’application suivant :

AuthenticationEvents__BypassTokenValidation : la valeur de true rend le déclencheur non case activée pour une validation du jeton.

Démarrage rapide

Visual Studio Code
- Démarrer Visual Studio Code
- Exécuter la commande func init . --worker-runtime node terminal via la palette de commandes
- Exécuter la commande func new terminal via la palette de commandes
- Suivez les invites de création de projet
- Exécuter la commande npm install @azure/functions-authentication-events terminal via la palette de commandes
- Exécuter la commande npm install terminal via la palette de commandes
- Exécuter la commande npm run-script build terminal via la palette de commandes
À des fins de développement, tour de validation de jeton pour le test :
Ajoutez la clé d’application AuthenticationEvents__BypassTokenValidation à la section « Valeurs » du fichier local.settings.json et définissez sa valeur sur true. Si vous n’avez pas de fichier local.settings.json dans votre environnement local, créez-en un à la racine de votre application de fonction.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

Une fois le projet chargé, vous pouvez exécuter l’exemple de code et vous devez voir l’application du développeur Azure Functions charger votre point de terminaison.

Concepts clés

Les concepts clés du Kit de développement logiciel (SDK) Azure .NET sont disponibles ici.

Documentation

Une des fonctions a été publiée, il y a une bonne lecture sur la journalisation et les métriques qui peuvent être trouvées ici
Pour obtenir la documentation de l’API, consultez (Lien à déterminer)
Une fois que cela passe à l’aperçu, nous n’avons pas de modifications cassantes et serait aussi simple que de supprimer la source nuget qui pointe vers l’aperçu privé.

Exemples

Pour tester l’augmentation des jetons, procédez comme suit.

Ouvrez le projet qui a été créé à l’étape précédente. (Démarrage rapide)
Exécutez l’application. func host start
Une fois l’application du développeur Azure Functions démarrée, copiez l’URL d’écoute qui s’affiche avec le démarrage de l’application.
Remarque : toutes les fonctions d’authentification sont répertoriées, dans le cas où nous avons un écouteur de fonction inscrit appelé « OnTokenIssuanceStart »
Votre point de terminaison de fonction sera alors une combinaison de l’URL d’écoute et de la fonction, par exemple : «http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& ; function=OnTokenIssuanceStart »
Publiez la charge utile suivante à l’aide de quelque chose comme Postman ou Fiddler.
Vous trouverez les étapes d’utilisation de Postman (Lien à déterminer)

{
    "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"
            }
        }
    }
}

Vous devriez voir cette réponse :

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Dépannage

Visual Studio Code
- Si vous exécutez dans Visual Studio Code, vous obtenez une erreur du type de l’émulateur de stockage Azure local n’est pas disponible, vous pouvez démarrer l’émulateur manuellement. (Remarque : l’émulateur Stockage Azure est désormais déconseillé et le remplacement suggéré est Azurite)
- Si vous utilisez Visual Studio Code sur Mac, utilisez Azurite
- Si vous voyez l’erreur suivante sur Windows (il s’agit d’un bogue) lors de la tentative d’exécution du projet créé.
- Vous pouvez résoudre ce problème en exécutant cette commande dans PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine pour plus d’informations à ce sujet, cliquez ici et ici

Étapes suivantes

Pour plus d’informations sur le Kit de développement logiciel (SDK) Azure, consultez ce site web.

Publier

Suivez les instructions ci-dessous pour créer et publier votre Azure Application. </azure/azure-functions/functions-develop-vs ?tabs=in-process#publish-to-azure>
Pour déterminer votre point de terminaison de publication publié, combinez le point de terminaison de fonction Azure que vous avez créé, routez vers le code de l’écouteur et de l’écouteur. Vous pouvez trouver le code d’écoute en accédant à votre application de fonction Azure, en sélectionnant « Clés d’application » et en copiant la valeur de AuthenticationEvents_extension.
Par exemple : «https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& ; function=OnTokenIssuanceStart »
Assurez-vous que votre environnement de production dispose des paramètres d’application appropriés pour l’authentification par jeton.
Une fois de plus, vous pouvez tester la fonction publiée en publiant la charge utile ci-dessus sur le nouveau point de terminaison.

Contribution

Pour plus d’informations sur la contribution à ce dépôt, consultez le guide de contribution.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Partager via