Vytvoření rozhraní REST API pro počáteční událost vystavení tokenu ve službě Azure Functions

Tento článek popisuje, jak vytvořit rozhraní REST API s událostí spuštění vystavení tokenu pomocí Azure Functions na webu Azure Portal. Vytvoříte aplikaci funkcí Azure a funkci triggeru HTTP, která může vrátit další deklarace identity pro váš token.

Požadavky

• Základní znalost konceptů popsaných v přehledu rozšíření vlastního ověřování
• Předplatné Azure s možností vytvářet azure Functions. Pokud nemáte existující účet Azure, zaregistrujte si bezplatnou zkušební verzi nebo při vytváření účtu využijte výhody předplatného sady Visual Studio.
• Tenant Microsoft Entra ID. K tomuto průvodci postupy můžete použít tenanta zákazníka nebo pracovní síly.

Tento článek popisuje, jak vytvořit rozhraní REST API pro událost spuštění vystavení tokenu pomocí knihovny NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents a nastavit ji pro ověřování. V sadě Visual Studio nebo Visual Studio Code vytvoříte funkci triggeru HTTP, nakonfigurujete ji pro ověřování a nasadíte ji na web Azure Portal, kde k ní budete mít přístup prostřednictvím Azure Functions.

Požadavky

• Základní znalost konceptů popsaných v přehledu rozšíření vlastního ověřování
• Předplatné Azure s možností vytvářet azure Functions. Pokud nemáte existující účet Azure, zaregistrujte si bezplatnou zkušební verzi nebo při vytváření účtu využijte výhody předplatného sady Visual Studio.
• Tenant Microsoft Entra ID. K tomuto průvodci postupy můžete použít tenanta zákazníka nebo pracovní síly.
• Jedna z následujících prostředí IDE a konfigurace:
  • Visual Studio s nakonfigurovanou úlohou Vývoj pro Azure pro Visual Studio
  • Visual Studio Code s povoleným rozšířením Azure Functions

Poznámka:

Knihovna NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents je aktuálně ve verzi Preview. Postup v tomto článku se může změnit. Pokud chcete implementovat obecnou dostupnost implementace počáteční události vystavení tokenu, můžete to provést pomocí webu Azure Portal.

Vytvoření aplikace Funkcí Azure

Na webu Azure Portal vytvořte aplikaci Azure Functions a její přidružený prostředek a teprve potom pokračujte vytvořením funkce triggeru HTTP.

1. Přihlaste se k webu Azure Portal jako alespoň správce aplikací a správce ověřování.

2. V nabídce webu Azure Portal nebo na domovské stránce vyberte Vytvořit prostředek.

3. Vyhledejte a vyberte Function App a vyberte Vytvořit.

4. Na stránce Vytvořit aplikaci funkcí vyberte Consumption a pak Vyberte.

5. Na stránce Vytvořit aplikaci funkcí (Consumption) na kartě Základy vytvořte aplikaci funkcí pomocí nastavení uvedených v následující tabulce:

   Nastavení	Navrhovaná hodnota	Popis
   Předplatné	Vaše předplatné	Předplatné, ve kterém se vytvoří nová aplikace funkcí.
   Skupina prostředků	myResourceGroup	Vyberte a existující skupinu prostředků nebo název nové skupiny prostředků, ve které vytvoříte aplikaci funkcí.
   Název aplikace funkcí	Globálně jedinečný název	Název, který identifikuje novou aplikaci funkcí. Platné znaky jsou a-z (bez rozlišování malých a velkých písmen), 0-9 a -.
   Nasazení kódu nebo image kontejneru	Kód	Možnost publikování souborů kódu nebo kontejneru Docker Pro účely tohoto kurzu vyberte Kód.
   Zásobník modulu runtime	.NET	Preferovaný programovací jazyk. Pro účely tohoto kurzu vyberte .NET.
   Verze	8 (LTS) V procesu	Verze modulu runtime .NET In-process signifies that you can create and modify functions in the portal, which is recommended for this guide
   Oblast	Upřednostňovaná oblast	Vyberte oblast, která je blízko vás nebo blízko jiných služeb, ke kterým mají vaše funkce přístup.
   Operační systém	Windows	Operační systém je předem vybraný na základě výběru zásobníku modulu runtime.

   

