Klientská knihovna ověřování aplikací pro .NET – verze 1.6.0

  • Článek

Poznámka

Microsoft.Azure.Services.AppAuthentication je vyřazený z provozu a už se nepodporuje ani neudržuje. Nahrazuje ji klientská knihovna Azure Identity , která je k dispozici pro .NET, Javu, TypeScript a Python. Informace o tom, jak migrovat do Azure Identity, najdete tady: Pokyny k migraci z AppAuthentication do Azure.Identity.

K ověřování ve službách Azure pomocí instančního objektu potřebujete přihlašovací údaje Azure Active Directory (Azure AD), a to buď sdílený tajný klíč, nebo certifikát.

Správa takových přihlašovacích údajů může být obtížná. Je lákavé sdružovat přihlašovací údaje do aplikace tím, že je zahrnete do zdrojových nebo konfiguračních souborů. Knihovna Microsoft.Azure.Services.AppAuthentication for .NET tento problém zjednodušuje. Používá přihlašovací údaje vývojáře k ověřování během místního vývoje. Po pozdějším nasazení řešení do Azure se knihovna automaticky přepne na přihlašovací údaje aplikace. Používání přihlašovacích údajů vývojáře během místního vývoje je bezpečnější, protože nemusíte vytvářet přihlašovací údaje Azure AD ani sdílet přihlašovací údaje mezi vývojáři.

Knihovna Microsoft.Azure.Services.AppAuthentication spravuje ověřování automaticky, což vám umožní soustředit se na řešení, a ne na přihlašovací údaje. Podporuje místní vývoj pomocí sady Microsoft Visual Studio, Azure CLI nebo integrovaného ověřování Azure AD. Při nasazení do prostředku Azure, který podporuje spravovanou identitu, knihovna automaticky používá spravované identity pro prostředky Azure. Nejsou vyžadovány žádné změny kódu ani konfigurace. Knihovna také podporuje přímé použití přihlašovacích údajů klienta Azure AD v případě, že spravovaná identita není k dispozici nebo když není možné určit kontext zabezpečení vývojáře během místního vývoje.

Zdrojový kód | Balíček (nuget) | Dokumentace ke službě Azure Active Directory

Požadavky

  • Visual Studio 2019 nebo Visual Studio 2017 v15.5.

  • Rozšíření Ověřování aplikací pro Visual Studio, které je k dispozici jako samostatné rozšíření pro Visual Studio 2017 Update 5 a je součástí produktu v aktualizaci Update 6 a novější. S aktualizací Update 6 nebo novější můžete ověřit instalaci rozšíření Ověřování aplikací tak, že v instalačním programu sady Visual Studio vyberete Vývojové nástroje Azure.

Použití knihovny

U aplikací .NET je nejjednodušším způsobem práce se spravovanou identitou prostřednictvím Microsoft.Azure.Services.AppAuthentication balíčku. Tady je postup, jak začít:

  1. Vyberte Nástroje> Správce >balíčků NuGetSpravovat balíčky NuGet pro řešení a přidejte odkazy na balíčky NuGet Microsoft.Azure.Services.AppAuthentication a Microsoft.Azure.KeyVault do projektu.

  2. Použití AzureServiceTokenProvider ke zjednodušení žádostí o přístupové tokeny pro klienty Azure, jako v následujících příkladech:

    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(); 
}

Třída bezpečná AzureServiceTokenProvider pro vlákna ukládá token do mezipaměti a načítá ho z Azure AD těsně před vypršením platnosti. To znamená, že před voláním metody nikdy nemusíte kontrolovat vypršení platnosti tokenu GetAccessTokenAsync .

Metoda GetAccessTokenAsync vyžaduje identifikátor prostředku. Další informace o službách Microsoft Azure najdete v tématu Co jsou spravované identity pro prostředky Azure.

Ověřování místního vývoje

Pro místní vývoj existují dva primární scénáře ověřování: ověřování ve službách Azure a ověřování ve vlastních službách.

Ověřování ve službách Azure

Místní počítače nepodporují spravované identity pro prostředky Azure. V důsledku toho Microsoft.Azure.Services.AppAuthentication knihovna používá vaše přihlašovací údaje pro vývojáře ke spuštění ve vašem místním vývojovém prostředí. Když se řešení nasadí do Azure, knihovna použije spravovanou identitu k přepnutí na tok udělení přihlašovacích údajů klienta OAuth 2.0. Tento přístup znamená, že stejný kód můžete testovat místně i vzdáleně bez obav.

Pro místní vývoj AzureServiceTokenProvider načítá tokeny pomocí sady Visual Studio, rozhraní příkazového řádku Azure (CLI) nebo Azure AD integrovaného ověřování. Každá možnost se postupně zkouší a knihovna použije první možnost, která bude úspěšná. Pokud žádná možnost nefunguje, vyvolá se AzureServiceTokenProviderException výjimka s podrobnými informacemi.

