Biblioteka klienta uwierzytelniania aplikacji dla platformy .NET — wersja 1.6.0

Uwaga

Microsoft.Azure.Services.AppAuthentication został wycofany i nie jest już obsługiwany ani obsługiwany. Jest on zastępowany przez bibliotekę klienta tożsamości platformy Azure dostępną dla platform .NET, Java, TypeScript i Python. Informacje o sposobie migracji do Azure Identityprogramu można znaleźć tutaj: AppAuthentication to Azure.Identity Migration Guidance (Wskazówki dotyczące migracji w usłudze Azure.Identity).

Aby uwierzytelnić się w usługach platformy Azure przy użyciu jednostki usługi, potrzebujesz poświadczeń usługi Azure Active Directory (Azure AD) — wspólnego wpisu tajnego lub certyfikatu.

Zarządzanie takimi poświadczeniami może być trudne. Kuszące jest umieszczenie poświadczeń w aplikacji przez uwzględnienie ich w plikach źródłowych lub konfiguracyjnych. Biblioteka Microsoft.Azure.Services.AppAuthentication platformy .NET upraszcza ten problem. Używa poświadczeń dewelopera do uwierzytelniania podczas programowania lokalnego. Gdy rozwiązanie zostanie później wdrożone na platformie Azure, biblioteka automatycznie przełączy się do poświadczeń aplikacji. Korzystanie z poświadczeń dewelopera podczas programowania lokalnego jest bezpieczniejsze, ponieważ nie trzeba tworzyć Azure AD poświadczeń ani udostępniać poświadczeń między deweloperami.

Biblioteka Microsoft.Azure.Services.AppAuthentication automatycznie zarządza uwierzytelnianiem, co z kolei pozwala skupić się na rozwiązaniu, a nie na poświadczeniach. Obsługuje lokalne programowanie przy użyciu programu Microsoft Visual Studio, interfejsu wiersza polecenia platformy Azure lub zintegrowanego uwierzytelniania Azure AD. Po wdrożeniu w zasobie platformy Azure, który obsługuje tożsamość zarządzaną, biblioteka automatycznie używa tożsamości zarządzanych dla zasobów platformy Azure. Nie są wymagane żadne zmiany w kodzie ani konfiguracji. Biblioteka obsługuje również bezpośrednie użycie poświadczeń klienta Azure AD, gdy tożsamość zarządzana jest niedostępna lub gdy kontekst zabezpieczeń dewelopera nie może być określony podczas programowania lokalnego.

Kod | źródłowy Pakiet (nuget) | Dokumentacja usługi Azure Active Directory

Wymagania wstępne

  • Visual Studio 2019 lub Visual Studio 2017 w wersji 15.5.

  • Rozszerzenie uwierzytelniania aplikacji dla programu Visual Studio dostępne jako osobne rozszerzenie dla programu Visual Studio 2017 Update 5 i dołączone do produktu w aktualizacji Update 6 i nowszych wersjach. Za pomocą aktualizacji Update 6 lub nowszej możesz zweryfikować instalację rozszerzenia uwierzytelniania aplikacji, wybierając pozycję Narzędzia programistyczne platformy Azure z poziomu instalatora programu Visual Studio.

Korzystanie z biblioteki

W przypadku aplikacji .NET najprostszym sposobem pracy z tożsamością zarządzaną jest użycie Microsoft.Azure.Services.AppAuthentication pakietu. Jak to zrobić krok po kroku:

  1. Wybierz pozycję Narzędzia> Menedżer >pakietów NuGetZarządzaj pakietami NuGet dla rozwiązania, aby dodać odwołania do pakietów Microsoft.Azure.Services.AppAuthentication i Microsoft.Azure.KeyVault NuGet do projektu.

  2. Użyj usługi AzureServiceTokenProvider, aby uprościć żądanie tokenów dostępu dla klientów platformy Azure, podobnie jak w poniższych przykładach:

    using Microsoft.Azure.Services.AppAuthentication;
    using Microsoft.Azure.KeyVault;
    using System.Data.SqlClient
    
    // Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
    var azureServiceTokenProvider = new AzureServiceTokenProvider();
    var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));
    
    // Request an access token for SqlConnection
    sqlConnection = new SqlConnection(YourConnectionString)) 
    { 
        sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
        sqlConnection.Open(); 
    } 
    

Klasa bezpieczna AzureServiceTokenProvider wątkowo buforuje token w pamięci i pobiera go z Azure AD tuż przed wygaśnięciem. Oznacza to, że nigdy nie trzeba sprawdzać wygaśnięcia tokenu przed wywołaniem GetAccessTokenAsync metody .