6. Výběrem možnosti Zkontrolovat a vytvořit zkontrolujte výběry konfigurace aplikace a pak vyberte Vytvořit. Nasazení trvá několik minut.

7. Po nasazení vyberte Přejít k prostředku a zobrazte novou aplikaci funkcí.

Vytvoření funkce triggeru HTTP

Po vytvoření aplikace Funkcí Azure vytvořte v aplikaci funkci triggeru HTTP. Trigger HTTP umožňuje vyvolat funkci s požadavkem HTTP a odkazuje na vás vaše rozšíření vlastního ověřování Microsoft Entra.

1. Na stránce Přehled aplikace funkcí vyberte podokno Funkce a v části Vytvořit na webu Azure Portal vyberte Vytvořit funkci.
2. V okně Vytvořit funkci vyberte typ funkce triggeru HTTP a vyberte Další.
3. V části Podrobnosti o šabloně zadejte CustomAuthenticationExtensionsAPI pro vlastnost Funkce název funkce a jako úroveň autorizace vyberte Funkci.
4. Vyberte Vytvořit.

Upravit funkci

Kód přečte příchozí objekt JSON a ID Microsoft Entra odešle objekt JSON do vašeho rozhraní API. V tomto příkladu načte hodnotu ID korelace. Pak kód vrátí kolekci přizpůsobených deklarací identity, včetně původní CorrelationIdApiVersion funkce Azure Functions a DateOfBirth která CustomRoles se vrátí do Microsoft Entra ID.

1. V nabídce v části Vývojář vyberte Kód + Test.

2. Celý kód nahraďte následujícím fragmentem kódu a pak vyberte Uložit.

   #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. V horní nabídce vyberte Získat adresu URL funkce a zkopírujte hodnotu adresy URL . Tuto adresu URL funkce lze použít při nastavování vlastního rozšíření ověřování.

Vytvoření a sestavení aplikace Azure Functions

V tomto kroku vytvoříte rozhraní API funkce triggeru HTTP pomocí integrovaného vývojového prostředí ( IDE), nainstalujete požadované balíčky NuGet a zkopírujete ho do ukázkového kódu. Projekt sestavíte a spustíte funkci pro extrahování adresy URL místní funkce.

Vytvoření aplikace

Pokud chcete vytvořit aplikaci Funkcí Azure, postupujte takto:

Visual Studio

1. Otevřete Visual Studio a vyberte Vytvořit nový projekt.
2. Vyhledejte a vyberte Azure Functions a pak vyberte Další.
3. Zadejte název projektu, například AuthEventsTrigger. Je vhodné se shodovat s názvem řešení s názvem projektu.
4. Vyberte umístění projektu. Vyberte Další.
5. Jako cílovou architekturu vyberte .NET 8.0 (dlouhodobá podpora ).
6. Jako typ funkce vyberte trigger HTTP a úroveň autorizace je nastavená na funkci. Vyberte Vytvořit.
7. V Průzkumník řešení přejmenujte soubor Function1.cs na AuthEventsTrigger.cs a přijměte návrh změny přejmenování.

Visual Studio Code

1. Otevřete Visual Studio Code.

2. V okně Průzkumníka vyberte ikonu Nová složka a vytvořte novou složku pro váš projekt, například AuthEventsTrigger.

3. Na levé straně obrazovky vyberte ikonu rozšíření Azure. Pokud jste to ještě neudělali, přihlaste se ke svému účtu Azure.

4. Na panelu pracovních prostorů vyberte ikonu >Azure Functions Vytvořit nový projekt.

   

5. V horním panelu vyberte umístění pro vytvoření projektu.

6. Jako jazyk vyberte C# a modul runtime .NET 6.0 LTS .

7. Jako šablonu vyberte trigger HTTP.

8. Zadejte název projektu, například AuthEventsTrigger.

9. Přijměte funkci Company.Function jako obor názvů s accessRights nastavenou na Funkci.

Instalace balíčků NuGet a sestavení projektu

Po vytvoření projektu budete muset nainstalovat požadované balíčky NuGet a sestavit projekt.

Visual Studio

