Share via

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

  • Article

Le déclencheur d’événements d’authentification pour Azure Functions vous permet d’implémenter une extension personnalisée pour gérer les événements d’authentification Azure Active Directory (Azure AD). Le déclencheur d’événements d’authentification gère tout le traitement back-end des requêtes HTTP entrantes pour les événements d’authentification Azure AD et fournit au développeur :

  • 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

Prise en main

Installer le package

Installez le déclencheur d’événements d’authentification pour Azure Functions avec NuGet :

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

Prérequis

  • Abonnement Azure : Pour utiliser les services Azure, y compris Azure Functions, vous avez besoin d’un abonnement. Si vous ne disposez pas d’un compte Azure existant, vous pouvez vous inscrire à un essai gratuit ou utiliser les avantages de votre abonnement Visual Studio lorsque vous créez un compte.

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 à service d’authentification dans lequel :

  • 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 est définie sur 1 ou null.

Il existe trois approches pour authentifier les requêtes HTTP pour votre application de fonction et valider le jeton.

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. Définissez les paramètres d’application de fonction suivants.

  1. Accédez à l’onglet « Authentification » de votre application de fonction
  2. Cliquez sur « Ajouter un fournisseur d’identité »
  3. Sélectionnez « Microsoft » comme fournisseur d’identité
  4. Sélectionnez « Fournir les détails d’une inscription d’application existante »
  5. 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 dans le fichier local.settings.json :

  • 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 les paramètres d’application suivants dans le fichier local.settings.json :

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

Démarrage rapide

  • Visual Studio 2019

    • Démarrez Visual Studio
    • Sélectionnez « Créer un projet »
    • Dans la zone de recherche du modèle, recherchez et sélectionnez « AzureAuthEventsTrigger »
    • Donnez à votre projet un nom de projet, un emplacement, une solution et un nom de solution explicites.

  • Visual Studio Code

    • Démarrer Visual Studio Code
    • Exécutez la commande « Créer un projet de déclencheur d’événements d’authentification Azure » via la palette de commandes
    • Suivez les invites de création de projet

  • Notez que lors d’une première exécution, le téléchargement des packages requis peut prendre un certain temps.

  • À 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": "dotnet",
    "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

Kit de développement logiciel (SDK) .NET

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

Extensions personnalisées Azure AD

Les extensions personnalisées vous permettent de gérer les événements Azure AD, de s’intégrer à des systèmes externes et de personnaliser ce qui se passe dans votre expérience d’authentification d’application. Par exemple, un fournisseur de revendications personnalisées est une extension personnalisée qui vous permet d’enrichir ou de personnaliser des jetons d’application avec des informations provenant de systèmes externes qui ne peuvent pas être stockées dans le répertoire Azure AD.

Déclencheur d’événements d’authentification

Le déclencheur d’événements d’authentification permet d’exécuter une fonction lorsqu’un événement d’authentification est envoyé à partir du service d’événements Azure AD.

Les événements d’authentification déclenchent la liaison de sortie

La liaison de sortie des événements d’authentification permet à une fonction d’envoyer des actions d’événement d’authentification au service d’événements Azure AD.

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 à la préversion, 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.

  • Démarrez Visual Studio.
  • Ouvrez le projet qui a été créé à l’étape précédente. (Démarrage rapide)
  • Exécutez l’application. (F5)
  • 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/{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"
      }
    }
  }
}
  • 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, reportez-vous à ce site web.

Publier

  • Suivez les instructions ici pour créer et publier votre Azure Application. https://learn.microsoft.com/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, le code d’écoute est disponible 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 »
  • Vérifiez 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 ne devrez le faire qu’une seule fois sur tous les dépôts à l’aide de notre cla cla 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.