Megosztás a következőn keresztül:

Hitelesítési események eseményindítója Azure Functions Node-ügyfélkódtárhoz

  • Cikk

Az Azure Functions hitelesítési eseményindítója kezeli az összes háttérfeldolgozást (például token/json sémaérvényesítést) a hitelesítési események bejövő HTTP-kérelmeihez. A fejlesztőnek pedig egy erősen gépelt, verziószámozott objektummodellt biztosít, amellyel dolgozhat, ami azt jelenti, hogy a fejlesztőnek nem kell előzetes ismeretekkel rendelkeznie a kérelem és a válasz json hasznos adatairól.

Ez a projekt-keretrendszer a következő funkciókat biztosítja:

  • Jogkivonat-ellenőrzés az API-hívás biztonságossá tételéhez
  • Objektummodell, gépelés és IDE intellisense
  • Az API-kérés- és válaszsémák bejövő és kimenő ellenőrzése
  • Verziókezelés
  • Nincs szükség sablonkódra.

Első lépések

Az npm-csomag telepítése

npm install @azure/functions-authentication-events

Előfeltételek

Az ügyfél hitelesítése

Amikor Azure AD hitelesítési események szolgáltatás meghívja az egyéni bővítményt, egy Authorization fejlécet küld a Bearer {token}következővel: . Ez a jogkivonat egy szolgáltatáshitelesítési szolgáltatást jelöl, amelyben:

  • Az "erőforrás", más néven a célközönség az az alkalmazás, amelyet regisztrál az API-jának megjelenítéséhez. Ezt a jogkivonatban szereplő aud jogcím jelöli.
  • Az "ügyfél" egy Microsoft-alkalmazás, amely a Azure AD hitelesítési eseményszolgáltatást jelöli. appId Értéke 99045fe1-7639-4a75-9d4a-577b6ca3810f. Ezt a következő képviseli:
    • A azp jogkivonatban szereplő jogcím, ha az alkalmazástulajdonság accessTokenAcceptedVersion értéke 2.
    • A appid jogkivonatban szereplő jogcím, ha az erőforrás-alkalmazás tulajdonsága accessTokenAcceptedVersion vagy nullértékre 1 van állítva.

A jogkivonat kezelésének három megközelítése van. A viselkedést az alább látható alkalmazásbeállítások használatával vagy a local.settings.json fájlon keresztül testre szabhatja a helyi környezetekben.

Jogkivonatok ellenőrzése Azure Functions Azure AD hitelesítési integrációval

Ha éles környezetben futtatja a függvényt, erősen ajánlott a Azure Functions Azure AD hitelesítési integrációt használni a bejövő jogkivonatok érvényesítéséhez.

  1. Nyissa meg a "Hitelesítés" lapot a függvényalkalmazásban
  2. Kattintson az "Identitásszolgáltató hozzáadása" elemre
  3. Identitásszolgáltatóként válassza a "Microsoft" lehetőséget
  4. Válassza a "Meglévő alkalmazásregisztráció részleteinek megadása" lehetőséget.
  5. Adja meg annak az alkalmazásnak az Application ID alkalmazását, amely az API-t képviseli a Azure AD

A kiállító és az engedélyezett célközönség az accessTokenAcceptedVersion alkalmazás tulajdonságától függ (az alkalmazás jegyzékfájljában található).

Ha a accessTokenAcceptedVersion tulajdonság 2értéke: 6. Állítsa be az Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId')

Ha a accessTokenAcceptedVersion tulajdonság értéke 1 vagy null: 6. Egyéni tartománynév használata esetén állítsa be az Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' értéket.

Alapértelmezés szerint a hitelesítési eseményindító ellenőrzi, hogy az Azure-függvény hitelesítési integrációja konfigurálva van-e, és ellenőrzi, hogy a jogkivonatban lévő ügyfél értéke (a jogkivonaton vagy appid jogcímen azp keresztül) van-e beállítva 99045fe1-7639-4a75-9d4a-577b6ca3810f .

Ha olyan ügyfélen szeretné tesztelni az API-t, amely nem Azure AD hitelesítési események szolgáltatása, például a Postman használatával, konfigurálhat egy választható alkalmazásbeállítást:

  • AuthenticationEvents__CustomCallerAppId – a kívánt ügyfél guid azonosítója. Ha nincs megadva, 99045fe1-7639-4a75-9d4a-577b6ca3810f feltételezzük.

Az eseményindító érvényesítése a jogkivonattal

Az azure-függvényszolgáltatásban nem üzemeltetett helyi környezetekben vagy környezetekben az eseményindító elvégezheti a jogkivonat-ellenőrzést. Adja meg a következő alkalmazásbeállításokat:

  • AuthenticationEvents__TenantId – a bérlő azonosítója
  • AuthenticationEvents__AudienceAppId – ugyanaz az érték, mint az 1. lehetőség "Engedélyezett célközönség" értéke.
  • AuthenticationEvents__CustomCallerAppId (nem kötelező) – a kívánt ügyfél guid azonosítója. Ha nincs megadva, 99045fe1-7639-4a75-9d4a-577b6ca3810f feltételezzük.

