REST API létrehozása jogkivonat-kiállítás kezdőeseményéhez az Azure Functionsben
Ez a cikk azt ismerteti, hogyan hozhat létre REST API-t tokenkiállítási indítási eseményekkel az Azure Functions használatával az Azure Portalon. Létrehozhat egy Azure-függvényalkalmazást és egy HTTP-triggerfüggvényt, amely további jogcímeket adhat vissza a jogkivonatához.
Előfeltételek
- Az egyéni hitelesítési bővítmények áttekintésében szereplő fogalmak alapszintű ismerete.
- Azure-előfizetés az Azure Functions létrehozásához. Ha nem rendelkezik meglévő Azure-fiókkal, regisztráljon ingyenes próbaverzióra, vagy használja a Visual Studio-előfizetés előnyeit egy fiók létrehozásakor.
- Egy Microsoft Entra ID-bérlő. Ehhez az útmutatóhoz ügyfél- vagy munkaerő-bérlőt is használhat.
Ez a cikk bemutatja, hogyan hozhat létre REST API-t egy tokenkiállítási kezdőeseményhez a Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet-kódtár használatával, és hogyan állíthatja be hitelesítésre. Létrehoz egy HTTP-eseményindító függvényt a Visual Studióban vagy a Visual Studio Code-ban, konfigurálja a hitelesítéshez, majd üzembe helyezi azt az Azure Portalon, ahol az Azure Functionsen keresztül érhető el.
Előfeltételek
- Az egyéni hitelesítési bővítmények áttekintésében szereplő fogalmak alapszintű ismerete.
- Azure-előfizetés az Azure Functions létrehozásához. Ha nem rendelkezik meglévő Azure-fiókkal, regisztráljon ingyenes próbaverzióra, vagy használja a Visual Studio-előfizetés előnyeit egy fiók létrehozásakor.
- Egy Microsoft Entra ID-bérlő. Ehhez az útmutatóhoz ügyfél- vagy munkaerő-bérlőt is használhat.
- Az alábbi azonosítók és konfigurációk egyike:
- A Visual Studio azure-fejlesztési számítási feladattal konfigurálva van a Visual Studio számára.
- Visual Studio Code, engedélyezve az Azure Functions-bővítmény .
Feljegyzés
A Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet-kódtár jelenleg előzetes verzióban érhető el. A cikkben szereplő lépések változhatnak. A jogkivonat-kiállítás indítási eseményének implementálásának általános rendelkezésre állási implementációja az Azure Portalon érhető el.
Az Azure-függvényalkalmazás létrehozása
Az Azure Portalon hozzon létre egy Azure-függvényalkalmazást és annak társított erőforrását, mielőtt folytatná a HTTP-eseményindító függvény létrehozását.
Jelentkezzen be az Azure Portalra legalább egy alkalmazás-Rendszergazda istrator és hitelesítési Rendszergazda istratorként.
Az Azure Portal menüjében vagy a Kezdőlapon válassza az Erőforrás létrehozása elemet.
Keresse meg és válassza a függvényalkalmazást, majd válassza a Létrehozás lehetőséget.
Az Alapok lapon hozzon létre egy függvényalkalmazást az alábbi táblázatban megadott beállítások használatával:
Beállítás Ajánlott érték Leírás Előfizetés Az Ön előfizetése Az előfizetés, amely alatt az új függvényalkalmazás létrejön. Erőforráscsoport myResourceGroup Válassza ki és adja meg a meglévő erőforráscsoportot vagy annak az újnak a nevét, amelyben létre fogja hozni a függvényalkalmazást. Függvényalkalmazás neve Globálisan egyedi név Az új függvényalkalmazást azonosító név. Az érvényes karakterek az a-z(kis- és nagybetűk megkülönböztetése nélkül)0-9és az-.Kód vagy tárolórendszerkép üzembe helyezése Kód Kódfájlok közzétételét teszi lehetővé egy Docker-tárolóban. Ebben az oktatóanyagban válassza a Kód lehetőséget. Futtatókörnyezeti verem .NET Az Ön által előnyben részesített programozási nyelv. Ebben az oktatóanyagban válassza a .NET lehetőséget. Verzió 6 (LTS) Folyamatban A .NET-futtatókörnyezet verziója. A folyamatban lévő funkció azt jelzi, hogy a portálon létrehozhat és módosíthat függvényeket, ami az útmutatóhoz ajánlott Régió Előnyben részesített régió Válasszon ki egy önhöz közeli régiót vagy a függvényei által elérhető egyéb szolgáltatásokat. Operációs rendszer Windows Az operációs rendszer előre ki van jelölve a futtatókörnyezeti verem kiválasztása alapján. Terv típusa Felhasználás (kiszolgáló nélküli) Szolgáltatási csomag, amely meghatározza az erőforrások lefoglalását a függvényalkalmazáshoz. Válassza a Véleményezés + létrehozás lehetőséget az alkalmazáskonfiguráció-beállítások áttekintéséhez, majd a Létrehozás gombra. Az üzembe helyezés néhány percet vesz igénybe.
Az üzembe helyezés után válassza az Erőforrás megnyitása lehetőséget az új függvényalkalmazás megtekintéséhez.
HTTP-eseményindító függvény létrehozása
Az Azure-függvényalkalmazás létrehozása után hozzon létre egy HTTP-eseményindító függvényt az alkalmazásban. A HTTP-eseményindítóval HTTP-kéréssel hívhat meg egy függvényt, és erre a Microsoft Entra egyéni hitelesítési bővítmény hivatkozik.
- A függvényalkalmazás Áttekintés lapján válassza a Függvények panelt, és válassza a Függvény létrehozása lehetőséget a Létrehozás az Azure Portalon.
- A Függvény létrehozása ablakban hagyja a Fejlesztői környezet tulajdonságot Fejlesztésként a portálon. A Sablon területen válassza a HTTP-eseményindítót.
- A Sablon részletei területen adja meg a CustomAuthenticationExtensionsAPI értéket az Új függvény tulajdonsághoz.
- Az engedélyezési szinthez válassza a Függvény lehetőséget.
- Válassza a Létrehozás lehetőséget.
A függvény szerkesztése
A kód beolvassa a bejövő JSON-objektumot, a Microsoft Entra-azonosító pedig elküldi a JSON-objektumot az API-nak. Ebben a példában beolvassa a korrelációs azonosító értékét. Ezután a kód egy testreszabott jogcímgyűjteményt ad vissza, beleértve az eredetiCorrelationId, az Azure-függvény DateOfBirth eredeti, a ApiVersion és CustomRoles a Microsoft Entra-azonosítónak visszaadott gyűjteményét.
A menü Fejlesztőeszközök területén válassza a Kód + Teszt lehetőséget.
Cserélje le a teljes kódot a következő kódrészletre, majd válassza a Mentés lehetőséget.
#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>(); } }A felső menüben válassza a Függvény URL-címének lekérése lehetőséget, és másolja ki az URL-értéket . Ez a függvény URL-címe használható egyéni hitelesítési bővítmények beállításakor.
Az Azure-függvényalkalmazás létrehozása és létrehozása
Ebben a lépésben létrehoz egy HTTP triggerfüggvény API-t az IDE használatával, telepíti a szükséges NuGet-csomagokat, és másolja a mintakódot. Létrehozhatja a projektet, és futtathatja a függvényt a helyi függvény URL-címének kinyeréséhez.
Az alkalmazás létrehozása
Azure-függvényalkalmazás létrehozásához kövesse az alábbi lépéseket:
- Nyissa meg a Visual Studiót, és válassza az Új projekt létrehozása lehetőséget.
- Keresse meg és válassza ki az Azure Functionst, majd válassza a Tovább gombot.
- Adjon nevet a projektnek, például : AuthEventsTrigger. Érdemes egyezni a megoldás nevével a projekt nevével.
- Válassza ki a projekt helyét. Válassza a Tovább lehetőséget.
- Cél keretrendszerként válassza a .NET 6.0 (hosszú távú támogatás) lehetőséget.
- Válassza a Http-eseményindítót függvénytípusként, és az engedélyezési szint függvényre van állítva. Válassza a Létrehozás lehetőséget.
- A Megoldáskezelő nevezze át a Function1.cs fájlt AuthEventsTrigger.cs, és fogadja el az átnevezés módosítási javaslatát.
NuGet-csomagok telepítése és a projekt létrehozása
A projekt létrehozása után telepítenie kell a szükséges NuGet-csomagokat, és létre kell hoznia a projektet.
- A Visual Studio felső menüjében válassza a Project, majd a NuGet-csomagok kezelése lehetőséget.
- Válassza a Tallózás lapot, majd keresse meg és válassza a Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents lehetőséget a jobb oldali panelen. Válassza a Telepítés lehetőséget.
- Alkalmazza és fogadja el a megjelenő előugró ablakok módosításait.
A mintakód hozzáadása
A függvény API a jogkivonathoz tartozó további jogcímek forrása. A cikk alkalmazásában a mintaalkalmazás értékeit dolgozunk ki. Éles környezetben lekérheti a felhasználó adatait a külső adattárból.
A AuthEventsTrigger.cs fájlban cserélje le a fájl teljes tartalmát a következő kódra:
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);
}
}
}
}
A projekt helyi létrehozása és futtatása
Létre lett hozva a projekt, és hozzáadtuk a mintakódot. Az IDE használatával helyileg kell létrehoznunk és futtatni a projektet a helyi függvény URL-címének kinyeréséhez.
- Keresse meg a buildet a felső menüben, és válassza a Megoldás létrehozása lehetőséget.
- Nyomja le az F5 billentyűt, vagy válassza a felső menü AuthEventsTrigger elemét a függvény futtatásához.
- Másolja ki a függvény URL-címét a függvény futtatásakor előugró terminálból. Ez egyéni hitelesítési bővítmények beállításakor használható.
A függvény helyi futtatása (ajánlott)
Érdemes helyileg tesztelni a függvényt, mielőtt üzembe helyeznénk az Azure-ban. Használhatunk egy olyan JSON-törzset, amely utánozza a Microsoft Entra ID által a REST API-nak küldött kérést. Használja az előnyben részesített API-tesztelési eszközt a függvény közvetlen meghívásához.
Nyissa meg az IDE-ben local.settings.json , és cserélje le a kódot a következő JSON-ra. Helyi tesztelési célokra állíthatjuk be
"AuthenticationEvents__BypassTokenValidation"true.{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : true } }Az előnyben részesített API-teszteszköz használatával hozzon létre egy új HTTP-kérést, és állítsa a HTTP-metódust a következőre
POST: .Használja az alábbi JSON-törzset, amely utánozza a Microsoft Entra ID által a REST API-nak küldött kérést.
{ "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" } } } }Válassza a Küldés lehetőséget, és a következőhöz hasonló JSON-választ kell kapnia:
{ "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "customClaim1": "customClaimValue1", "customClaim2": [ "customClaimString1", "customClaimString2" ] } } ] } }
A függvény üzembe helyezése és közzététele az Azure-ban
A függvényt az IDE használatával kell üzembe helyezni az Azure-ban. Ellenőrizze, hogy megfelelően van-e bejelentkezve az Azure-fiókjába, hogy közzétehesse a függvényt.
A Megoldáskezelő kattintson a jobb gombbal a projektre, és válassza a Közzététel lehetőséget.
A Cél területen válassza az Azure-t, majd a Tovább lehetőséget.
Válassza az Azure-függvényalkalmazást (Windows) az adott célhoz, válassza az Azure-függvényalkalmazást (Windows), majd a Tovább lehetőséget.
A függvénypéldányban az Előfizetés neve legördülő listából válassza ki azt az előfizetést, amelyben az új függvényalkalmazás létrejön.
Válassza ki az új függvényalkalmazás közzétételének helyét, majd válassza az Új létrehozása lehetőséget.
A Függvényalkalmazás (Windows) lapon használja az alábbi táblázatban megadott függvényalkalmazás-beállításokat, majd válassza a Létrehozás lehetőséget.
Beállítás Ajánlott érték Leírás Név Globálisan egyedi név Az új függvényalkalmazást azonosító név. Az érvényes karakterek az a-z(kis- és nagybetűk megkülönböztetése nélkül)0-9és az-.Előfizetés Az Ön előfizetése Az előfizetés, amely alatt az új függvényalkalmazás létrejön. Erőforráscsoport myResourceGroup Válasszon ki egy meglévő erőforráscsoportot, vagy nevezze el az újat, amelyben létre fogja hozni a függvényalkalmazást. Terv típusa Felhasználás (kiszolgáló nélküli) Szolgáltatási csomag, amely meghatározza az erőforrások lefoglalását a függvényalkalmazáshoz. Helyen Előnyben részesített régió Válasszon ki egy önhöz közeli régiót vagy a függvényei által elérhető egyéb szolgáltatásokat. Azure Storage Az Ön tárfiókja A Functions futtatókörnyezetének szüksége van egy Azure Storage-fiókra. Általános célú tárfiók konfigurálásához válassza az Új lehetőséget. Application Insights Alapértelmezett Az Azure Monitor egyik funkciója. Ez automatikusan ki van jelölve, válassza ki azt, amelyet használni szeretne, vagy konfiguráljon egy újat. Várjon néhány percet a függvényalkalmazás üzembe helyezésére. Miután bezárult az ablak, válassza a Befejezés lehetőséget.
Megnyílik egy új Közzététel panel. A lap tetején válassza a Közzététel lehetőséget. Várjon néhány percet, amíg a függvényalkalmazás üzembe lesz helyezve, és megjelenik az Azure Portalon.
Hitelesítés konfigurálása az Azure-függvényhez
Az Azure-függvényhez háromféleképpen állíthat be hitelesítést:
- Hitelesítés beállítása az Azure Portalon környezeti változók használatával (ajánlott)
- Hitelesítés beállítása a kódban a következő használatával:
WebJobsAuthenticationEventsTriggerAttribute - Azure-alkalmazás szolgáltatáshitelesítés és -engedélyezés
Alapértelmezés szerint a kód be lett állítva az Azure Portalon való hitelesítéshez környezeti változók használatával. Az alábbi lapok segítségével kiválaszthatja a környezeti változók implementálásának előnyben részesített módszerét, vagy másik lehetőségként tekintse meg a beépített Azure-alkalmazás szolgáltatáshitelesítést és -engedélyezést. Környezeti változók beállításához használja a következő értékeket:
Hitelesítés beállítása az Azure Portalon környezeti változók használatával
- Jelentkezzen be az Azure Portalra legalább alkalmazás-Rendszergazda istratorként vagy hitelesítési Rendszergazda istratorként.
- Keresse meg a létrehozott függvényalkalmazást, és a Gépház alatt válassza a Konfiguráció lehetőséget.
- Az Alkalmazásbeállítások területen válassza az Új alkalmazásbeállítás lehetőséget, és adja hozzá a környezeti változókat a táblából és a hozzájuk tartozó értékeket.
- Az alkalmazásbeállítások mentéséhez válassza a Mentés lehetőséget.