Skapa ett REST API för en starthändelse för tokenutfärding i Azure Functions

Den här artikeln beskriver hur du skapar ett REST API med en starthändelse för tokenutfärdning med hjälp av Azure Functions i Azure Portal. Du skapar en Azure-funktionsapp och en HTTP-utlösarfunktion som kan returnera extra anspråk för din token.

Förutsättningar

• En grundläggande förståelse av de begrepp som beskrivs i översikten över anpassade autentiseringstillägg.
• En Azure-prenumeration med möjlighet att skapa Azure Functions. Om du inte har ett befintligt Azure-konto registrerar du dig för en kostnadsfri utvärderingsversion eller använder dina Visual Studio-prenumerationsförmåner när du skapar ett konto.
• En Microsoft Entra-ID-klientorganisation. Du kan använda antingen en kund- eller personalklientorganisation för den här instruktionsguiden.

Den här artikeln beskriver hur du skapar ett REST API för en starthändelse för tokenutfärdande med hjälp av NuGet-biblioteket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents och konfigurerar det för autentisering. Du skapar en HTTP-utlösarfunktion i Visual Studio eller Visual Studio Code, konfigurerar den för autentisering och distribuerar den till Azure Portal, där den kan nås via Azure Functions.

Förutsättningar

• En grundläggande förståelse av de begrepp som beskrivs i översikten över anpassade autentiseringstillägg.
• En Azure-prenumeration med möjlighet att skapa Azure Functions. Om du inte har ett befintligt Azure-konto registrerar du dig för en kostnadsfri utvärderingsversion eller använder dina Visual Studio-prenumerationsförmåner när du skapar ett konto.
• En Microsoft Entra-ID-klientorganisation. Du kan använda antingen en kund- eller personalklientorganisation för den här instruktionsguiden.
• Något av följande IDE:er och konfigurationer:
  • Visual Studio med Azure Development-arbetsbelastning för Visual Studio konfigurerad.
  • Visual Studio Code med Azure Functions-tillägget aktiverat.

Kommentar

NuGet-biblioteket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents finns för närvarande i förhandsversion. Steg i den här artikeln kan komma att ändras. För implementering av allmän tillgänglighet för implementering av en starthändelse för tokenutfärdning kan du göra det med hjälp av Azure Portal.

Skapa Azure-funktionsappen

I Azure Portal skapar du en Azure-funktionsapp och dess associerade resurs innan du fortsätter att skapa funktionen HTTP-utlösare.

1. Logga in på Azure Portal som minst programadministratör och autentiseringsadministratör.

2. I menyn i Azure-portalen eller på sidan Start väljer du Skapa en resurs.

3. Sök efter och välj Funktionsapp och välj Skapa.

4. På sidan Skapa funktionsapp väljer du Förbrukning och sedan Välj.

5. På sidan Skapa funktionsapp (förbrukning) på fliken Grundläggande skapar du en funktionsapp med inställningarna som anges i följande tabell:

   Inställning	Föreslaget värde	beskrivning
   Abonnemang	Din prenumeration	Prenumerationen under vilken den nya funktionsappen ska skapas.
   Resursgrupp	myResourceGroup	Välj och befintlig resursgrupp eller namn på den nya där du skapar funktionsappen.
   Funktionsappens namn	Globalt unikt namn	Ett namn som identifierar den nya funktionsappen. Giltiga tecken är a-z (skiftlägesokänsligt), 0-9 och -.
   Distribuera kod eller containeravbildning	Kod	Alternativ för att publicera kodfiler eller en Docker-container. I den här självstudien väljer du Kod.
   Körningsstack	.NET	Önskat programmeringsspråk. I den här självstudien väljer du .NET.
   Version:	8 (LTS) i processen	Version av .NET-körningen. Processen innebär att du kan skapa och ändra funktioner i portalen, vilket rekommenderas för den här guiden
   Region	Önskad region	Välj en region som är nära dig eller nära andra tjänster som dina funktioner kan komma åt.
   Operativsystem	Windows	Operativsystemet är förvalt baserat på valet av körningsstack.

   

6. Välj Granska + skapa för att granska appkonfigurationsvalen och välj sedan Skapa. Distributionen tar några minuter.

7. När du har distribuerat väljer du Gå till resurs för att visa din nya funktionsapp.

Skapa en HTTP-utlösarfunktion

När Azure-funktionsappen har skapats skapar du en HTTP-utlösarfunktion i appen. Med HTTP-utlösaren kan du anropa en funktion med en HTTP-begäran och refereras av ditt anpassade Microsoft Entra-autentiseringstillägg.

1. På sidan Översikt i funktionsappen väljer du fönstret Funktioner och väljer Skapa funktion under Skapa i Azure Portal.
2. I fönstret Skapa funktion väljer du funktionstypen HTTP-utlösare och väljer Nästa.
3. Under Mallinformation anger du CustomAuthenticationExtensionsAPI för egenskapen Funktionsnamn och väljer Funktion som auktoriseringsnivå.
4. Välj Skapa.

Redigera funktionen