Metoda GetAccessTokenAsync wymaga identyfikatora zasobu. Aby dowiedzieć się więcej na temat usług platformy Microsoft Azure, zobacz Co to jest tożsamości zarządzane dla zasobów platformy Azure.

Lokalne uwierzytelnianie programistyczne

W przypadku programowania lokalnego istnieją dwa podstawowe scenariusze uwierzytelniania: uwierzytelnianie w usługach platformy Azure i uwierzytelnianie w usługach niestandardowych.

Uwierzytelnianie w usługach platformy Azure

Maszyny lokalne nie obsługują tożsamości zarządzanych dla zasobów platformy Azure. W związku z tym Microsoft.Azure.Services.AppAuthentication biblioteka używa poświadczeń dewelopera do uruchamiania w lokalnym środowisku programistycznym. Po wdrożeniu rozwiązania na platformie Azure biblioteka używa tożsamości zarządzanej do przełączenia się do przepływu udzielania poświadczeń klienta OAuth 2.0. Takie podejście oznacza, że możesz przetestować ten sam kod lokalnie i zdalnie bez obaw.

W przypadku programowania AzureServiceTokenProvider lokalnego pobiera tokeny przy użyciu programu Visual Studio, interfejsu wiersza polecenia platformy Azure lub zintegrowanego uwierzytelniania Azure AD. Każda opcja jest podejmowana sekwencyjnie, a biblioteka używa pierwszej opcji, która się powiedzie. Jeśli żadna opcja nie działa, zostanie AzureServiceTokenProviderException zgłoszony wyjątek ze szczegółowymi informacjami.

Uwierzytelnianie za pomocą programu Visual Studio

Aby uwierzytelnić się przy użyciu programu Visual Studio:

  1. Zaloguj się do programu Visual Studio i użyj opcji narzędzi>, aby otworzyć opcje.

  2. Wybierz pozycję Uwierzytelnianie usługi platformy Azure, wybierz konto na potrzeby programowania lokalnego, a następnie wybierz przycisk OK.

Jeśli wystąpią problemy podczas korzystania z programu Visual Studio, takie jak błędy, które obejmują plik dostawcy tokenów, dokładnie zapoznaj się z poprzednimi krokami.

Może być konieczne ponowne uwierzytelnienie tokenu dewelopera. W tym celu wybierz pozycję Narzędzia>Opcje, a następnie wybierz pozycję Uwierzytelnianie usługi platformy Azure. Poszukaj linku Ponowne uwierzytelnianie w ramach wybranego konta. Wybierz ją, aby się uwierzytelnić.

Uwierzytelnianie za pomocą interfejsu wiersza polecenia platformy Azure

Aby używać interfejsu wiersza polecenia platformy Azure do programowania lokalnego, upewnij się, że masz wersję interfejsu wiersza polecenia platformy Azure w wersji 2.0.12 lub nowszej.

Aby użyć interfejsu wiersza polecenia platformy Azure:

  1. Wyszukaj pozycję Interfejs wiersza polecenia platformy Azure na pasku zadań systemu Windows, aby otworzyć wiersz polecenia platformy Microsoft Azure.

  2. Zaloguj się do Azure Portal: az login, aby zalogować się na platformie Azure.

  3. Zweryfikuj dostęp, wprowadzając polecenie az account get-access-token --resource https://vault.azure.net. Jeśli wystąpi błąd, sprawdź, czy właściwa wersja interfejsu wiersza polecenia platformy Azure jest poprawnie zainstalowana.

    Jeśli interfejs wiersza polecenia platformy Azure nie jest zainstalowany w katalogu domyślnym, może zostać wyświetlony raport o błędach, który AzureServiceTokenProvider nie może znaleźć ścieżki dla interfejsu wiersza polecenia platformy Azure. Użyj zmiennej środowiskowej AzureCLIPath , aby zdefiniować folder instalacyjny interfejsu wiersza polecenia platformy Azure. AzureServiceTokenProvider Dodaje katalog określony w zmiennej środowiskowej AzureCLIPath do zmiennej środowiskowej Path w razie potrzeby.

  4. Jeśli logujesz się do interfejsu wiersza polecenia platformy Azure przy użyciu wielu kont lub twoje konto ma dostęp do wielu subskrypcji, musisz określić subskrypcję do użycia. Wprowadź polecenie az account set --subscription .

To polecenie generuje dane wyjściowe tylko w przypadku błędu. Aby sprawdzić bieżące ustawienia konta, wprowadź polecenie az account list.