1. V horní nabídce sady Visual Studio vyberte Projekt a pak spravovat balíčky NuGet.
2. Vyberte kartu Procházet a pak v pravém podokně vyhledejte a vyberte Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents. Vyberte volbu Instalovat.
3. Použijte a přijměte změny v automaticky otevírané nabídce, které se zobrazí.

Visual Studio Code

1. Otevřete terminál v editoru Visual Studio Code a přejděte do složky projektu.

2. Zadáním následujícího příkazu do konzoly nainstalujte balíček NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents .

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

Přidání vzorového kódu

Rozhraní API funkce je zdrojem dodatečných deklarací identity pro váš token. Pro účely tohoto článku pevně zakódujeme hodnoty ukázkové aplikace. V produkčním prostředí můžete načíst informace o uživateli z externího úložiště dat. Informace o existujících vlastnostech najdete ve třídě WebJobsAuthenticationEventsContext.

V souboru AuthEventsTrigger.cs nahraďte celý obsah souboru následujícím kódem:

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

Sestavení a místní spuštění projektu

Projekt byl vytvořen a byl přidán vzorový kód. Pomocí integrovaného vývojového prostředí (IDE) potřebujeme sestavit a spustit projekt místně, abychom extrahovali adresu URL místní funkce.

Visual Studio

1. V horní nabídce přejděte na Sestavení a vyberte Sestavit řešení.
2. Stisknutím klávesy F5 nebo výběrem AuthEventsTrigger v horní nabídce funkci spusťte.
3. Zkopírujte adresu URL funkce z terminálu, který se otevře při spuštění funkce. To se dá použít při nastavování vlastního rozšíření ověřování.

Visual Studio Code

1. V horní nabídce vyberte Spustit>ladění nebo stisknutím klávesy F5 funkci spusťte.
2. V terminálu zkopírujte adresu URL funkce, která se zobrazí. To se dá použít při nastavování vlastního rozšíření ověřování.

Místní spuštění funkce (doporučeno)

Před nasazením funkce do Azure je vhodné funkci otestovat místně. Můžeme použít fiktivní tělo JSON, které napodobuje požadavek, který Microsoft Entra ID odesílá do rozhraní REST API. K přímému volání funkce použijte preferovaný testovací nástroj rozhraní API.

1. V integrovaném vývojovém prostředí otevřete local.settings.json a nahraďte kód následujícím kódem JSON. Můžeme nastavit "AuthenticationEvents__BypassTokenValidation" pro true účely místního testování.

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

2. Pomocí preferovaného testovacího nástroje rozhraní API vytvořte nový požadavek HTTP a nastavte metodu HTTP na POST.