Koden läser det inkommande JSON-objektet och Microsoft Entra-ID skickar JSON-objektet till ditt API. I det här exemplet läss korrelations-ID-värdet. Sedan returnerar koden en samling anpassade anspråk, inklusive den ursprungliga CorrelationId, ApiVersion azure-funktionens, en DateOfBirth och CustomRoles som returneras till Microsoft Entra-ID.

1. På menyn under Utvecklare väljer du Kod + Test.

2. Ersätt hela koden med följande kodfragment och välj sedan Spara.

   #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. På den översta menyn väljer du Hämta funktions-URL och kopierar URL-värdet . Den här funktions-URL:en kan användas när du konfigurerar ett anpassat autentiseringstillägg.

Skapa och skapa Azure-funktionsappen

I det här steget skapar du ett HTTP-utlösarfunktions-API med din IDE, installerar nödvändiga NuGet-paket och kopierar i exempelkoden. Du skapar projektet och kör funktionen för att extrahera den lokala funktions-URL:en.

Skapa programmet

Följ dessa steg för att skapa en Azure-funktionsapp:

Visual Studio

1. Öppna Visual Studio och välj Skapa ett nytt projekt.
2. Sök efter och välj Azure Functions och välj sedan Nästa.
3. Ge projektet ett namn, till exempel AuthEventsTrigger. Det är en bra idé att matcha lösningsnamnet med projektnamnet.
4. Välj en plats för projektet. Välj Nästa.
5. Välj .NET 8.0 (långsiktig support) som målramverk.
6. Välj Http-utlösare som funktionstyp och auktoriseringsnivån är inställd på Funktion. Välj Skapa.
7. I Solution Explorer byter du namn på filen Function1.cs till AuthEventsTrigger.cs och godkänner ändringsförslaget för byt namn.

Visual Studio Code

1. Öppna Visual Studio Code.

2. Välj ikonen Ny mapp i utforskarfönstret och skapa en ny mapp för projektet, till exempel AuthEventsTrigger.

3. Välj Azure-tilläggsikonen till vänster på skärmen. Logga in på ditt Azure-konto om du inte redan har gjort det.

4. Under fältet Arbetsyta väljer du Azure Functions-ikonen >Skapa nytt projekt.

   

5. I det övre fältet väljer du platsen för att skapa projektet.

6. Välj C# som språk och .NET 6.0 LTS som .NET-körning.

7. Välj HTTP-utlösare som mall.

8. Ange ett namn för projektet, till exempel AuthEventsTrigger.

9. Acceptera Company.Function som namnrymd med AccessRights inställt på Funktion.

Installera NuGet-paket och skapa projektet

När du har skapat projektet måste du installera nödvändiga NuGet-paket och skapa projektet.

Visual Studio

1. På den översta menyn i Visual Studio väljer du Projekt och sedan Hantera NuGet-paket.
2. Välj fliken Bläddra och sök sedan efter och välj Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents i den högra rutan. Välj Installera.
3. Använd och acceptera ändringarna i popup-fönster som visas.

Visual Studio Code

1. Öppna terminalen i Visual Studio Code och gå till projektmappen.

2. Ange följande kommando i konsolen för att installera NuGet-paketet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents .

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

Lägga till exempelkoden

Funktions-API:et är källan till extra anspråk för din token. I den här artikeln hårdkodar vi värdena för exempelappen. I produktion kan du hämta information om användaren från ett externt datalager. Se klassen WebJobsAuthenticationEventsContext för befintliga egenskaper.

I filen AuthEventsTrigger.cs ersätter du hela innehållet i filen med följande kod:

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

Skapa och köra projektet lokalt

Projektet har skapats och exempelkoden har lagts till. Med din IDE måste vi skapa och köra projektet lokalt för att extrahera den lokala funktions-URL:en.

Visual Studio

1. Gå till Skapa på den översta menyn och välj Skapa lösning.
2. Tryck på F5 eller välj AuthEventsTrigger på den översta menyn för att köra funktionen.
3. Kopiera funktions-URL :en från terminalen som öppnas när funktionen körs. Detta kan användas när du konfigurerar ett anpassat autentiseringstillägg.

Visual Studio Code

1. På den översta menyn väljer du Kör>Starta felsökning eller trycker på F5 för att köra funktionen.
2. I terminalen kopierar du funktions-URL :en som visas. Detta kan användas när du konfigurerar ett anpassat autentiseringstillägg.

Kör funktionen lokalt (rekommenderas)

Det är en bra idé att testa funktionen lokalt innan du distribuerar den till Azure. Vi kan använda en dummy-JSON-brödtext som imiterar den begäran som Microsoft Entra-ID skickar till ditt REST-API. Använd önskat API-testverktyg för att anropa funktionen direkt.

1. Öppna local.settings.json i din IDE och ersätt koden med följande JSON. Vi kan ange "AuthenticationEvents__BypassTokenValidation" till true för lokala teständamål.

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

2. Använd det API-testverktyg du föredrar, skapa en ny HTTP-begäran och ange HTTP-metoden till POST.

