Een REST API maken voor een start-gebeurtenis voor tokenuitgifte in Azure Functions

In dit artikel wordt beschreven hoe u een REST API maakt met een tokenuitgifte-start-gebeurtenis met behulp van Azure Functions in Azure Portal. U maakt een Azure Function-app en een HTTP-triggerfunctie die extra claims voor uw token kan retourneren.

Vereisten

• Een basiskennis van de concepten die worden behandeld in het overzicht van aangepaste verificatie-extensies.
• Een Azure-abonnement met de mogelijkheid om Azure Functions te maken. Als u geen bestaand Azure-account hebt, meldt u zich aan voor een gratis proefversie of gebruikt u de voordelen van uw Visual Studio-abonnement wanneer u een account maakt.
• Een Microsoft Entra ID-tenant. U kunt een klant- of personeelstenant gebruiken voor deze handleiding.

In dit artikel wordt beschreven hoe u een REST API maakt voor een begingebeurtenis voor tokenuitgifte met behulp van de NuGet-bibliotheek Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents en deze instelt voor verificatie. U maakt een HTTP-triggerfunctie in Visual Studio of Visual Studio Code, configureert deze voor verificatie en implementeert deze in Azure Portal, waar deze kan worden geopend via Azure Functions.

Vereisten

• Een basiskennis van de concepten die worden behandeld in het overzicht van aangepaste verificatie-extensies.
• Een Azure-abonnement met de mogelijkheid om Azure Functions te maken. Als u geen bestaand Azure-account hebt, meldt u zich aan voor een gratis proefversie of gebruikt u de voordelen van uw Visual Studio-abonnement wanneer u een account maakt.
• Een Microsoft Entra ID-tenant. U kunt een klant- of personeelstenant gebruiken voor deze handleiding.
• Een van de volgende IDE's en configuraties:
  • Visual Studio met Azure Development-workload voor Visual Studio geconfigureerd.
  • Visual Studio Code, waarbij de Azure Functions-extensie is ingeschakeld.

Notitie

De NuGet-bibliotheek Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents is momenteel beschikbaar als preview-versie. Stappen in dit artikel zijn onderhevig aan wijzigingen. Voor de implementatie van algemene beschikbaarheid van het implementeren van een start-gebeurtenis voor tokenuitgifte kunt u dit doen met behulp van Azure Portal.

De Azure Function-app maken

Maak in Azure Portal een Azure Function-app en de bijbehorende resource voordat u de HTTP-triggerfunctie gaat maken.

1. Meld u aan bij Azure Portal als ten minste een toepassingsbeheerder en verificatiebeheerder.

2. Selecteer vanuit het menu van Azure Portal of op de startpagina de optie Een resource maken.

3. Zoek en selecteer Functie-app en selecteer Maken.

4. Selecteer Verbruik op de pagina Functie-app maken en selecteer vervolgens Selecteren.

5. Maak op de pagina Functie-app maken (Verbruik) op het tabblad Basisbeginselen een functie-app met behulp van de instellingen die zijn opgegeven in de volgende tabel:

   Instelling	Voorgestelde waarde	Beschrijving
   Abonnement	Uw abonnement	Het abonnement waaronder de nieuwe functie-app wordt gemaakt.
   Resourcegroep	myResourceGroup	Selecteer en de bestaande resourcegroep of geef een naam op voor de nieuwe resourcegroep waarin u uw functie-app gaat maken.
   Naam van de functie-app	Wereldwijd unieke naam	Een naam die de nieuwe functie-app identificeert. Geldige tekens zijn a-z (niet hoofdlettergevoelig), 0-9 en -.
   Code of containerinstallatiekopieën implementeren	Code	Optie voor het publiceren van codebestanden of een Docker-container. Voor deze zelfstudie selecteert u Code.
   Runtimestack	.NET	Uw favoriete programmeertaal. Voor deze zelfstudie selecteert u .NET.
   Versie	8 (LTS) In-process	Versie van de .NET-runtime. In-process geeft aan dat u functies in de portal kunt maken en wijzigen. Dit wordt aanbevolen voor deze handleiding
   Regio	Voorkeursregio	Selecteer een regio in de buurt of in de buurt van andere services waartoe uw functies toegang hebben.
   Besturingssysteem	Windows	Het besturingssysteem is vooraf geselecteerd op basis van uw runtimestackselectie.

   