Uwierzytelnianie przy użyciu uwierzytelniania Azure AD

Aby użyć uwierzytelniania Azure AD, sprawdź, czy:

Uwierzytelnianie w usługach niestandardowych

Gdy usługa wywołuje usługi platformy Azure, poprzednie kroki działają, ponieważ usługi platformy Azure umożliwiają dostęp do użytkowników i aplikacji.

Podczas tworzenia usługi, która wywołuje usługę niestandardową, użyj Azure AD poświadczeń klienta na potrzeby lokalnego uwierzytelniania programistycznego. Dostępne są dwie opcje:

Po zalogowaniu się do platformy Azure AzureServiceTokenProvider użyj jednostki usługi do pobrania tokenu na potrzeby programowania lokalnego.

Takie podejście dotyczy tylko programowania lokalnego. Po wdrożeniu rozwiązania na platformie Azure biblioteka przełącza się do tożsamości zarządzanej na potrzeby uwierzytelniania.

Uruchamianie aplikacji przy użyciu tożsamości zarządzanej lub tożsamości przypisanej przez użytkownika

Po uruchomieniu kodu na Azure App Service lub maszynie wirtualnej platformy Azure z włączoną tożsamością zarządzaną biblioteka automatycznie używa tożsamości zarządzanej. Nie są wymagane żadne zmiany w kodzie, ale tożsamość zarządzana musi mieć uprawnienia do zasobów, do których będzie próbował uzyskać dostęp. Na przykład zasady dostępu są wymagane, aby tożsamość zarządzana uzyskiwała dostęp do wszystkich wpisów tajnych w magazynie kluczy.

Alternatywnie możesz uwierzytelnić się przy użyciu tożsamości przypisanej przez użytkownika. Aby uzyskać więcej informacji na temat tożsamości przypisanych przez użytkownika, zobacz About Managed Identities for Azure resources (Informacje o tożsamościach zarządzanych dla zasobów platformy Azure). Aby uwierzytelnić się przy użyciu tożsamości przypisanej przez użytkownika, należy określić identyfikator klienta tożsamości przypisanej przez użytkownika w parametrach połączenia. Parametry połączenia są określone w obszarze Obsługa parametrów połączenia.

Uruchamianie aplikacji przy użyciu jednostki usługi

Może być konieczne utworzenie poświadczeń klienta Azure AD w celu uwierzytelnienia. Taka sytuacja może wystąpić w następujących przykładach:

  • Kod jest uruchamiany w lokalnym środowisku deweloperskim, ale nie w ramach tożsamości dewelopera. Na przykład usługa Service Fabric używa konta NetworkService do programowania lokalnego.

  • Kod działa w lokalnym środowisku projektowym i uwierzytelniasz się w usłudze niestandardowej, aby nie można było używać tożsamości dewelopera.

  • Kod jest uruchamiany w zasobie obliczeniowym platformy Azure, który nie obsługuje jeszcze tożsamości zarządzanych dla zasobów platformy Azure, takich jak Azure Batch.

Istnieją trzy podstawowe metody używania jednostki usługi do uruchamiania aplikacji. Aby użyć dowolnego z nich, należy najpierw utworzyć jednostkę usługi. Aby uzyskać więcej informacji, zobacz Tworzenie jednostki usługi platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

Logowanie się do Azure AD przy użyciu certyfikatu w lokalnym magazynie kluczy

  1. Utwórz certyfikat jednostki usługi przy użyciu polecenia az ad sp create-for-rbac interfejsu wiersza polecenia platformy Azure.

    az ad sp create-for-rbac --create-cert
    

    To polecenie tworzy plik pem (klucz prywatny), który jest przechowywany w katalogu głównym. Przekonwertuj plik pem na certyfikat PFX przy użyciu polecenia :

    openssl pkcs12 -export -in test.pem -out test.pfx
    
  2. Ustaw zmienną środowiskową o nazwie AzureServicesAuthConnectionString na następującą wartość:

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
          CertificateStoreLocation={CertificateStore}
    

    Zastąp {AppId}, {TenantId} i {Thumbprint} wartościami wygenerowanymi w kroku 1. Zastąp element {CertificateStore} ciągiem LocalMachine' lub CurrentUser na podstawie planu wdrożenia.

  3. Uruchom aplikację.