3. Använd följande JSON-brödtext som imiterar den begäran som Microsoft Entra-ID skickar till rest-API:et.

   {
       "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. Välj Skicka och du bör få ett JSON-svar som liknar följande:

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

Distribuera funktionen och publicera till Azure

Funktionen måste distribueras till Azure med vår IDE. Kontrollera att du är korrekt inloggad på ditt Azure-konto så att funktionen kan publiceras.

Visual Studio

1. Högerklicka på projektet i Solution Explorer och välj Publicera.

2. I Mål väljer du Azure och sedan Nästa.

3. Välj Azure Function App (Windows) för Det specifika målet, välj Azure Function App (Windows) och välj sedan Nästa.

4. I funktionsinstansen använder du listrutan Prenumerationsnamn för att välja den prenumeration under vilken den nya funktionsappen ska skapas.

5. Välj var du vill publicera den nya funktionsappen och välj Skapa ny.

6. På sidan Funktionsapp (Windows) använder du inställningarna för funktionsappen som anges i följande tabell och väljer sedan Skapa.

   Inställning	Föreslaget värde	Description
   Namn	Globalt unikt namn	Ett namn som identifierar den nya funktionsappen. Giltiga tecken är a-z (skiftlägesokänsligt), 0-9 och -.
   Abonnemang	Din prenumeration	Prenumerationen under vilken den nya funktionsappen skapas.
   Resursgrupp	myResourceGroup	Välj en befintlig resursgrupp eller ge den nya namnet där du skapar funktionsappen.
   Plantyp	Förbrukning (serverlös)	Värdplan som definierar hur resurser allokeras till din funktionsapp.
   Plats	Önskad region	Välj en region som är nära dig eller nära andra tjänster som dina funktioner kan komma åt.
   Azure Storage	Ditt lagringskonto	Azure Functions-körmiljön kräver ett Azure Storage-konto. Välj Ny för att konfigurera ett allmänt lagringskonto.
   Application Insights	Standardvärde	En funktion i Azure Monitor. Detta är automatiskt markerat, välj den som du vill använda eller konfigurera en ny.

7. Vänta en stund tills funktionsappen har distribuerats. När fönstret har stängts väljer du Slutför.

8. Ett nytt publiceringsfönster öppnas. Längst upp väljer du Publicera. Vänta några minuter tills funktionsappen har distribuerats och visas i Azure Portal.

Visual Studio Code

1. Välj azure-tilläggsikonen. I Resurser väljer du + ikonen för att skapa en resurs.
2. Välj Skapa funktionsapp i Azure. Använd följande inställningar för att konfigurera funktionsappen.
3. Ge funktionsappen ett namn, till exempel AuthEventsTriggerNuGet, och tryck på Retur.
4. Välj .NET 6 -stacken (LTS) In-Process runtime.
5. Välj en plats för funktionsappen, till exempel USA, östra.
6. Vänta några minuter tills funktionsappen har distribuerats och visas i Azure Portal.

Konfigurera autentisering för din Azure-funktion

Det finns tre sätt att konfigurera autentisering för din Azure-funktion:

• Konfigurera autentisering i Azure Portal med hjälp av miljövariabler (rekommenderas)
• Konfigurera autentisering i koden med hjälp av WebJobsAuthenticationEventsTriggerAttribute
• Autentisering och auktorisering för Azure App Service

Som standard har koden konfigurerats för autentisering i Azure Portal med hjälp av miljövariabler. Använd flikarna nedan för att välja önskad metod för att implementera miljövariabler, eller också kan du läsa den inbyggda Azure App Service-autentiseringen och auktoriseringen. Använd följande värden för att konfigurera miljövariabler:

Name	Värde
AuthenticationEvents__AudienceAppId	App-ID för anpassat autentiseringstillägg som har konfigurerats i Konfigurera en anpassad anspråksprovider för en tokenutfärdarhändelse
AuthenticationEvents__AuthorityUrl	• Personalklientorganisation https://login.microsoftonline.com/<tenantID> • Extern klientorganisation https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f eller någon annan behörig part

Konfigurera autentisering i Azure Portal

Konfigurera autentisering i Azure Portal med hjälp av miljövariabler

1. Logga in på Azure Portal som minst programadministratör eller autentiseringsadministratör.
2. Gå till funktionsappen som du skapade och välj Konfiguration under Inställningar.
3. Under Programinställningar väljer du Ny programinställning och lägger till miljövariablerna från tabellen och deras associerade värden.
4. Välj Spara för att spara programinställningarna.

Konfigurera autentisering i koden

Konfigurera autentisering i koden med hjälp av WebJobsAuthenticationEventsTriggerAttribute

1. Öppna filen AuthEventsTrigger.cs i din IDE.
2. WebJobsAuthenticationEventsTriggerAttribute Ändra inkludera AuthorityUrlegenskaperna , AudienceAppId och AuthorizedPartyAppId som visas i kodfragmentet nedan.

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

Gå vidare

Konfigurera en tokenutfärdingshändelse för en anpassad anspråksprovider