Példafájl local.settings.json :

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Nincs jogkivonat-ellenőrzés

Ha nem szeretné hitelesíteni a jogkivonatot a helyi fejlesztés során, állítsa be a következő alkalmazásbeállítást:

  • AuthenticationEvents__BypassTokenValidation – értéke true miatt az eseményindító nem ellenőrzi a jogkivonat érvényesítését.

Gyorsútmutató

  • Visual Studio Code
    • A Visual Studio Code elindítása
    • A terminálparancs func init . --worker-runtime node futtatása a parancskatalóguson keresztül
    • A terminálparancs func new futtatása a parancskatalóguson keresztül
    • Kövesse a projektlétrehozásra vonatkozó utasításokat
    • A terminálparancs npm install @azure/functions-authentication-events futtatása a parancskatalóguson keresztül
    • A terminálparancs npm install futtatása a parancskatalóguson keresztül
    • A terminálparancs npm run-script build futtatása a parancskatalóguson keresztül
  • A teszteléshez szükséges jogkivonat-ellenőrzés fejlesztési célú fordulója:
  • Adja hozzá a AuthenticationEvents__BypassTokenValidation alkalmazáskulcsot a local.settings.json fájl "Értékek" szakaszához, és állítsa igaz értékre. Ha nem rendelkezik local.settings.json fájllal a helyi környezetben, hozzon létre egyet a függvényalkalmazás gyökerében.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • A projekt betöltése után futtathatja a mintakódot, és látnia kell, hogy az Azure Functions-fejlesztő alkalmazása betölti a végpontot.

Fő fogalmak

Az Azure .NET SDK fő fogalmai itt találhatók

Dokumentáció

  • Az egyik függvényt közzétették, van néhány jó olvasmány a naplózásról és a metrikákról, amelyek itt találhatók

  • Az API dokumentációját a (Link TBD) című témakörben találja.

  • Ha ez az előzetes verzióra kerül, kivéve a kompatibilitástörő módosításokat, és egyszerűen eltávolítjuk a privát előzetes verzióra mutató nuget-forrást.

Példák

A jogkivonat-bővítés teszteléséhez tegye a következőket.

  • Nyissa meg az előző lépésben létrehozott projektet. (Rövid útmutató)
  • Futtassa az alkalmazást. func host start
  • Az Azure Functions fejlesztői alkalmazásának elindítása után másolja ki az alkalmazás indításakor megjelenő figyelési URL-címet.
  • Megjegyzés: Minden hitelesítési függvény szerepel a listában, abban az esetben, ha egy függvényfigyelő regisztrálva van az "OnTokenIssuanceStart" néven.
  • A függvényvégpont ezután a figyelési URL-cím és a függvény kombinációja lesz, például: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Tegye közzé a következő hasznos adatokat a Postman vagy a Fiddler használatával.
  • A Postman használatának lépései megtalálhatók (Link TBD)
{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}
  • A következő választ kell látnia:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Hibaelhárítás

  • Visual Studio Code
    • Ha a Visual Studio Code-ban fut, hibaüzenet jelenik meg a helyi Azure Storage Emulator sorai mentén, és manuálisan indíthatja el az emulátort.! (Megjegyzés: Az Azure Storage emulátor elavult, és a javasolt csere az Azurite)
    • Ha a Visual Studio Code-ot macen használja, használja az Azurite-ot
    • Ha a következő hibaüzenet jelenik meg a Windowsban (ez egy hiba), amikor megpróbálja futtatni a létrehozott kivetített fájlt.
    • Ezt úgy oldhatja meg, hogy végrehajtja ezt a parancsot a PowerShellbenSet-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine. Erről itt ésitt talál további információt.

Következő lépések

Az Azure SDK-val kapcsolatos további információkért tekintse meg ezt a webhelyet.

Közzététel

  • Kövesse az itt található utasításokat a Azure-alkalmazás létrehozásához és közzétételéhez. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • A közzétett közzétételi végpont meghatározásához kombinálja a létrehozott Azure-függvényvégpontot, irányt a figyelőhöz és a figyelő kódjához. A figyelőkód az Azure-függvényalkalmazásban való navigálással, az "Alkalmazáskulcsok" kiválasztásával és a AuthenticationEvents_extension értékének másolásával érhető el.
  • Például: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Győződjön meg arról, hogy az éles környezetben a megfelelő alkalmazásbeállítások vannak megadva a jogkivonat-hitelesítéshez.
  • Ismét tesztelheti a közzétett függvényt, ha a fenti hasznos adatokat közzéteszi az új végponton.

Közreműködés

Az adattárhoz való hozzájárulás részleteiért tekintse meg a közreműködői útmutatót.

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes adattárban a CLA használatával.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.