Klientbibliotek för appautentisering för .NET – version 1.6.0

Artikel
04/03/2023

Anteckning

Microsoft.Azure.Services.AppAuthentication har dragits tillbaka och stöds inte längre eller underhålls inte. Det ersätts av Azure Identity-klientbiblioteket som är tillgängligt för .NET, Java, TypeScript och Python. Information om hur du migrerar till Azure Identityfinns här: Vägledning för AppAuthentication till Azure.Identity Migration.

Om du vill autentisera till Azure-tjänster med tjänstens huvudnamn behöver du en autentiseringsuppgift för Azure Active Directory (Azure AD), antingen en delad hemlighet eller ett certifikat.

Det kan vara svårt att hantera sådana autentiseringsuppgifter. Det är frestande att paketera autentiseringsuppgifter i en app genom att inkludera dem i käll- eller konfigurationsfiler. För Microsoft.Azure.Services.AppAuthentication .NET-biblioteket förenklar det här problemet. Den använder utvecklarens autentiseringsuppgifter för att autentisera under lokal utveckling. När lösningen senare distribueras till Azure växlar biblioteket automatiskt till programautentiseringsuppgifter. Att använda autentiseringsuppgifter för utvecklare under lokal utveckling är säkrare eftersom du inte behöver skapa Azure AD autentiseringsuppgifter eller dela autentiseringsuppgifter mellan utvecklare.

Biblioteket Microsoft.Azure.Services.AppAuthentication hanterar autentisering automatiskt, vilket i sin tur gör att du kan fokusera på din lösning i stället för dina autentiseringsuppgifter. Den stöder lokal utveckling med Microsoft Visual Studio, Azure CLI eller Azure AD integrerad autentisering. När biblioteket distribueras till en Azure-resurs som stöder en hanterad identitet använder det automatiskt hanterade identiteter för Azure-resurser. Inga kod- eller konfigurationsändringar krävs. Biblioteket stöder också direkt användning av Azure AD klientautentiseringsuppgifter när en hanterad identitet inte är tillgänglig eller när utvecklarens säkerhetskontext inte kan fastställas under den lokala utvecklingen.

Källkod | Paket (nuget) | Dokumentation om Azure Active Directory

Förutsättningar

Visual Studio 2019 eller Visual Studio 2017 v15.5.
Appautentiseringstillägget för Visual Studio finns som ett separat tillägg för Visual Studio 2017 Update 5 och paketeras med produkten i uppdatering 6 och senare. Med uppdatering 6 eller senare kan du verifiera installationen av appautentiseringstillägget genom att välja Azure Development-verktyg inifrån Installationsprogrammet för Visual Studio.

Använda biblioteket

För .NET-program är det enklaste sättet att arbeta med en hanterad identitet via Microsoft.Azure.Services.AppAuthentication paketet. Så här kommer du igång:

Välj Verktyg>NuGet Package Manager>Hantera NuGet-paket för lösning för att lägga till referenser till NuGet-paketen Microsoft.Azure.Services.AppAuthentication och Microsoft.Azure.KeyVault i projektet.

Använd AzureServiceTokenProvider för att förenkla begäran om åtkomsttoken för dina Azure-klienter, som i exemplen nedan:

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

Den trådsäkra AzureServiceTokenProvider klassen cachelagrar token i minnet och hämtar den från Azure AD strax före förfallodatumet. Det innebär att du aldrig behöver kontrollera förfallodatumet för token innan du anropar GetAccessTokenAsync metoden.

Metoden GetAccessTokenAsync kräver en resursidentifierare. Mer information om Microsoft Azure-tjänster finns i Vad är hanterade identiteter för Azure-resurser.

Autentisering för lokal utveckling

För lokal utveckling finns det två primära autentiseringsscenarier: autentisera till Azure-tjänster och autentisera till anpassade tjänster.

Autentisera till Azure Services

Lokala datorer stöder inte hanterade identiteter för Azure-resurser. Microsoft.Azure.Services.AppAuthentication Därför använder biblioteket dina autentiseringsuppgifter för utvecklare för att köras i din lokala utvecklingsmiljö. När lösningen distribueras till Azure använder biblioteket en hanterad identitet för att växla till ett OAuth 2.0-flöde för tilldelning av klientautentiseringsuppgifter. Den här metoden innebär att du kan testa samma kod lokalt och via fjärranslutning utan att oroa dig.