6. Selecteer Beoordelen en maken om de app-configuratieselecties te controleren en selecteer vervolgens Maken. De implementatie duurt een paar minuten.

7. Nadat de resource is geïmplementeerd, selecteert u Ga naar de resource om uw nieuwe functie-app weer te geven.

Een HTTP-triggerfunctie maken

Nadat de Azure Function-app is gemaakt, maakt u een HTTP-triggerfunctie in de app. Met de HTTP-trigger kunt u een functie aanroepen met een HTTP-aanvraag en waarnaar wordt verwezen door de aangepaste verificatie-extensie van Microsoft Entra.

1. Selecteer op de pagina Overzicht van uw functie-app het deelvenster Functies en selecteer Functie maken onder Maken in Azure Portal.
2. Selecteer in het venster Functie maken het type HTTP-triggerfunctie en selecteer Volgende.
3. Voer onder Sjabloondetails CustomAuthenticationExtensionsAPI in voor de eigenschap Functienaam, en selecteer Functie als autorisatieniveau.
4. Selecteer Maken.

De functie bewerken

De code leest het binnenkomende JSON-object en Microsoft Entra-id verzendt het JSON-object naar uw API. In dit voorbeeld wordt de correlatie-id-waarde gelezen. Vervolgens retourneert de code een verzameling aangepaste claims, waaronder het origineel CorrelationId, de ApiVersion Azure-functie, een DateOfBirth en CustomRoles die wordt geretourneerd naar Microsoft Entra-id.

1. Selecteer Code + Test in het menu onder Ontwikkelaars.

2. Vervang de volledige code door het volgende codefragment en selecteer Opslaan.

   #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. Selecteer in het bovenste menu Functie-URL ophalen en kopieer de URL-waarde . Deze functie-URL kan worden gebruikt bij het instellen van een aangepaste verificatie-extensie.

De Azure Function-app maken en bouwen

In deze stap maakt u een HTTP-triggerfunctie-API met behulp van uw IDE, installeert u de vereiste NuGet-pakketten en kopieert u deze in de voorbeeldcode. U bouwt het project en voert de functie uit om de URL van de lokale functie te extraheren.

De toepassing maken

Voer de volgende stappen uit om een Azure Function-app te maken:

Visual Studio

1. Open Visual Studio en selecteer Een nieuw project maken.
2. Zoek en selecteer Azure Functions en selecteer vervolgens Volgende.
3. Geef het project een naam, zoals AuthEventsTrigger. Het is een goed idee om de naam van de oplossing te vergelijken met de projectnaam.
4. Selecteer een locatie voor het project. Selecteer Volgende.
5. Selecteer .NET 8.0 (Langetermijnondersteuning) als doelframework.
6. Selecteer Http-trigger als het functietype en dat autorisatieniveau is ingesteld op Functie. Selecteer Maken.
7. Wijzig in Solution Explorer de naam van het Function1.cs-bestand in AuthEventsTrigger.cs en accepteer de suggestie voor het wijzigen van de naam.

Visual Studio Code

1. Open Visual Studio Code.

2. Selecteer het pictogram Nieuwe map in het Verkenner-venster en maak een nieuwe map voor uw project, bijvoorbeeld AuthEventsTrigger.

3. Selecteer het Azure-extensiepictogram aan de linkerkant van het scherm. Meld u aan bij uw Azure-account als u dat nog niet hebt gedaan.

4. Selecteer onder de werkruimtebalk het pictogram >Nieuw project maken in Azure Functions.

   

5. Selecteer in de bovenste balk de locatie om het project te maken.

6. Selecteer C# als taal en .NET 6.0 LTS als .NET-runtime.

7. Selecteer DE HTTP-trigger als de sjabloon.

8. Geef een naam op voor het project, zoals AuthEventsTrigger.

9. Accepteer Company.Function als naamruimte, waarbij AccessRights is ingesteld op Functie.

NuGet-pakketten installeren en het project bouwen

Nadat u het project hebt gemaakt, moet u de vereiste NuGet-pakketten installeren en het project bouwen.

Visual Studio