Logowanie się do Azure AD przy użyciu poświadczeń wspólnego wpisu tajnego

  1. Utwórz certyfikat jednostki usługi z hasłem przy użyciu polecenia az ad sp create-for-rbac interfejsu wiersza polecenia platformy Azure z parametrem --sdk-auth.

    az ad sp create-for-rbac --sdk-auth
    
  2. Ustaw zmienną środowiskową o nazwie AzureServicesAuthConnectionString na następującą wartość:

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
    

    Zastąp wartości {AppId}, {TenantId} i {ClientSecret} wartościami wygenerowanymi w kroku 1.

  3. Uruchom aplikację.

Po poprawnym skonfigurowaniu wszystkich elementów nie są wymagane żadne dalsze zmiany kodu. AzureServiceTokenProviderużywa zmiennej środowiskowej i certyfikatu do uwierzytelniania w Azure AD.

Zaloguj się do Azure AD przy użyciu certyfikatu w Key Vault

Ta opcja umożliwia przechowywanie certyfikatu klienta jednostki usługi w Key Vault i używanie go do uwierzytelniania jednostki usługi. Tej opcji można użyć w następujących scenariuszach:

  • Uwierzytelnianie lokalne, w którym chcesz uwierzytelnić się przy użyciu jawnej jednostki usługi i chcesz bezpiecznie przechowywać poświadczenia jednostki usługi w magazynie kluczy. Konto dewelopera musi mieć dostęp do magazynu kluczy.

  • Uwierzytelnianie z platformy Azure, w którym chcesz używać jawnych poświadczeń i chcesz bezpiecznie przechowywać poświadczenia jednostki usługi w magazynie kluczy. Ta opcja może być używana w scenariuszu między dzierżawami. Tożsamość zarządzana musi mieć dostęp do magazynu kluczy.

Tożsamość zarządzana lub tożsamość dewelopera musi mieć uprawnienia do pobierania certyfikatu klienta z Key Vault. Biblioteka AppAuthentication używa pobranego certyfikatu jako poświadczenia klienta jednostki usługi.

Aby użyć certyfikatu klienta do uwierzytelniania jednostki usługi:

  1. Utwórz certyfikat jednostki usługi i automatycznie zapisz go w Key Vault. Użyj polecenia interfejsu wiersza polecenia platformy Azure az ad sp create-for-rbac --keyvault keyvaultname <--cert <certificatename>> --create-cert --skip-assignment:

    az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
    

    Identyfikator certyfikatu będzie adresem URL w formacie https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

  2. Zastąp {KeyVaultCertificateSecretIdentifier} wartość w tych parametrach połączenia identyfikatorem certyfikatu:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
    

    Jeśli na przykład magazyn kluczy nosi nazwę myKeyVault i utworzono certyfikat o nazwie myCert, identyfikator certyfikatu będzie:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
    

Obsługa parametrów połączenia

Domyślnie AzureServiceTokenProvider próbuje wykonać następujące metody uwierzytelniania w celu pobrania tokenu:

Aby kontrolować proces, użyj parametrów połączenia przekazanych do konstruktora AzureServiceTokenProvider lub określonego w zmiennej środowiskowej AzureServicesAuthConnectionString . Obsługiwane są następujące opcje:

Opcja parametrów połączenia Scenariusz Komentarze
RunAs=Developer;DeveloperTool=AzureCli Programowanie lokalne AzureServiceTokenProvider używa narzędzia AzureCli do uzyskiwania tokenu.
RunAs=Developer;DeveloperTool=VisualStudio Programowanie lokalne AzureServiceTokenProvider używa programu Visual Studio do pobierania tokenu.
RunAs=CurrentUser Programowanie lokalne Nieobsługiwane na platformie .NET Core. AzureServiceTokenProviderużywa Azure AD zintegrowanego uwierzytelniania w celu uzyskania tokenu.
RunAs=App Tożsamości zarządzane dla zasobów platformy Azure AzureServiceTokenProvider używa tożsamości zarządzanej do pobrania tokenu.
RunAs=App;AppId={ClientId of user-assigned identity} Tożsamość przypisana przez użytkownika dla zasobów platformy Azure AzureServiceTokenProvider używa tożsamości przypisanej przez użytkownika do uzyskiwania tokenu.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier} Uwierzytelnianie usług niestandardowych KeyVaultCertificateSecretIdentifier to identyfikator wpisu tajnego certyfikatu.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} Jednostka usługi AzureServiceTokenProviderużywa certyfikatu do pobierania tokenu z Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} Jednostka usługi AzureServiceTokenProviderużywa certyfikatu do pobierania tokenu z Azure AD
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Jednostka usługi AzureServiceTokenProviderużywa wpisu tajnego do pobierania tokenu z Azure AD.

Samples