För lokal utveckling AzureServiceTokenProvider hämtar token med visual studio, Azure-kommandoradsgränssnitt (CLI) eller Azure AD integrerad autentisering. Varje alternativ provas sekventiellt och biblioteket använder det första alternativet som lyckas. Om inget alternativ fungerar genereras ett AzureServiceTokenProviderException undantag med detaljerad information.

Autentisera med Visual Studio

Så här autentiserar du med hjälp av Visual Studio:

Logga in i Visual Studio och använd Verktygsalternativ> för att öppna Alternativ.
Välj Azure Service Authentication, välj ett konto för lokal utveckling och välj OK.

Om du stöter på problem med att använda Visual Studio, till exempel fel som involverar tokenproviderfilen, bör du noggrant granska föregående steg.

Du kan behöva autentisera din utvecklartoken igen. Det gör du genom att välja Verktygsalternativ> och sedan Azure Service Authentication. Leta efter en återautentiseringslänk under det valda kontot. Välj den för att autentisera.

Autentisera med Azure CLI

Om du vill använda Azure CLI för lokal utveckling måste du ha version Azure CLI v2.0.12 eller senare.

Med Azure CLI gör du så här:

Sök efter Azure CLI i Aktivitetsfältet i Windows för att öppna Microsoft Azure-kommandotolken.
Logga in på Azure Portal: az login för att logga in på Azure.
Verifiera åtkomsten genom att ange az account get-access-token --resource https://vault.azure.net. Om du får ett fel kontrollerar du att rätt version av Azure CLI är korrekt installerad.

Om Azure CLI inte är installerat i standardkatalogen kan du få en felrapportering som AzureServiceTokenProvider inte kan hitta sökvägen för Azure CLI. Använd miljövariabeln AzureCLIPath för att definiera Installationsmappen för Azure CLI. AzureServiceTokenProvider lägger till katalogen som anges i Miljövariabeln AzureCLIPath till variabeln Sökvägsmiljö vid behov.
Om du är inloggad i Azure CLI med flera konton eller om ditt konto har åtkomst till flera prenumerationer måste du ange vilken prenumeration som ska användas. Ange kommandot az account set --subscription .

Det här kommandot genererar endast utdata vid fel. Om du vill verifiera de aktuella kontoinställningarna anger du kommandot az account list.

Autentisera med Azure AD-autentisering

Om du vill använda Azure AD autentisering kontrollerar du att:

Din lokal Active Directory synkroniseras till Azure AD. Mer information finns i Vad är hybrididentitet med Azure Active Directory?.
Koden körs på en domänansluten dator.

Autentisera till anpassade tjänster

När en tjänst anropar Azure-tjänster fungerar de föregående stegen eftersom Azure-tjänster tillåter åtkomst till både användare och program.

När du skapar en tjänst som anropar en anpassad tjänst använder du Azure AD klientautentiseringsuppgifter för lokal utvecklingsautentisering. Det finns två alternativ:

Använd tjänstens huvudnamn för att logga in på Azure:
1. Skapa ett huvudnamn för tjänsten. Mer information finns i Skapa ett Huvudnamn för Azure-tjänsten med Azure CLI.
2. Använd Azure CLI för att logga in med följande kommando:
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  Eftersom tjänstens huvudnamn kanske inte har åtkomst till en prenumeration använder du --allow-no-subscriptions argumentet .
Använd miljövariabler för att ange information om tjänstens huvudnamn. Mer information finns i Köra programmet med ett huvudnamn för tjänsten.

När du har loggat in på Azure AzureServiceTokenProvider använder du tjänstens huvudnamn för att hämta en token för lokal utveckling.

Den här metoden gäller endast för lokal utveckling. När din lösning distribueras till Azure växlar biblioteket till en hanterad identitet för autentisering.

Köra programmet med hanterad identitet eller användartilldelad identitet

När du kör koden på en Azure App Service eller en virtuell Azure-dator med en aktiverad hanterad identitet använder biblioteket automatiskt den hanterade identiteten. Inga kodändringar krävs, men den hanterade identiteten måste ha behörighet för de resurser som den försöker komma åt. Åtkomstprinciper krävs till exempel för att en hanterad identitet ska få åtkomst till hemligheter i ett nyckelvalv.

Du kan också autentisera med en användartilldelad identitet. Mer information om användartilldelade identiteter finns i Om hanterade identiteter för Azure-resurser. Om du vill autentisera med en användartilldelad identitet måste du ange klient-ID för den användartilldelade identiteten i anslutningssträngen. Anslutningssträngen anges i Stöd för anslutningssträng.

Köra programmet med hjälp av tjänstens huvudnamn

Det kan vara nödvändigt att skapa en Azure AD klientautentiseringsuppgifter för att autentisera. Den här situationen kan inträffa i följande exempel:

Koden körs i en lokal utvecklingsmiljö, men inte under utvecklarens identitet. Service Fabric använder till exempel NetworkService-kontot för lokal utveckling.
Koden körs i en lokal utvecklingsmiljö och du autentiserar till en anpassad tjänst, så att du inte kan använda utvecklaridentiteten.
Koden körs på en Azure-beräkningsresurs som ännu inte stöder hanterade identiteter för Azure-resurser, till exempel Azure Batch.

Det finns tre primära metoder för att använda tjänstens huvudnamn för att köra programmet. Om du vill använda någon av dem måste du först skapa ett huvudnamn för tjänsten. Mer information finns i Skapa ett huvudnamn för Azure-tjänsten med Azure CLI.

Använda ett certifikat i det lokala nyckelarkivet för att logga in på Azure AD

Skapa ett certifikat för tjänstens huvudnamn med hjälp av kommandot Azure CLI az ad sp create-for-rbac .
```
az ad sp create-for-rbac --create-cert
```
Det här kommandot skapar en .pem-fil (privat nyckel) som lagras i din hemkatalog. Konvertera .pem-filen till ett PFX-certifikat med kommandot :
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
Ange följande värde för en miljövariabel med namnet AzureServicesAuthConnectionString :
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
Ersätt {AppId}, {TenantId} och {Thumbprint} med värden som genererades i steg 1. Ersätt {CertificateStore} med Antingen LocalMachine' eller CurrentUser, baserat på din distributionsplan.
Kör appen.

Använd en delad hemlighetsautentiseringsuppgift för att logga in på Azure AD

Skapa ett certifikat för tjänstens huvudnamn med ett lösenord med hjälp av kommandot Azure CLI az ad sp create-for-rbac med parametern --sdk-auth.
```
az ad sp create-for-rbac --sdk-auth
```
Ange följande värde för en miljövariabel med namnet AzureServicesAuthConnectionString :
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
Ersätt {AppId}, {TenantId} och {ClientSecret} med värden som genererades i steg 1.
Kör appen.

När allt har konfigurerats korrekt behövs inga ytterligare kodändringar. AzureServiceTokenProvideranvänder miljövariabeln och certifikatet för att autentisera till Azure AD.

Använda ett certifikat i Key Vault för att logga in på Azure AD

Med det här alternativet kan du lagra klientcertifikatet för tjänstens huvudnamn i Key Vault och använda det för autentisering med tjänstens huvudnamn. Du kan använda det här alternativet för följande scenarier:

Lokal autentisering, där du vill autentisera med hjälp av ett explicit tjänsthuvudnamn och vill behålla autentiseringsuppgifterna för tjänstens huvudnamn på ett säkert sätt i ett nyckelvalv. Utvecklarkontot måste ha åtkomst till nyckelvalvet.
Autentisering från Azure där du vill använda explicita autentiseringsuppgifter och vill skydda autentiseringsuppgifterna för tjänstens huvudnamn i ett nyckelvalv. Du kan använda det här alternativet för ett scenario mellan klientorganisationer. Hanterad identitet måste ha åtkomst till nyckelvalvet.

Den hanterade identiteten eller utvecklaridentiteten måste ha behörighet att hämta klientcertifikatet från Key Vault. AppAuthentication-biblioteket använder det hämtade certifikatet som tjänstens huvudnamns klientautentiseringsuppgift.

Så här använder du ett klientcertifikat för autentisering av tjänstens huvudnamn:

Skapa ett certifikat för tjänstens huvudnamn och lagra det automatiskt i Key Vault. Använd Azure CLI az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment command:
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
Certifikatidentifieraren är en URL i formatet https://<keyvaultname>.vault.azure.net/secrets/<certificatename>
Ersätt {KeyVaultCertificateSecretIdentifier} i den här anslutningssträngen med certifikatidentifieraren:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
Om ditt nyckelvalv till exempel kallades myKeyVault och du skapade ett certifikat med namnet myCert skulle certifikatidentifieraren vara:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

Stöd för anslutningssträngar

Som standard AzureServiceTokenProvider provar du följande autentiseringsmetoder för att hämta en token:

En hanterad identitet för Azure-resurser
Visual Studio-autentisering
Azure CLI-autentisering
Integrerad Windows-autentisering

Om du vill styra processen använder du en anslutningssträng som skickas till AzureServiceTokenProvider konstruktorn eller anges i miljövariabeln AzureServicesAuthConnectionString . Följande alternativ stöds:

Alternativ för anslutningssträng	Scenario	Kommentarer
`RunAs=Developer;DeveloperTool=AzureCli`	Lokal utveckling	`AzureServiceTokenProvider` använder AzureCli för att hämta token.
`RunAs=Developer;DeveloperTool=VisualStudio`	Lokal utveckling	`AzureServiceTokenProvider` använder Visual Studio för att hämta token.
`RunAs=CurrentUser`	Lokal utveckling	Stöds inte i .NET Core. `AzureServiceTokenProvider`använder Azure AD integrerad autentisering för att hämta token.
`RunAs=App`	Hanterade identiteter för Azure-resurser	`AzureServiceTokenProvider` använder en hanterad identitet för att hämta token.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Användartilldelad identitet för Azure-resurser	`AzureServiceTokenProvider` använder en användartilldelad identitet för att hämta token.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	Autentisering med anpassade tjänster	`KeyVaultCertificateSecretIdentifier` är certifikatets hemliga identifierare.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	Tjänstens huvudnamn	`AzureServiceTokenProvider`använder certifikat för att hämta token från Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	Tjänstens huvudnamn	`AzureServiceTokenProvider`använder certifikat för att hämta token från Azure AD
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	Tjänstens huvudnamn	`AzureServiceTokenProvider`använder hemlighet för att hämta token från Azure AD.

Exempel

Om du vill se biblioteket Microsoft.Azure.Services.AppAuthentication i praktiken läser du följande kodexempel.

Felsökning av appauthentication

Vanliga problem under lokal utveckling

Azure CLI är inte installerat, du är inte inloggad eller så har du inte den senaste versionen

Kör az account get-access-token för att se om Azure CLI visar en token åt dig. Om det står att inget sådant program hittades installerar du den senaste versionen av Azure CLI. Du kan bli uppmanad att logga in.

AzureServiceTokenProvider kan inte hitta sökvägen för Azure CLI

AzureServiceTokenProvider söker efter Azure CLI på standardinstallationsplatserna. Om det inte går att hitta Azure CLI anger du miljövariabeln AzureCLIPath till installationsmappen för Azure CLI. AzureServiceTokenProvider lägger till miljövariabeln i miljövariabeln Sökväg.

Du är inloggad i Azure CLI med flera konton, samma konto har åtkomst till prenumerationer i flera klientorganisationer eller så får du ett felmeddelande om nekad åtkomst när du försöker göra anrop under lokal utveckling

Använd Azure CLI och ställ in standardprenumerationen på en prenumeration som har det konto som du vill använda. Prenumerationen måste finnas i samma klientorganisation som den resurs som du vill komma åt: az account set --subscription [subscription-id]. Om inga utdata visas lyckades det. Kontrollera att rätt konto nu är standard med az account list.

Vanliga problem i miljöer

Obehörig åtkomst, åtkomst nekad, förbjudet eller liknande fel

Huvudkontot som används har inte åtkomst till resursen som det försöker få åtkomst till. Bevilja antingen ditt användarkonto eller App Service MSI-deltagare åtkomst till en resurs. Vilken beror på om du kör exemplet på din lokala dator eller distribueras i Azure till din App Service. Vissa resurser, till exempel nyckelvalv, har också egna åtkomstprinciper som du använder för att bevilja åtkomst till huvudkonton, till exempel användare, appar och grupper.

Vanliga problem vid distribution till Azure App Service

Hanterad identitet har inte konfigurerats på App Service

Kontrollera miljövariablerna MSI_ENDPOINT och MSI_SECRET finns med hjälp av Kudu-felsökningskonsolen. Om dessa miljövariabler inte finns aktiveras inte hanterad identitet på App Service.

Vanliga problem när de distribueras lokalt med IIS

Det går inte att hämta token vid felsökning av appen i IIS

Som standard körs AppAuth i en annan användarkontext i IIS. Det är därför den inte har åtkomst att använda din utvecklaridentitet för att hämta åtkomsttoken. Du kan konfigurera IIS att köras med användarkontexten med följande två steg:

Konfigurera programpoolen för webbappen så att den körs som ditt aktuella användarkonto. Se mer information här
Konfigurera "setProfileEnvironment" till "True". Se mer information här.
- Gå till %windir%\System32\inetsrv\config\applicationHost.config
- Sök efter "setProfileEnvironment". Om den är inställd på "False" ändrar du den till "True". Om det inte finns lägger du till det som ett attribut till processModel-elementet (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) och ställer in det på "True".
Läs mer om hanterade identiteter för Azure-resurser.
Läs mer om Azure AD autentiseringsscenarier.