1. Selecteer Project in het bovenste menu van Visual Studio en vervolgens NuGet-pakketten beheren.
2. Selecteer het tabblad Bladeren en zoek en selecteer Vervolgens Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents in het rechterdeelvenster. Selecteer Installeren.
3. Pas de wijzigingen toe en accepteer deze in de pop-ups die worden weergegeven.

Visual Studio Code

1. Open de Terminal in Visual Studio Code en navigeer naar de projectmap.

2. Voer de volgende opdracht in de console in om het NuGet-pakket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents te installeren.

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

De voorbeeldcode toevoegen

De functie-API is de bron van extra claims voor uw token. Voor het doel van dit artikel coderen we de waarden voor de voorbeeld-app. In productie kunt u informatie over de gebruiker ophalen uit het externe gegevensarchief. Raadpleeg de Klasse WebJobsAuthenticationEventsContext voor bestaande eigenschappen.

Vervang in het AuthEventsTrigger.cs bestand de volledige inhoud van het bestand door de volgende code:

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);
            }
        }
    }
}

Het project lokaal bouwen en uitvoeren

Het project is gemaakt en de voorbeeldcode is toegevoegd. Met behulp van uw IDE moeten we het project lokaal bouwen en uitvoeren om de URL van de lokale functie te extraheren.

Visual Studio

1. Navigeer naar Build in het bovenste menu en selecteer Build Solution.
2. Druk op F5 of selecteer AuthEventsTrigger in het bovenste menu om de functie uit te voeren.
3. Kopieer de functie-URL vanuit de terminal die wordt weergegeven bij het uitvoeren van de functie. Dit kan worden gebruikt bij het instellen van een aangepaste verificatie-extensie.

Visual Studio Code

1. Selecteer in het bovenste menu Run>Start Debugging of druk op F5 om de functie uit te voeren.
2. Kopieer in de terminal de functie-URL die wordt weergegeven. Dit kan worden gebruikt bij het instellen van een aangepaste verificatie-extensie.

De functie lokaal uitvoeren (aanbevolen)

Het is een goed idee om de functie lokaal te testen voordat u deze implementeert in Azure. We kunnen een dummy JSON-hoofdtekst gebruiken die de aanvraag imiteert die door Microsoft Entra-id naar uw REST API wordt verzonden. Gebruik het hulpprogramma voor API-testen van uw voorkeur om de functie rechtstreeks aan te roepen.

1. Open in uw IDE local.settings.json en vervang de code door de volgende JSON. We kunnen dit instellen "AuthenticationEvents__BypassTokenValidation" true voor lokale testdoeleinden.

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

2. Maak met behulp van uw favoriete API-testprogramma een nieuwe HTTP-aanvraag en stel de HTTP-methode in op POST.

