Konfigurowanie identyfikatora Entra firmy Microsoft na potrzeby uwierzytelniania klienta
Ostrzeżenie
Obecnie uwierzytelnianie klienta firmy Microsoft Entra i usługa tokenu tożsamości zarządzanej są wzajemnie niezgodne w systemie Linux.
W przypadku klastrów działających na platformie Azure zaleca się zabezpieczenie dostępu do punktów końcowych zarządzania. W tym artykule opisano sposób konfigurowania identyfikatora entra firmy Microsoft w celu uwierzytelniania klientów dla klastra usługi Service Fabric.
W systemie Linux przed utworzeniem klastra należy wykonać następujące kroki. W systemie Windows można również skonfigurować uwierzytelnianie firmy Microsoft dla istniejącego klastra.
W tym artykule termin "aplikacja" odnosi się do aplikacji firmy Microsoft, a nie aplikacji usługi Service Fabric, a nie aplikacji usługi Service Fabric. W razie potrzeby należy dokonać rozróżnienia. Microsoft Entra ID umożliwia organizacjom (znanym jako dzierżawy) zarządzanie dostępem użytkowników do aplikacji.
Klaster usługi Service Fabric udostępnia kilka punktów wejścia dla swoich funkcji zarządzania, w tym internetowe narzędzie Service Fabric Explorer i program Visual Studio. W rezultacie utworzysz dwie aplikacje firmy Microsoft Entra, aby kontrolować dostęp do klastra: jedną aplikację internetową i jedną aplikację natywną. Po utworzeniu aplikacji przypiszesz użytkowników do ról tylko do odczytu i administratorów.
Uwaga
Obecnie usługa Service Fabric nie obsługuje uwierzytelniania entra firmy Microsoft dla magazynu.
Uwaga
Jest to znany problem polegający na tym, że nie można wyświetlić aplikacji i węzłów w klastrach z włączoną obsługą identyfikatorów firmy Microsoft w systemie Linux w witrynie Azure Portal.
Uwaga
Identyfikator entra firmy Microsoft wymaga teraz zweryfikowania domeny wydawców aplikacji (rejestracji aplikacji) lub użycia schematu domyślnego. Aby uzyskać dodatkowe informacje, zobacz Konfigurowanie domeny wydawcy aplikacji i identyfikatora URI identyfikatora AppId w aplikacjach z jedną dzierżawą wymaga użycia schematu domyślnego lub zweryfikowanych domen .
Uwaga
Począwszy od usługi Service Fabric 11.0, program Service Fabric Explorer wymaga identyfikatora URI przekierowania aplikacji jednostronicowej zamiast identyfikatora URI przekierowania sieci Web.
Wymagania wstępne
W tym artykule przyjęto założenie, że dzierżawa została już utworzona. Jeśli nie, zacznij od zapoznania się z artykułem Jak uzyskać dzierżawę firmy Microsoft Entra. Aby uprościć niektóre kroki związane z konfigurowaniem identyfikatora Entra firmy Microsoft za pomocą klastra usługi Service Fabric, utworzyliśmy zestaw skryptów programu Windows PowerShell. Niektóre akcje wymagają dostępu na poziomie administracyjnym do identyfikatora Entra firmy Microsoft. Jeśli skrypt wystąpi błąd 401 lub 403 "Authorization_RequestDenied", administrator musi wykonać skrypt.
- Uwierzytelnianie przy użyciu uprawnień administracyjnych platformy Azure.
- Sklonuj repozytorium na komputer.
- Upewnij się, że masz zainstalowane wszystkie wymagania wstępne dotyczące skryptów.
Tworzenie aplikacji firmy Microsoft Entra i przypisywanie użytkowników do ról
Użyjemy skryptów, aby utworzyć dwie aplikacje firmy Microsoft Entra, aby kontrolować dostęp do klastra: jedną aplikację internetową i jedną aplikację natywną. Po utworzeniu aplikacji reprezentujących klaster utworzysz użytkowników dla ról obsługiwanych przez usługę Service Fabric: tylko do odczytu i administratora.
SetupApplications.ps1
Uruchom SetupApplications.ps1 polecenie i podaj identyfikator dzierżawy, nazwę klastra, identyfikator URI aplikacji internetowej i adres URL odpowiedzi aplikacji internetowej jako parametry. Użyj -remove, aby usunąć rejestracje aplikacji. Użycie parametru -logFile <log file path> generuje dziennik transkrypcji. Aby uzyskać dodatkowe informacje, zobacz pomoc dotyczącą skryptu (pomoc .\setupApplications.ps1 -full). Skrypt tworzy aplikacje internetowe i natywne do reprezentowania klastra usługi Service Fabric. Dwa nowe wpisy rejestracji aplikacji mają następujący format:
- ClusterName_Cluster
- ClusterName_Client
Uwaga
W przypadku chmur krajowych (na przykład Azure Government platforma Microsoft Azure obsługiwana przez firmę 21Vianet) należy również określić -Location parametr .
Parametry
tenantId: Identyfikator dzierżawy można znaleźć, wykonując polecenie
Get-AzureSubscriptionprogramu PowerShell . Wykonanie tego polecenia powoduje wyświetlenie identyfikatora TenantId dla każdej subskrypcji.clusterName: Nazwa_klastra służy do prefiksu aplikacji Firmy Microsoft, które są tworzone przez skrypt. Nie musi dokładnie odpowiadać rzeczywistej nazwie klastra. Ma to na celu tylko ułatwienie mapowania artefaktów firmy Microsoft na klaster usługi Service Fabric, z którymi są używane.
SpaApplicationReplyUrl: SpaApplicationReplyUrl to domyślny punkt końcowy, który identyfikator Entra firmy Microsoft powraca do użytkowników po zakończeniu logowania. Ustaw ten punkt końcowy jako punkt końcowy programu Service Fabric Explorer dla klastra. Jeśli tworzysz aplikacje firmy Microsoft Entra do reprezentowania istniejącego klastra, upewnij się, że ten adres URL jest zgodny z punktem końcowym istniejącego klastra. Jeśli tworzysz aplikacje dla nowego klastra, zaplanuj punkt końcowy dla klastra i upewnij się, że nie używasz punktu końcowego istniejącego klastra. Domyślnie punkt końcowy narzędzia Service Fabric Explorer to:
https://<cluster_domain>:19080/Explorer/index.htmlwebApplicationUri: Identyfikator WebApplicationUri jest identyfikatorem URI "zweryfikowanej domeny" lub identyfikatorem URI przy użyciu formatu schematu interfejsu API API://{{identyfikator dzierżawy}}/{{nazwa klastra}}. Aby uzyskać dodatkowe informacje, zobacz Identyfikator URI appId w aplikacjach z jedną dzierżawą wymaga użycia schematu domyślnego lub zweryfikowanych domen .
Przykładowy schemat interfejsu API: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster
Przykład SetupApplications.ps1
# if using cloud shell
# cd clouddrive
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .
$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain
$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
-ClusterName $clusterName `
-SpaApplicationReplyUrl $spaApplicationReplyUrl `
-AddResourceAccess `
-WebApplicationUri $webApplicationUri `
-Verbose
Skrypt zwraca zmienną $configObj dla kolejnych poleceń i wyświetla kod JSON wymagany przez szablon usługi Azure Resource Manager. Skopiuj dane wyjściowe JSON i użyj ich podczas tworzenia lub modyfikowania istniejącego klastra, aby utworzyć klaster z włączoną obsługą identyfikatora Entra firmy Microsoft.
SetupApplications.ps1 przykładowe dane wyjściowe
Name Value
---- -----
WebAppId f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId 0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId 3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId b22cc0e2-7c4e-480c-89f5-25f768ecb439
-----ARM template-----
"azureActiveDirectory": {
"tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
"clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
"clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},
azureActiveDirectory parameters object JSON
"azureActiveDirectory": {
"tenantId":"<guid>",
"clusterApplication":"<guid>",
"clientApplication":"<guid>"
},
SetupUser.ps1
SetupUser.ps1 służy do dodawania kont użytkowników do nowo utworzonej rejestracji aplikacji przy użyciu zmiennej wyjściowej $configObj z powyższych. Określ nazwę użytkownika dla konta użytkownika, które ma zostać skonfigurowane przy użyciu rejestracji aplikacji, i określ wartość "isAdmin" dla uprawnień administracyjnych. Jeśli konto użytkownika jest nowe, podaj również hasło tymczasowe dla nowego użytkownika. Hasło należy zmienić przy pierwszym logowaniu. Jeśli używasz polecenia "-remove", usuniesz konto użytkownika, a nie tylko rejestrację aplikacji.
Przykład użytkownika SetupUser.ps1 (odczyt)
.\SetupUser.ps1 -ConfigObj $configobj `
-UserName 'TestUser' `
-Password 'P@ssword!123' `
-Verbose
Przykład setupUser.ps1 admin (odczyt/zapis)
.\SetupUser.ps1 -ConfigObj $configobj `
-UserName 'TestAdmin' `
-Password 'P@ssword!123' `
-IsAdmin `
-Verbose
SetupClusterResource.ps1
SetupClusterResource.ps1 można opcjonalnie użyć do wyeksportowania istniejącego szablonu arm zasobu klastra, dodania/zmodyfikowania konfiguracji "azureActiveDirectory" i ponownego wdrożenia szablonu. Użyj polecenia "-Whatif", aby wyeksportować i zmodyfikować szablon, ale nie wdrożyć zmiany konfiguracji. Ten skrypt wymaga modułu "Az" platformy Azure i nazwy grupy zasobów dla klastra.
SetupClusterResource.ps1 -whatIf example
# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
-resourceGroupName $resourceGroupName `
-WhatIf
Po zweryfikowaniu szablonu i uzyskaniu gotowości do przetworzenia ponownie uruchom skrypt bez polecenia "-WhatIf" lub użyj polecenia programu PowerShell "New-AzResourceGroupDeployment", aby wdrożyć szablon.
Przykład SetupClusterResource.ps1
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
-resourceGroupName $resourceGroupName
Uwaga
Zaktualizuj szablony usługi ARM lub skrypty aprowizacji klastra przy użyciu nowych zmian konfiguracji klastra Firmy Microsoft.
Udzielanie zgody administratora
Może być konieczne wyrażenie zgody administratora dla konfigurowanego elementu "Uprawnienia interfejsu API". Przejdź do bloku aplikacja systemu Azure rejestracji i dodaj nazwę klastra do filtru. W przypadku obu rejestracji otwórz pozycję "Uprawnienia interfejsu API" i wybierz pozycję "Udziel zgody administratora", jeśli jest dostępna.
Weryfikowanie konfiguracji usługi Microsoft Entra
Przejdź do adresu URL narzędzia Service Fabric Explorer (SFX). Powinno to być takie samo jak spaapplicationReplyUrl parametru. Powinno zostać wyświetlone okno dialogowe uwierzytelniania platformy Azure. Zaloguj się przy użyciu konta skonfigurowanego przy użyciu nowej konfiguracji firmy Microsoft Entra. Sprawdź, czy konto administratora ma dostęp do odczytu/zapisu i czy użytkownik ma dostęp do odczytu. Wszelkie modyfikacje klastra, na przykład wykonanie akcji, to akcja administracyjna.
Pomoc dotycząca rozwiązywania problemów z konfigurowaniem identyfikatora entra firmy Microsoft
Konfigurowanie identyfikatora Entra firmy Microsoft i korzystanie z niego może być trudne, więc poniżej przedstawiono wskazówki dotyczące tego, co można zrobić, aby debugować problem. Rejestrowanie transkrypcji programu PowerShell można włączyć przy użyciu argumentu "-logFile" w skryptach "SetupApplications.ps1" i "SetupUser.ps1", aby przejrzeć dane wyjściowe.
Uwaga
W przypadku migracji platform tożsamości (ADAL do biblioteki MSAL) wycofywanie modułu AzureRM na rzecz az platformy Azure i obsługa wielu wersji programu PowerShell zależności mogą nie zawsze być poprawne lub aktualne, co powoduje błędy podczas wykonywania skryptu. Uruchamianie poleceń i skryptów programu PowerShell z usługi Azure Cloud Shell zmniejsza potencjał błędów związanych z automatycznym uwierzytelnianiem sesji i tożsamością zarządzaną.
Request_BadRequest
Problem
Nieprawidłowa aktualizacja referencyjna. Kod stanu HTTP: 400.
VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).
Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
239 | … $result = Invoke-WebRequest $uri -Method $method -Headers $headers …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}
at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True
Przyczyna
Zmiany konfiguracji nie zostały rozpropagowane. Skrypty ponawiają próby dotyczące niektórych żądań z kodami stanu HTTP 400 i 404.
Rozwiązanie
Skrypty ponawiają próby dla niektórych żądań z kodami stanu HTTP 400 i 404 upto provided "-timeoutMin", który jest domyślnie 5 minut. Skrypt można ponownie wykonać w razie potrzeby.
Program Service Fabric Explorer monituje o wybranie certyfikatu
Problem
Po pomyślnym zalogowaniu się do identyfikatora Entra firmy Microsoft w narzędziu Service Fabric Explorer przeglądarka powróci do strony głównej, ale zostanie wyświetlony komunikat z monitem o wybranie certyfikatu.
Przyczyna
Użytkownik nie ma przypisanej roli w aplikacji klastra Microsoft Entra ID. W związku z tym uwierzytelnianie entra firmy Microsoft kończy się niepowodzeniem w klastrze usługi Service Fabric. Program Service Fabric Explorer wraca do uwierzytelniania certyfikatów.
Rozwiązanie
Postępuj zgodnie z instrukcjami dotyczącymi konfigurowania identyfikatora Entra firmy Microsoft i przypisywania ról użytkowników. Ponadto zalecamy włączenie opcji "Przypisanie użytkownika wymagane do uzyskania dostępu do aplikacji", tak jak SetupApplications.ps1 to ma być.
Połączenie z programem PowerShell kończy się niepowodzeniem z powodu błędu: "Określone poświadczenia są nieprawidłowe"
Problem
Jeśli używasz programu PowerShell do nawiązywania połączenia z klastrem przy użyciu trybu zabezpieczeń "AzureActiveDirectory", po pomyślnym zalogowaniu się do identyfikatora Entra firmy Microsoft połączenie kończy się niepowodzeniem z powodu błędu: "Określone poświadczenia są nieprawidłowe".
Rozwiązanie
To rozwiązanie jest takie samo jak poprzednie.
Narzędzie Service Fabric Explorer zwraca błąd podczas logowania: "AADSTS50011"
Problem
Podczas próby zalogowania się do identyfikatora Entra firmy Microsoft w narzędziu Service Fabric Explorer strona zwraca błąd: "AADSTS50011: Adres URL> adresu <odpowiedzi nie jest zgodny z adresami odpowiedzi skonfigurowanymi dla aplikacji: <guid>".
Przyczyna
Aplikacja klastra (internetowego), która reprezentuje narzędzie Service Fabric Explorer, próbuje uwierzytelnić się względem identyfikatora Entra firmy Microsoft, a w ramach żądania udostępnia adres URL powrotu przekierowania. Jednak adres URL nie znajduje się na liście adresów URL ODPOWIEDZI aplikacji firmy Microsoft.
Rozwiązanie
Na stronie rejestracji aplikacji Microsoft Entra dla klastra wybierz pozycję Uwierzytelnianie, a następnie w sekcji Identyfikatory URI przekierowania dodaj adres URL narzędzia Service Fabric Explorer do listy. Zapisz zmianę.
Nawiązywanie połączenia z klastrem przy użyciu uwierzytelniania entra firmy Microsoft za pośrednictwem programu PowerShell powoduje błąd podczas logowania: "AADSTS50011"
Problem
Podczas próby nawiązania połączenia z klastrem usługi Service Fabric przy użyciu identyfikatora Entra firmy Microsoft za pośrednictwem programu PowerShell strona logowania zwraca błąd: "AADSTS50011: adres URL odpowiedzi określony w żądaniu nie jest zgodny z adresami URL odpowiedzi skonfigurowanymi dla aplikacji: <guid>".
Przyczyna
Podobnie jak w przypadku poprzedniego problemu program PowerShell próbuje uwierzytelnić się względem identyfikatora Entra firmy Microsoft, który udostępnia adres URL przekierowania, który nie znajduje się na liście adresów URL odpowiedzi aplikacji Firmy Microsoft Entra.
Rozwiązanie
Użyj tego samego procesu, co w poprzednim problemie, ale adres URL musi być ustawiony na urn:ietf:wg:oauth:2.0:oob, specjalne przekierowanie do uwierzytelniania wiersza polecenia.
Wykonanie skryptu powoduje błąd w błędzie autoryzacji
Problem
Skrypt programu PowerShell może nie wykonać wszystkich poleceń REST wymaganych do ukończenia konfiguracji usługi Microsoft Entra z błędem "Authorization_RequestDenied", "Niewystarczające uprawnienia do ukończenia operacji". Przykładowy błąd:
Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
239 | … $result = Invoke-WebRequest $uri -Method $method -Headers $headers …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
| operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
364 | assert-notNull $result "aad app service principal oauth permissio …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| aad app service principal oauth permissions User.Read configuration failed
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
656 | main
| ~~~~
| exception: exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed Exception:
| /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line | 22 | throw "assertion failure: object:$obj message:$msg" |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed
...
Przyczyna
Ten błąd jest zwracany, gdy konto użytkownika wykonujące skrypt nie ma uprawnień do wykonywania wywołania REST. Może się tak zdarzyć, jeśli użytkownik nie ma uprawnień administratora/zarządzania/zapisu dla tworzonych lub modyfikowanych obiektów.
Rozwiązanie
Skontaktuj się z administratorem dzierżawy platformy Azure lub identyfikatorem entra firmy Microsoft, aby wykonać wszystkie pozostałe akcje. Podane skrypty są idempotentne, więc można je ponownie wykonać w celu ukończenia procesu.
Łączenie klastra przy użyciu uwierzytelniania firmy Microsoft Entra za pomocą programu PowerShell
Aby połączyć klaster usługi Service Fabric, użyj następującego przykładu polecenia programu PowerShell:
Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>
Aby dowiedzieć się więcej, zobacz Polecenie cmdlet Connect-ServiceFabricCluster.
Czy mogę ponownie użyć tej samej dzierżawy usługi Microsoft Entra w wielu klastrach?
Tak. Pamiętaj jednak, aby dodać adres URL narzędzia Service Fabric Explorer do aplikacji klastra (sieci Web). W przeciwnym razie program Service Fabric Explorer nie działa.
Dlaczego nadal potrzebuję certyfikatu serwera, gdy jest włączony identyfikator Entra firmy Microsoft?
FabricClient i FabricGateway wykonują wzajemne uwierzytelnianie. Podczas uwierzytelniania firmy Microsoft Entra integracja firmy Microsoft zapewnia tożsamość klienta na serwerze, a certyfikat serwera jest używany przez klienta do weryfikowania tożsamości serwera. Aby uzyskać więcej informacji na temat certyfikatów usługi Service Fabric, zobacz Certyfikaty X.509 i Service Fabric.
Następne kroki
Po skonfigurowaniu aplikacji Firmy Microsoft Entra i ustawieniu ról dla użytkowników skonfiguruj i wdróż klaster.