Wyzwalacz zdarzeń uwierzytelniania dla biblioteki klienta Azure Functions dla środowiska Node

Artykuł
01/10/2024

Wyzwalacz zdarzenia uwierzytelniania dla Azure Functions obsługuje wszystkie operacje przetwarzania zaplecza (np. weryfikację schematu tokenu/json) dla przychodzących żądań HTTP dla zdarzeń uwierzytelniania. Zapewnia deweloperowi silnie typizowanego, wersjonowanego modelu obiektów do pracy, co oznacza, że deweloper nie musi mieć żadnej wcześniejszej wiedzy na temat ładunków żądania i odpowiedzi w formacie JSON.

Ta struktura projektu udostępnia następujące funkcje:

Weryfikacja tokenu na potrzeby zabezpieczania wywołania interfejsu API
Model obiektów, wpisywanie i intellisense środowiska IDE
Weryfikacja przychodzących i wychodzących schematów żądań i odpowiedzi interfejsu API
Przechowywanie wersji
Nie ma potrzeby standardowego kodu.

Wprowadzenie

Instalowanie pakietu npm

npm install @azure/functions-authentication-events

Wymagania wstępne

Narzędzia funkcji platformy Azure
Podstawowe narzędzia funkcji platformy Azure
W przypadku korzystania z Visual Studio Code następujących rozszerzeń:
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Uwierzytelnianie klienta

Gdy usługa zdarzeń uwierzytelniania Azure AD wywołuje rozszerzenie niestandardowe, wyśle Authorization nagłówek z .Bearer {token} Ten token będzie reprezentować usługę uwierzytelniania usługi , w której:

"zasób", znany również jako odbiorcy, to aplikacja zarejestrowana w celu reprezentowania interfejsu API. Jest to reprezentowane aud przez oświadczenie w tokenie.
"Klient" to aplikacja firmy Microsoft reprezentująca usługę zdarzeń uwierzytelniania Azure AD. Ma appId wartość 99045fe1-7639-4a75-9d4a-577b6ca3810f. Jest to reprezentowane przez:
- Oświadczenie azp w tokenie, jeśli właściwość aplikacji accessTokenAcceptedVersion jest ustawiona na 2wartość .
- Oświadczenie appid w tokenie, jeśli właściwość aplikacji zasobu jest ustawiona accessTokenAcceptedVersion na 1 wartość lub null.

Istnieją trzy podejścia do radzenia sobie z tokenem. Zachowanie można dostosować przy użyciu ustawień aplikacji , jak pokazano poniżej lub za pośrednictwem pliku local.settings.json w środowiskach lokalnych.

Weryfikowanie tokenów przy użyciu integracji uwierzytelniania Azure Functions Azure AD

Podczas uruchamiania funkcji w środowisku produkcyjnym zdecydowanie zaleca się użycie integracji uwierzytelniania Azure Functions Azure AD do weryfikacji tokenów przychodzących.

Przejdź do karty "Uwierzytelnianie" w aplikacji funkcji
Kliknij pozycję "Dodaj dostawcę tożsamości"
Wybierz pozycję "Microsoft" jako dostawcę tożsamości
Wybierz pozycję "Podaj szczegóły istniejącej rejestracji aplikacji"
Application ID Wprowadź aplikację reprezentującą interfejs API w Azure AD

Wystawca i dozwoloni odbiorcy zależą od accessTokenAcceptedVersion właściwości aplikacji (można je znaleźć w "Manifeście" aplikacji).

Jeśli właściwość jest ustawiona accessTokenAcceptedVersion na 2wartość : 6. Ustaw identyfikator Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId')

accessTokenAcceptedVersion Jeśli właściwość jest ustawiona na 1 wartość lub null: 6. Ustaw Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentyfikatorUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}, jeśli używasz niestandardowej nazwy domeny.

Domyślnie wyzwalacz zdarzenia uwierzytelniania zweryfikuje, czy jest skonfigurowana integracja uwierzytelniania funkcji platformy Azure i sprawdzi, czy klient w tokenie jest ustawiony na 99045fe1-7639-4a75-9d4a-577b6ca3810f wartość (za pośrednictwem azp oświadczeń lub appid w tokenie).

Jeśli chcesz przetestować interfejs API na innym kliencie, który nie jest Azure AD usługi zdarzeń uwierzytelniania, na przykład przy użyciu narzędzia Postman, możesz skonfigurować opcjonalne ustawienie aplikacji:

AuthenticationEvents__CustomCallerAppId — identyfikator GUID żądanego klienta. Jeśli nie zostanie podana, przyjmuje się założenie 99045fe1-7639-4a75-9d4a-577b6ca3810f .

Sprawdzanie poprawności tokenu przez wyzwalacz

W środowiskach lokalnych lub środowiskach, które nie są hostowane w usłudze funkcji platformy Azure, wyzwalacz może przeprowadzić walidację tokenu. Ustaw następujące ustawienia aplikacji:

AuthenticationEvents__TenantId — identyfikator dzierżawy
AuthenticationEvents__AudienceAppId — ta sama wartość co "Dozwolona publiczność" w opcji 1.
AuthenticationEvents__CustomCallerAppId (opcjonalnie) — identyfikator GUID żądanego klienta. Jeśli nie zostanie podana, przyjmuje się założenie 99045fe1-7639-4a75-9d4a-577b6ca3810f .

Przykładowy local.settings.json plik:

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

Brak weryfikacji tokenu

Jeśli nie chcesz uwierzytelniać tokenu podczas programowania lokalnego, ustaw następujące ustawienie aplikacji:

AuthenticationEvents__BypassTokenValidation — wartość parametru true spowoduje, że wyzwalacz nie będzie sprawdzany pod kątem weryfikacji tokenu.

Szybki start

Visual Studio Code
- Uruchom program Visual Studio Code
- Uruchamianie polecenia func init . --worker-runtime node terminalu za pomocą palety poleceń
- Uruchamianie polecenia func new terminalu za pomocą palety poleceń
- Postępuj zgodnie z monitami tworzenia projektu
- Uruchamianie polecenia npm install @azure/functions-authentication-events terminalu za pomocą palety poleceń
- Uruchamianie polecenia npm install terminalu za pomocą palety poleceń
- Uruchamianie polecenia npm run-script build terminalu za pomocą palety poleceń
W celu programowania weryfikacja tokenu na potrzeby testowania:
Dodaj klucz aplikacji AuthenticationEvents__BypassTokenValidation do sekcji "Wartości" w pliku local.settings.json i ustaw dla niego wartość true. Jeśli nie masz pliku local.settings.json w środowisku lokalnym, utwórz go w katalogu głównym aplikacji funkcji.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

Po załadowaniu projektu możesz uruchomić przykładowy kod. Aplikacja dewelopera usługi Azure Functions powinna załadować punkt końcowy.

Kluczowe pojęcia

Kluczowe pojęcia dotyczące zestawu Azure .NET SDK można znaleźć tutaj

Dokumentacja

Opublikowano jedną z funkcji. Istnieje kilka dobrych informacji na temat rejestrowania i metryk, które można znaleźć tutaj
Aby uzyskać dokumentację interfejsu API, zobacz (Link TBD)
Gdy przejdziemy do wersji zapoznawczej, z wyjątkiem zmian powodujących niezgodność i będzie tak proste, jak usunięcie źródła nuget wskazującego prywatną wersję zapoznawcza.

Przykłady

Aby przetestować rozszerzenie tokenu, wykonaj następujące czynności.

Otwórz projekt utworzony w poprzednim kroku. (Szybki start)
Uruchom aplikację. func host start
Po uruchomieniu aplikacji dewelopera usługi Azure Functions skopiuj adres URL nasłuchiwania wyświetlany podczas uruchamiania aplikacji.
Uwaga: wszystkie funkcje uwierzytelniania są wyświetlane w przypadku, gdy mamy zarejestrowany jeden odbiornik funkcji o nazwie "OnTokenIssuanceStart"
Punkt końcowy funkcji będzie wówczas kombinacją adresu URL nasłuchiwania i funkcji, na przykład: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
Opublikuj następujący ładunek, używając czegoś takiego jak Postman lub Fiddler.
Kroki dotyczące korzystania z narzędzia Postman można znaleźć (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"
            }
        }
    }
}

Powinna zostać wyświetlona następująca odpowiedź:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Rozwiązywanie problemów

Visual Studio Code
- Jeśli uruchomiono polecenie w Visual Studio Code, w wierszach lokalnego emulatora usługi Azure Storage jest niedostępny, możesz uruchomić emulator ręcznie.! (Uwaga: emulator usługi Azure Storage jest teraz przestarzały, a sugerowane zastąpienie to Azurite)
- Jeśli używasz Visual Studio Code na komputerze Mac, użyj Azurite
- Jeśli podczas próby uruchomienia utworzonego projektu zostanie wyświetlony następujący błąd w systemie Windows (jest to usterka).
- Można to rozwiązać, wykonując to polecenie w programie PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine więcej informacji na ten temat można znaleźć tutaj i tutaj

Następne kroki

Aby uzyskać więcej informacji na temat zestawu Azure SDK, zapoznaj się z tą witryną internetową

Publikowanie

Postępuj zgodnie z instrukcjami podanymi tutaj, aby utworzyć i opublikować aplikacja systemu Azure. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
Aby określić opublikowany punkt końcowy publikowania, połącz utworzony punkt końcowy funkcji platformy Azure, trasę do odbiornika i kodu odbiornika, kod nasłuchiwania można znaleźć, przechodząc do aplikacji funkcji platformy Azure, wybierając pozycję "Klucze aplikacji" i kopiując wartość AuthenticationEvents_extension.
Na przykład: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
Upewnij się, że środowisko produkcyjne ma poprawne ustawienia aplikacji na potrzeby uwierzytelniania tokenu.
Po raz kolejny możesz przetestować opublikowaną funkcję, publikując powyższy ładunek w nowym punkcie końcowym.

Współtworzenie

Aby uzyskać szczegółowe informacje na temat współtworzenia tego repozytorium, zobacz przewodnik współtworzenia.

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Musisz to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego cla.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Udostępnij za pośrednictwem