Ověřování pomocí sady Visual Studio

Ověření pomocí sady Visual Studio:

  1. Přihlaste se k sadě Visual Studio a pomocí nástroje>Možnosti otevřete Možnosti.

  2. Vyberte Ověřování služby Azure, zvolte účet pro místní vývoj a vyberte OK.

Pokud při používání sady Visual Studio narazíte na problémy, jako jsou chyby, které zahrnují soubor zprostředkovatele tokenu, pečlivě si projděte předchozí kroky.

Možná budete muset znovu provést ověření tokenu pro vývojáře. Uděláte to tak, že vyberete Možnosti nástrojů> a pak vyberete Ověřování služby Azure. Vyhledejte odkaz Pro opětovné ověření pod vybraným účtem. Vyberte ho a ověřte ho.

Ověřování pomocí Azure CLI

Pokud chcete k místnímu vývoji použít Azure CLI, ujistěte se, že máte verzi Azure CLI verze 2.0.12 nebo novější.

V Azure CLI postupujte takto:

  1. Vyhledejte Azure CLI na hlavním panelu Windows a otevřete příkazový řádek Microsoft Azure.

  2. Přihlaste se k Azure Portal: az login a přihlaste se k Azure.

  3. Ověřte přístup zadáním příkazu az account get-access-token --resource https://vault.azure.net. Pokud se zobrazí chyba, zkontrolujte, jestli je správně nainstalovaná správná verze Azure CLI.

    Pokud azure CLI není nainstalované do výchozího adresáře, může se zobrazit zpráva o chybě, která AzureServiceTokenProvider nemůže najít cestu pro Azure CLI. K definování instalační složky Azure CLI použijte proměnnou prostředí AzureCLIPath . AzureServiceTokenProvider V případě potřeby přidá adresář zadaný v proměnné prostředí AzureCLIPath do proměnné prostředí Path .

  4. Pokud jste přihlášení k Azure CLI pomocí více účtů nebo váš účet má přístup k více předplatným, musíte zadat předplatné, které se má použít. Zadejte příkaz az account set --subscription .

Tento příkaz vygeneruje výstup pouze při selhání. Pokud chcete ověřit aktuální nastavení účtu, zadejte příkaz az account list.

Ověřování pomocí ověřování Azure AD

Pokud chcete použít ověřování Azure AD, ověřte, že:

Ověřování ve vlastních službách

Když služba volá služby Azure, předchozí kroky fungují, protože služby Azure umožňují přístup uživatelům i aplikacím.

Při vytváření služby, která volá vlastní službu, použijte přihlašovací údaje klienta Azure AD pro ověřování místního vývoje. Existují dvě možnosti:

  • Přihlaste se k Azure pomocí instančního objektu:

    1. Vytvořte instanční objekt. Další informace najdete v tématu Vytvoření instančního objektu Azure pomocí Azure CLI.

    2. Pomocí Azure CLI se přihlaste pomocí následujícího příkazu:

      az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions

      Vzhledem k tomu, že instanční objekt nemusí mít přístup k předplatnému, použijte --allow-no-subscriptions argument .

  • K zadání podrobností instančního objektu použijte proměnné prostředí. Další informace najdete v tématu Spuštění aplikace pomocí instančního objektu.

Po přihlášení k Azure AzureServiceTokenProvider použije instanční objekt k načtení tokenu pro místní vývoj.

Tento přístup se vztahuje pouze na místní rozvoj. Po nasazení řešení do Azure se knihovna přepne na spravovanou identitu pro účely ověřování.

Spuštění aplikace pomocí spravované identity nebo identity přiřazené uživatelem

Když spustíte kód na Azure App Service nebo virtuálním počítači Azure s povolenou spravovanou identitou, knihovna automaticky použije spravovanou identitu. Nejsou vyžadovány žádné změny kódu, ale spravovaná identita musí mít oprávnění pro prostředky, ke kterým se pokusí získat přístup. Například zásady přístupu se vyžadují, aby spravovaná identita přistupovala k tajným kódům v trezoru klíčů.

Případně se můžete ověřit pomocí identity přiřazené uživatelem. Další informace o identitách přiřazených uživatelem najdete v tématu o spravovaných identitách pro prostředky Azure. Pokud chcete ověřit identitu přiřazenou uživatelem, musíte v připojovacím řetězci zadat ID klienta identity přiřazené uživatelem. Připojovací řetězec je zadaný v části Podpora připojovacího řetězce.

Spuštění aplikace pomocí instančního objektu