3. Použijte následující text JSON, který napodobuje požadavek Microsoft Entra ID odesílá do rozhraní REST API.

   {
       "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. Vyberte Odeslat a měli byste obdržet odpověď JSON podobnou této:

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

Nasazení funkce a publikování do Azure

Funkci je potřeba nasadit do Azure pomocí našeho integrovaného vývojového prostředí (IDE). Zkontrolujte, že jste ke svému účtu Azure správně přihlášení, abyste mohli funkci publikovat.

Visual Studio

1. V Průzkumník řešení klikněte pravým tlačítkem myši na projekt a vyberte Publikovat.

2. V části Cíl vyberte Azure a pak vyberte Další.

3. Vyberte aplikaci Funkcí Azure (Windows) pro konkrétní cíl, vyberte Aplikaci funkcí Azure (Windows) a pak vyberte Další.

4. V instanci funkce pomocí rozevíracího seznamu Název předplatného vyberte předplatné, ve kterém se vytvoří nová aplikace funkcí.

5. Vyberte, kam chcete novou aplikaci funkcí publikovat, a vyberte Vytvořit novou.

6. Na stránce Aplikace funkcí (Windows) použijte nastavení aplikace funkcí, jak je uvedeno v následující tabulce, a pak vyberte Vytvořit.

   Nastavení	Navrhovaná hodnota	Description
   Jméno	Globálně jedinečný název	Název, který identifikuje novou aplikaci funkcí. Platné znaky jsou a-z (bez rozlišování malých a velkých písmen), 0-9 a -.
   Předplatné	Vaše předplatné	Předplatné, pod kterým se vytvoří nová aplikace funkcí.
   Skupina prostředků	myResourceGroup	Vyberte existující skupinu prostředků nebo pojmenujte novou skupinu, ve které vytvoříte aplikaci funkcí.
   Typ plánu	Využití (bez serverů)	Plán Hosting, který určuje způsob přidělování prostředků aplikaci Function App.
   Místo	Upřednostňovaná oblast	Vyberte oblast, která je blízko vás nebo blízko jiných služeb, ke kterým mají vaše funkce přístup.
   Azure Storage	Váš účet úložiště	Modul runtime Functions vyžaduje účet úložiště Azure. Výběrem možnosti Nový nakonfigurujte účet úložiště pro obecné účely.
   Application Insights	Výchozí	Funkce služby Azure Monitor Toto je automaticky zaškrtnuto, vyberte ten, který chcete použít, nebo nakonfigurujte nový.

7. Chvíli počkejte, než se vaše aplikace funkcí nasadí. Po zavření okna vyberte Dokončit.

8. Otevře se nové podokno Publikování . Nahoře vyberte Publikovat. Počkejte několik minut, než se vaše aplikace funkcí nasadí a zobrazí se na webu Azure Portal.

Visual Studio Code

1. Vyberte ikonu rozšíření Azure. V části Prostředky vyberte + ikonu pro vytvoření prostředku.
2. Vyberte Vytvořit aplikaci funkcí v Azure. K nastavení aplikace funkcí použijte následující nastavení.
3. Pojmenujte aplikaci funkcí, například AuthEventsTriggerNuGet, a stiskněte Enter.
4. Vyberte zásobník modulu runtime v procesu .NET 6 (LTS).
5. Vyberte umístění aplikace funkcí, například USA – východ.
6. Počkejte několik minut, než se vaše aplikace funkcí nasadí a zobrazí se na webu Azure Portal.

Konfigurace ověřování pro funkci Azure Functions

Ověřování pro funkci Azure Functions můžete nastavit třemi způsoby:

• Nastavení ověřování na webu Azure Portal pomocí proměnných prostředí (doporučeno)
• Nastavení ověřování v kódu pomocí WebJobsAuthenticationEventsTriggerAttribute
• ověřování a autorizace služby Aplikace Azure

Ve výchozím nastavení je kód nastavený pro ověřování na webu Azure Portal pomocí proměnných prostředí. Pomocí karet níže vyberte upřednostňovanou metodu implementace proměnných prostředí nebo případně si projděte předdefinované ověřování a autorizaci služby Aplikace Azure. Pro nastavení proměnných prostředí použijte následující hodnoty:

Jméno	Hodnota
AuthenticationEvents__AudienceAppId	ID aplikace rozšíření vlastního ověřování, které je nastavené v části Konfigurace vlastního zprostředkovatele deklarací identity pro událost vystavení tokenu
AuthenticationEvents__AuthorityUrl	• Tenant pracovních sil https://login.microsoftonline.com/<tenantID> • Externí tenant https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f nebo jiná autorizovaná strana

Nastavení ověřování na webu Azure Portal

Nastavení ověřování na webu Azure Portal pomocí proměnných prostředí

1. Přihlaste se k webu Azure Portal jako alespoň správce aplikace nebo správce ověřování.
2. Přejděte do aplikace funkcí, kterou jste vytvořili, a v části Nastavení vyberte Konfigurace.
3. V části Nastavení aplikace vyberte Nové nastavení aplikace a přidejte proměnné prostředí z tabulky a jejich přidružené hodnoty.
4. Výběrem možnosti Uložit uložte nastavení aplikace.

Nastavení ověřování v kódu

Nastavení ověřování v kódu pomocí WebJobsAuthenticationEventsTriggerAttribute

1. Otevřete soubor AuthEventsTrigger.cs v integrovaném vývojovém prostředí (IDE).
2. WebJobsAuthenticationEventsTriggerAttribute Upravte zahrnutí AuthorityUrlAudienceAppId a AuthorizedPartyAppId vlastnosti, jak je znázorněno v následujícím fragmentu kódu.

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

Další krok

Konfigurace události vystavení vlastního tokenu zprostředkovatele deklarací identity