Delen via

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

  • Artikel

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

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. Maak op de pagina Basisinformatie 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 6 (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.
    Plantype Verbruik (serverloos) Hostingabonnement dat definieert hoe resources worden toegewezen aan uw functie-app.

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

  6. 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. Laat in het venster Functie maken de eigenschap Ontwikkelomgeving staan als Ontwikkelen in de portal. Selecteer onder Sjabloon de HTTP-trigger.
  3. Voer onder Sjabloondetails CustomAuthenticationExtensionsAPI in voor de eigenschap Nieuwe functie.
  4. Selecteer Functie voor het autorisatieniveau.
  5. Selecteer Maken. Schermopname van het kiezen van de ontwikkelomgeving en de sjabloon.

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:

  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 6.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.

NuGet-pakketten installeren en het project bouwen

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

  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.

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.

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.

  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.

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.

  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.

Verificatie configureren voor uw Azure-functie

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

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 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.

Volgende stap

Een aangepaste claimprovidertokenuitgifte-gebeurtenis configureren