Pro ověření může být nutné vytvořit přihlašovací údaje klienta Azure AD. K této situaci může dojít v následujících příkladech:

  • Váš kód běží v místním vývojovém prostředí, ale ne pod identitou vývojáře. Service Fabric například používá účet NetworkService pro místní vývoj.

  • Váš kód běží v místním vývojovém prostředí a vy se ověřujete ve vlastní službě, takže nemůžete použít svoji vývojářskou identitu.

  • Váš kód běží na výpočetním prostředku Azure, který zatím nepodporuje spravované identity pro prostředky Azure, jako je Azure Batch.

Existují tři primární metody použití instančního objektu ke spuštění aplikace. Pokud chcete některou z nich použít, musíte nejprve vytvořit instanční objekt. Další informace najdete v tématu Vytvoření instančního objektu Azure pomocí Azure CLI.

Použití certifikátu v místním úložišti klíčů k přihlášení k Azure AD

  1. Vytvořte certifikát instančního objektu pomocí příkazu Azure CLI az ad sp create-for-rbac .

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

    Tento příkaz vytvoří soubor .pem (privátní klíč), který je uložený ve vašem domovském adresáři. Pomocí příkazu převeďte soubor .pem na certifikát PFX:

    openssl pkcs12 -export -in test.pem -out test.pfx

  2. Proměnnou prostředí s názvem AzureServicesAuthConnectionString nastavte na následující hodnotu:

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

    Nahraďte {AppId}, {TenantId} a {Thumbprint} hodnotami vygenerovanými v kroku 1. Nahraďte {CertificateStore} hodnotou LocalMachine' nebo CurrentUser na základě vašeho plánu nasazení.

  3. Spusťte aplikaci.

Použití přihlašovacích údajů sdíleného tajného klíče k přihlášení k Azure AD

  1. Pomocí příkazu Azure CLI az ad sp create-for-rbac s parametrem --sdk-auth vytvořte certifikát instančního objektu s heslem.

    az ad sp create-for-rbac --sdk-auth

  2. Proměnnou prostředí s názvem AzureServicesAuthConnectionString nastavte na následující hodnotu:

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

    Nahraďte {AppId}, {TenantId} a {ClientSecret} hodnotami vygenerovanými v kroku 1.

  3. Spusťte aplikaci.

Jakmile je vše správně nastavené, nebudou potřeba žádné další změny kódu. AzureServiceTokenProviderpoužívá proměnnou prostředí a certifikát k ověření pro Azure AD.

Přihlášení k Azure AD pomocí certifikátu v Key Vault

Tato možnost umožňuje uložit klientský certifikát instančního objektu v Key Vault a použít ho k ověřování instančního objektu. Tuto možnost můžete použít v následujících scénářích:

  • Místní ověřování, kde chcete ověřit pomocí explicitního instančního objektu a chcete bezpečně uchovávat přihlašovací údaje instančního objektu v trezoru klíčů. Vývojářský účet musí mít přístup k trezoru klíčů.

  • Ověřování z Azure, kde chcete použít explicitní přihlašovací údaje a chcete bezpečně uchovávat přihlašovací údaje instančního objektu v trezoru klíčů. Tuto možnost můžete použít pro scénář mezi tenanty. Spravovaná identita musí mít přístup k trezoru klíčů.

Spravovaná identita nebo identita vývojáře musí mít oprávnění k načtení klientského certifikátu z Key Vault. Knihovna AppAuthentication používá načtený certifikát jako přihlašovací údaje klienta instančního objektu.

Použití klientského certifikátu pro ověřování instančního objektu:

  1. Vytvořte certifikát instančního objektu a automaticky ho uložte do Key Vault. Použijte příkaz Azure CLI 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

    Identifikátor certifikátu bude adresa URL ve formátu. https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

  2. Nahraďte {KeyVaultCertificateSecretIdentifier} v tomto připojovacím řetězci identifikátorem certifikátu:

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

    Pokud se například váš trezor klíčů jmenoval myKeyVault a vytvořili jste certifikát myCert, identifikátor certifikátu bude:

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

Podpora připojovacích řetězců

Ve výchozím nastavení AzureServiceTokenProvider se pokusí načíst token pomocí následujících metod ověřování:

K řízení procesu použijte připojovací řetězec předaný konstruktoru AzureServiceTokenProvider nebo zadaný v proměnné prostředí AzureServicesAuthConnectionString . Podporují se následující možnosti:

Možnost připojovacího řetězce Scenario Komentáře
RunAs=Developer;DeveloperTool=AzureCli Místní vývoj AzureServiceTokenProvider k získání tokenu používá AzureCli.
RunAs=Developer;DeveloperTool=VisualStudio Místní vývoj AzureServiceTokenProvider k získání tokenu používá sadu Visual Studio.
RunAs=CurrentUser Místní vývoj V .NET Core se nepodporuje. AzureServiceTokenProviderk získání tokenu používá Azure AD integrované ověřování.
RunAs=App Spravované identity pro prostředky Azure AzureServiceTokenProvider používá spravovanou identitu k získání tokenu.
RunAs=App;AppId={ClientId of user-assigned identity} Identita přiřazená uživatelem pro prostředky Azure AzureServiceTokenProvider k získání tokenu používá identitu přiřazenou uživatelem.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier} Ověřování vlastních služeb KeyVaultCertificateSecretIdentifier je identifikátor tajného klíče certifikátu.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} Instanční objekt AzureServiceTokenProviderk získání tokenu z Azure AD používá certifikát.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} Instanční objekt AzureServiceTokenProviderk získání tokenu z Azure AD používá certifikát.
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Instanční objekt AzureServiceTokenProviderk získání tokenu z Azure AD používá tajný kód.

ukázky

Pokud chcete zobrazit knihovnu Microsoft.Azure.Services.AppAuthentication v akci, projděte si následující ukázky kódu.

Řešení potíží s ověřováním aplikací

Běžné problémy při místním vývoji

Azure CLI není nainstalované, nejste přihlášení nebo nemáte nejnovější verzi.

Spuštěním příkazu az account get-access-token zkontrolujte, jestli azure CLI zobrazuje token. Pokud se zobrazí zpráva, že žádný takový program nebyl nalezen, nainstalujte nejnovější verzi Azure CLI. Může se zobrazit výzva k přihlášení.

AzureServiceTokenProvider nemůže najít cestu pro Azure CLI

AzureServiceTokenProvider hledá Azure CLI ve výchozím umístění instalace. Pokud azure CLI nenajde, nastavte proměnnou prostředí AzureCLIPath na instalační složku Azure CLI. AzureServiceTokenProvider přidá proměnnou prostředí do proměnné prostředí Path.

Jste přihlášení k Azure CLI pomocí více účtů, stejný účet má přístup k předplatným ve více tenantech nebo se vám při pokusu o volání během místního vývoje zobrazí chyba Přístup odepřen.

Pomocí Azure CLI nastavte výchozí předplatné na předplatné, které má účet, který chcete použít. Předplatné musí být ve stejném tenantovi jako prostředek, ke který chcete získat přístup: az account set --subscription [subscription-id]. Pokud se nezobrazí žádný výstup, byl úspěšný. Pomocí příkazu az account list ověřte, že je teď správný účet výchozí.

Běžné problémy napříč prostředími

Chyba typu Neoprávněný přístup, Přístup odepřen, Zakázáno nebo podobná chyba

Použitý objekt zabezpečení nemá přístup k prostředku, ke kterému se pokouší získat přístup. Udělte přístup ke svému uživatelskému účtu nebo přispěvateli MSI App Service k prostředku. Který z nich závisí na tom, jestli ukázku spouštíte na místním počítači, nebo jestli ji nasazujete v Azure do App Service. Některé prostředky, jako jsou trezory klíčů, mají také vlastní zásady přístupu , které používáte k udělení přístupu k objektům zabezpečení, jako jsou uživatelé, aplikace a skupiny.

Běžné problémy při nasazení do Azure App Service

Spravovaná identita není nastavená na App Service

Pomocí konzoly ladění Kudu zkontrolujte, MSI_ENDPOINT a MSI_SECRET existují proměnné prostředí. Pokud tyto proměnné prostředí neexistují, spravovaná identita není na App Service povolená.

Běžné problémy při místním nasazení se službou IIS

Při ladění aplikace ve službě IIS nejde načíst tokeny

Ve výchozím nastavení se AppAuth spouští v jiném kontextu uživatele ve službě IIS. Proto nemá přístup k použití vaší vývojářské identity k načtení přístupových tokenů. Službu IIS můžete nakonfigurovat tak, aby běžela s kontextem uživatele, a to pomocí následujících dvou kroků:

  • Nakonfigurujte fond aplikací pro webovou aplikaci tak, aby běžela jako váš aktuální uživatelský účet. Další informace najdete tady.

  • Nakonfigurujte "setProfileEnvironment" na "True". Další informace najdete tady.

    • Přejít na %windir%\System32\inetsrv\config\applicationHost.config
    • Vyhledejte "setProfileEnvironment". Pokud je nastavená na Nepravda, změňte ji na True. Pokud neexistuje, přidejte ho jako atribut do elementu processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) a nastavte ho na True.

  • Přečtěte si další informace o spravovaných identitách pro prostředky Azure.

  • Přečtěte si další informace o scénářích ověřování Azure AD.