Udostępnij za pośrednictwem

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

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

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.

  1. Przejdź do karty "Uwierzytelnianie" w aplikacji funkcji
  2. Kliknij pozycję "Dodaj dostawcę tożsamości"
  3. Wybierz pozycję "Microsoft" jako dostawcę tożsamości
  4. Wybierz pozycję "Podaj szczegóły istniejącej rejestracji aplikacji"
  5. 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.