Aby zobaczyć bibliotekę Microsoft.Azure.Services.AppAuthentication w działaniu, zapoznaj się z poniższymi przykładami kodu.

Rozwiązywanie problemów z uwierzytelnianiem aplikacji

Typowe problemy podczas programowania lokalnego

Interfejs wiersza polecenia platformy Azure nie jest zainstalowany, nie zalogowano się lub nie masz najnowszej wersji

Uruchom polecenie az account get-access-token , aby sprawdzić, czy w interfejsie wiersza polecenia platformy Azure jest wyświetlany token. Jeśli nie znaleziono takiego programu, zainstaluj najnowszą wersję interfejsu wiersza polecenia platformy Azure. Może zostać wyświetlony monit o zalogowanie się.

Dostawca AzureServiceTokenProvider nie może znaleźć ścieżki dla interfejsu wiersza polecenia platformy Azure

Dostawca AzureServiceTokenProvider szuka interfejsu wiersza polecenia platformy Azure w domyślnych lokalizacjach instalacji. Jeśli nie można odnaleźć interfejsu wiersza polecenia platformy Azure, ustaw zmienną środowiskową AzureCLIPath na folder instalacyjny interfejsu wiersza polecenia platformy Azure. Element AzureServiceTokenProvider doda zmienną środowiskową do zmiennej środowiskowej Path.

Zalogowano się do interfejsu wiersza polecenia platformy Azure przy użyciu wielu kont, to samo konto ma dostęp do subskrypcji w wielu dzierżawach lub wystąpił błąd Odmowa dostępu podczas próby wykonania wywołań podczas programowania lokalnego

Za pomocą interfejsu wiersza polecenia platformy Azure ustaw domyślną subskrypcję na taką, która ma konto, którego chcesz użyć. Subskrypcja musi znajdować się w tej samej dzierżawie co zasób, do którego chcesz uzyskać dostęp: az account set --subscription [subscription-id]. Jeśli żadne dane wyjściowe nie są widoczne, powiodło się. Sprawdź, czy właściwe konto jest teraz domyślne przy użyciu polecenia az account list.

Typowe problemy w różnych środowiskach

Nieautoryzowany dostęp, odmowa dostępu, dostęp zabroniony lub podobny błąd

Używany podmiot zabezpieczeń nie ma dostępu do zasobu, do którego próbuje uzyskać dostęp. Przyznaj swojemu kontu użytkownika lub tożsamości usługi zarządzanej usługi zarządzanej App Service "Współautor" dostęp do zasobu. Zależy to od tego, czy korzystasz z przykładu na komputerze lokalnym, czy wdrożono go na platformie Azure w App Service. Niektóre zasoby, takie jak magazyny kluczy, również mają własne zasady dostępu , których używasz do udzielania dostępu podmiotom zabezpieczeń, takim jak użytkownicy, aplikacje i grupy.

Typowe problemy występujące podczas wdrażania w Azure App Service

Tożsamość zarządzana nie jest skonfigurowana w App Service

Sprawdź, czy zmienne środowiskowe MSI_ENDPOINT i MSI_SECRET istnieją przy użyciu konsoli debugowania Kudu. Jeśli te zmienne środowiskowe nie istnieją, tożsamość zarządzana nie jest włączona w App Service.

Typowe problemy występujące podczas wdrażania lokalnego za pomocą usług IIS

Nie można pobrać tokenów podczas debugowania aplikacji w usługach IIS

Domyślnie usługa AppAuth jest uruchamiana w innym kontekście użytkownika w usługach IIS. Dlatego nie ma dostępu do używania tożsamości dewelopera do pobierania tokenów dostępu. Usługi IIS można skonfigurować do uruchamiania z kontekstem użytkownika, wykonując następujące dwa kroki:

  • Skonfiguruj pulę aplikacji dla aplikacji internetowej do uruchamiania jako bieżącego konta użytkownika. Zobacz więcej informacji tutaj

  • Skonfiguruj wartość "setProfileEnvironment" na wartość "True". Zobacz więcej informacji tutaj.

    • Przejdź do witryny %windir%\System32\inetsrv\config\applicationHost.config
    • Wyszukaj ciąg "setProfileEnvironment". Jeśli jest ustawiona wartość "Fałsz", zmień ją na "True". Jeśli nie istnieje, dodaj go jako atrybut do elementu processModel (/configuration/system.applicationHost/applicationPools/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) i ustaw go na wartość "True".
  • Dowiedz się więcej o tożsamościach zarządzanych dla zasobów platformy Azure.

  • Dowiedz się więcej o scenariuszach uwierzytelniania Azure AD.