3. Gebruik de volgende JSON-hoofdtekst die de aanvraag imiteert die microsoft Entra-id naar uw REST API verzendt.

   {
       "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. Selecteer Verzenden en u moet een JSON-antwoord ontvangen dat er ongeveer als volgt uitziet:

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

De functie implementeren en publiceren naar Azure

De functie moet worden geïmplementeerd in Azure met behulp van onze IDE. Controleer of u correct bent aangemeld bij uw Azure-account, zodat de functie kan worden gepubliceerd.

Visual Studio

1. Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Publiceren.

2. Selecteer Azure in Target en selecteer Vervolgens.

3. Selecteer De Azure-functie-app (Windows) voor het specifieke doel, selecteer Azure Function-app (Windows) en selecteer vervolgens Volgende.

4. Gebruik in het functie-exemplaar de vervolgkeuzelijst Abonnementsnaam om het abonnement te selecteren waarin de nieuwe functie-app wordt gemaakt.

5. Selecteer waar u de nieuwe functie-app wilt publiceren en selecteer Nieuwe maken.

6. Gebruik op de pagina Functie-app (Windows) de instellingen van de functie-app zoals opgegeven in de volgende tabel en selecteer Vervolgens Maken.

   Instelling	Voorgestelde waarde	Omschrijving
   Naam	Wereldwijd unieke naam	Een naam die de nieuwe functie-app identificeert. Geldige tekens zijn a-z (niet hoofdlettergevoelig), 0-9 en -.
   Abonnement	Uw abonnement	Het abonnement waaronder de nieuwe functie-app wordt gemaakt.
   Resourcegroep	myResourceGroup	Selecteer een bestaande resourcegroep of geef de nieuwe de naam waarin u uw functie-app maakt.
   Plantype	Verbruik (serverloos)	Hostingabonnement dat definieert hoe resources worden toegewezen aan uw functie-app.
   Location	Voorkeursregio	Selecteer een regio in de buurt of in de buurt van andere services waartoe uw functies toegang hebben.
   Azure Storage	Uw opslagaccount	Er is een Azure-opslagaccount vereist voor de Functions-runtime. Selecteer Nieuw om een algemeen opslagaccount te configureren.
   Application Insights	Standaard	Een functie van Azure Monitor. Dit wordt automatisch geselecteerd, selecteer de optie die u wilt gebruiken of een nieuwe wilt configureren.

7. Wacht even totdat uw functie-app is geïmplementeerd. Zodra het venster is gesloten, selecteert u Voltooien.

8. Er wordt een nieuw deelvenster Publiceren geopend. Selecteer Bovenaan publiceren. Wacht enkele minuten totdat uw functie-app is geïmplementeerd en wordt weergegeven in Azure Portal.

Visual Studio Code

1. Selecteer het pictogram van de Azure-extensie . Selecteer in Resources het + pictogram om een resource te maken.
2. Selecteer Functie-app maken in Azure. Gebruik de volgende instellingen voor het instellen van uw functie-app.
3. Geef de functie-app een naam, zoals AuthEventsTriggerNuGet, en druk op Enter.
4. Selecteer de runtimestack voor .NET 6 (LTS) In-Process .
5. Selecteer een locatie voor de functie-app, zoals VS - oost.
6. Wacht enkele minuten totdat uw functie-app is geïmplementeerd en wordt weergegeven in Azure Portal.

Verificatie configureren voor uw Azure-functie

Er zijn drie manieren om verificatie in te stellen voor uw Azure-functie:

• Verificatie instellen in Azure Portal met behulp van omgevingsvariabelen (aanbevolen)
• Verificatie instellen in uw code met behulp van WebJobsAuthenticationEventsTriggerAttribute
• Azure-app serviceverificatie en -autorisatie

De code is standaard ingesteld voor verificatie in Azure Portal met behulp van omgevingsvariabelen. Gebruik de onderstaande tabbladen om uw voorkeursmethode voor het implementeren van omgevingsvariabelen te selecteren, of raadpleeg de ingebouwde Azure-app serviceverificatie en -autorisatie. Gebruik de volgende waarden voor het instellen van omgevingsvariabelen:

Naam	Weergegeven als
AuthenticationEvents__AudienceAppId	App-id voor aangepaste verificatie-extensie die is ingesteld in Een aangepaste claimprovider configureren voor een tokenuitgifte-gebeurtenis
AuthenticationEvents__AuthorityUrl	• Personeelstenant https://login.microsoftonline.com/<tenantID> • Externe tenant https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f of een andere geautoriseerde partij

Verificatie instellen in Azure Portal

Verificatie instellen in Azure Portal met behulp van omgevingsvariabelen

1. Meld u aan bij Azure Portal als ten minste een toepassingsbeheerder of verificatiebeheerder.
2. Navigeer naar de functie-app die u hebt gemaakt en selecteer onder Instellingen de optie Configuratie.
3. Selecteer onder Toepassingsinstellingen de optie Nieuwe toepassingsinstelling en voeg de omgevingsvariabelen uit de tabel en de bijbehorende waarden toe.
4. Selecteer Opslaan om de toepassingsinstellingen op te slaan.

Verificatie instellen in uw code

Verificatie instellen in uw code met behulp van WebJobsAuthenticationEventsTriggerAttribute

1. Open het bestand AuthEventsTrigger.cs in uw IDE.
2. Wijzig de WebJobsAuthenticationEventsTriggerAttribute AuthorityUrlAudienceAppId insluiting en AuthorizedPartyAppId eigenschappen, zoals wordt weergegeven in het onderstaande fragment.

    [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)

Volgende stap

Een aangepaste claimprovidertokenuitgifte-gebeurtenis configureren