Clientbibliotheek voor app-verificatie voor .NET - versie 1.6.0

Artikel
04/03/2023

Notitie

Microsoft.Azure.Services.AppAuthentication is buiten gebruik gesteld en wordt niet meer ondersteund of onderhouden. Deze wordt vervangen door de Azure Identity-clientbibliotheek die beschikbaar is voor .NET, Java, TypeScript en Python. Informatie over hoe u migreert naar Azure Identityvindt u hier: AppAuthentication to Azure.Identity Migration Guidance(Richtlijnen voor identiteitsmigratie).

Als u zich wilt verifiëren bij Azure-services met een service-principal, hebt u een Azure Active Directory-referentie (Azure AD) nodig, een gedeeld geheim of een certificaat.

Het beheren van dergelijke referenties kan lastig zijn. Het is verleidelijk om referenties te bundelen in een app door ze op te slaan in bron- of configuratiebestanden. De Microsoft.Azure.Services.AppAuthentication voor .NET-bibliotheek vereenvoudigt dit probleem. Hierbij worden de referenties van de ontwikkelaar gebruikt om te verifiëren tijdens de lokale ontwikkeling. Wanneer de oplossing later in Azure wordt geïmplementeerd, schakelt de bibliotheek automatisch over naar toepassingsreferenties. Het gebruik van referenties voor ontwikkelaars tijdens lokale ontwikkeling is veiliger omdat u geen Azure AD referenties hoeft te maken of referenties tussen ontwikkelaars hoeft te delen.

De Microsoft.Azure.Services.AppAuthentication bibliotheek beheert verificatie automatisch, waardoor u zich op uw oplossing kunt richten in plaats van op uw referenties. Het ondersteunt lokale ontwikkeling met Microsoft Visual Studio, Azure CLI of Azure AD Integrated Authentication. Wanneer deze wordt geïmplementeerd in een Azure-resource die ondersteuning biedt voor een beheerde identiteit, gebruikt de bibliotheek automatisch beheerde identiteiten voor Azure-resources. Er zijn geen code- of configuratiewijzigingen vereist. De bibliotheek ondersteunt ook direct gebruik van Azure AD clientreferenties wanneer er geen beheerde identiteit beschikbaar is of wanneer de beveiligingscontext van de ontwikkelaar niet kan worden bepaald tijdens de lokale ontwikkeling.

Broncode | Pakket (nuget) | Documentatie voor Azure Active Directory

Vereisten

Visual Studio 2019 of Visual Studio 2017 v15.5.
De app-verificatie-extensie voor Visual Studio, beschikbaar als een afzonderlijke extensie voor Visual Studio 2017 Update 5 en gebundeld met het product in Update 6 en hoger. Met Update 6 of hoger kunt u de installatie van de app-verificatie-extensie controleren door Azure-ontwikkelhulpprogramma's te selecteren in het Visual Studio-installatieprogramma.

De bibliotheek gebruiken

Voor .NET-toepassingen is de eenvoudigste manier om met een beheerde identiteit te werken via het Microsoft.Azure.Services.AppAuthentication pakket. Stappen om aan de slag te gaan:

Selecteer Hulpprogramma's>NuGet Package Manager>NuGet-pakketten beheren voor oplossing om verwijzingen naar de NuGet-pakketten Microsoft.Azure.Services.AppAuthentication en Microsoft.Azure.KeyVault NuGet-pakketten toe te voegen aan uw project.

Gebruik AzureServiceTokenProvider om het aanvragen van toegangstokens voor uw Azure-clients te vereenvoudigen, zoals in de onderstaande voorbeelden:

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

De thread-safe-klasse AzureServiceTokenProvider slaat het token op in het geheugen en haalt het op uit Azure AD vlak voor de vervaldatum. Dat betekent dat u nooit de vervaldatum van het token hoeft te controleren voordat u de GetAccessTokenAsync methode aanroept.

Voor de GetAccessTokenAsync methode is een resource-id vereist. Zie Wat zijn beheerde identiteiten voor Azure-resources voor meer informatie over Microsoft Azure-services.

Verificatie voor lokale ontwikkeling

Voor lokale ontwikkeling zijn er twee primaire verificatiescenario's: verificatie bij Azure-services en verificatie bij aangepaste services.

Verificatie bij Azure-services

Lokale machines bieden geen ondersteuning voor beheerde identiteiten voor Azure-resources. Als gevolg hiervan gebruikt de Microsoft.Azure.Services.AppAuthentication bibliotheek uw referenties voor ontwikkelaars om uit te voeren in uw lokale ontwikkelomgeving. Wanneer de oplossing is geïmplementeerd in Azure, gebruikt de bibliotheek een beheerde identiteit om over te schakelen naar een OAuth 2.0-clientreferentietoestemmingsstroom. Deze aanpak betekent dat u dezelfde code zonder zorgen lokaal en op afstand kunt testen.

Voor lokale ontwikkeling AzureServiceTokenProvider worden tokens opgehaald met behulp van Visual Studio, Azure-opdrachtregelinterface (CLI) of Azure AD Integrated Authentication. Elke optie wordt opeenvolgend geprobeerd en de bibliotheek gebruikt de eerste optie die slaagt. Als geen optie werkt, wordt er een AzureServiceTokenProviderException uitzondering gegenereerd met gedetailleerde informatie.

Verifiëren met Visual Studio

Verifiëren met behulp van Visual Studio:

Meld u aan bij Visual Studio en gebruik Extra>Opties om Opties te openen.
Selecteer Azure Service Authentication, kies een account voor lokale ontwikkeling en selecteer OK.

Als u problemen ondervindt met het gebruik van Visual Studio, zoals fouten die betrekking hebben op het tokenproviderbestand, bekijkt u de voorgaande stappen zorgvuldig.

Mogelijk moet u uw ontwikkelaarstoken opnieuw verifiëren. Selecteer hiervoor Extra>opties en selecteer vervolgens Azure Service Authentication. Zoek naar de koppeling Opnieuw verifiëren onder het geselecteerde account. Selecteer deze om te verifiëren.

Verifiëren met Azure CLI

Als u Azure CLI wilt gebruiken voor lokale ontwikkeling, moet u versie Azure CLI v2.0.12 of hoger hebben.

Azure CLI gebruiken:

Zoek naar Azure CLI op de Windows-taakbalk om de Microsoft Azure-opdrachtprompt te openen.
Meld u aan bij de Azure Portal: az login om u aan te melden bij Azure.
Controleer de toegang door az account get-access-token --resource https://vault.azure.netin te voeren. Als er een foutbericht wordt weergegeven, controleert u of de juiste versie van Azure CLI correct is geïnstalleerd.

Als Azure CLI niet is geïnstalleerd in de standaardmap, ontvangt u mogelijk een foutrapportage waarin AzureServiceTokenProvider het pad voor Azure CLI niet kan worden gevonden. Gebruik de omgevingsvariabele AzureCLIPath om de Azure CLI-installatiemap te definiëren. AzureServiceTokenProvider voegt indien nodig de map toe die is opgegeven in de omgevingsvariabele AzureCLIPath aan de omgevingsvariabele Path .
Als u bent aangemeld bij Azure CLI met meerdere accounts of als uw account toegang heeft tot meerdere abonnementen, moet u het abonnement opgeven dat u wilt gebruiken. Voer de opdracht az account set --subscription in.

Met deze opdracht wordt alleen uitvoer gegenereerd bij een fout. Voer de opdracht az account listin om de huidige accountinstellingen te controleren.

Verifiëren met Azure AD-verificatie

Als u Azure AD-verificatie wilt gebruiken, controleert u of:

Uw on-premises Active Directory wordt gesynchroniseerd met Azure AD. Zie Wat is hybride identiteit met Azure Active Directory? voor meer informatie.
Uw code wordt uitgevoerd op een computer die lid is van een domein.

Verificatie bij aangepaste services

Wanneer een service Azure-services aanroept, werken de vorige stappen omdat Azure-services toegang verlenen aan zowel gebruikers als toepassingen.

Wanneer u een service maakt die een aangepaste service aanroept, gebruikt u Azure AD clientreferenties voor verificatie van lokale ontwikkeling. Er zijn twee opties:

Gebruik een service-principal om u aan te melden bij Azure:
1. Een service-principal maken. Zie Een Azure-service-principal maken met Azure CLI voor meer informatie.
2. Gebruik Azure CLI om u aan te melden met de volgende opdracht:
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  Omdat de service-principal mogelijk geen toegang heeft tot een abonnement, gebruikt u het --allow-no-subscriptions argument .
Gebruik omgevingsvariabelen om details van de service-principal op te geven. Zie De toepassing uitvoeren met behulp van een service-principal voor meer informatie.

Nadat u zich hebt aangemeld bij Azure, AzureServiceTokenProvider gebruikt u de service-principal om een token op te halen voor lokale ontwikkeling.

Deze benadering is alleen van toepassing op lokale ontwikkeling. Wanneer uw oplossing is geïmplementeerd in Azure, schakelt de bibliotheek over naar een beheerde identiteit voor verificatie.

De toepassing uitvoeren met behulp van een beheerde identiteit of door de gebruiker toegewezen identiteit

Wanneer u uw code uitvoert op een Azure App Service of een Azure-VM waarvoor een beheerde identiteit is ingeschakeld, maakt de bibliotheek automatisch gebruik van de beheerde identiteit. Er zijn geen codewijzigingen vereist, maar de beheerde identiteit moet machtigingen hebben voor de resources die deze probeert te openen. Er is bijvoorbeeld toegangsbeleid vereist voor een beheerde identiteit om toegang te krijgen tot geheimen in een sleutelkluis.

U kunt zich ook verifiëren met een door de gebruiker toegewezen identiteit. Zie Over beheerde identiteiten voor Azure-resources voor meer informatie over door de gebruiker toegewezen identiteiten. Als u zich wilt verifiëren met een door de gebruiker toegewezen identiteit, moet u de client-id van de door de gebruiker toegewezen identiteit opgeven in de connection string. De connection string wordt opgegeven in Ondersteuning voor verbindingsreeksen.

De toepassing uitvoeren met behulp van een service-principal

Het kan nodig zijn om een Azure AD clientreferentie te maken om te verifiëren. Deze situatie kan zich voordoen in de volgende voorbeelden:

Uw code wordt uitgevoerd in een lokale ontwikkelomgeving, maar niet onder de identiteit van de ontwikkelaar. Service Fabric gebruikt bijvoorbeeld het NetworkService-account voor lokale ontwikkeling.
Uw code wordt uitgevoerd in een lokale ontwikkelomgeving en u verifieert zich bij een aangepaste service, zodat u uw ontwikkelaarsidentiteit niet kunt gebruiken.
Uw code wordt uitgevoerd op een Azure-rekenresource die nog geen beheerde identiteiten voor Azure-resources ondersteunt, zoals Azure Batch.

Er zijn drie primaire methoden voor het gebruik van een service-principal om uw toepassing uit te voeren. Als u een van deze wilt gebruiken, moet u eerst een service-principal maken. Zie Een Azure-service-principal maken met Azure CLI voor meer informatie.

Een certificaat in het lokale sleutelarchief gebruiken om u aan te melden bij Azure AD

Maak een service-principalcertificaat met behulp van de Azure CLI-opdracht az ad sp create-for-rbac .
```
az ad sp create-for-rbac --create-cert
```
Met deze opdracht maakt u een PEM-bestand (persoonlijke sleutel) dat is opgeslagen in uw basismap. Converteer het PEM-bestand naar een PFX-certificaat met behulp van de opdracht :
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
Stel een omgevingsvariabele met de naam AzureServicesAuthConnectionString in op de volgende waarde:
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
Vervang {AppId}, {TenantId} en {Thumbprint} door waarden die in stap 1 zijn gegenereerd. Vervang {CertificateStore} door LocalMachine' of CurrentUser op basis van uw implementatieplan.
Voer de toepassing uit.

Een gedeelde geheime referentie gebruiken om u aan te melden bij Azure AD

Maak een service-principalcertificaat met een wachtwoord met behulp van de Azure CLI az ad sp create-for-rbac-opdracht met de parameter --sdk-auth.
```
az ad sp create-for-rbac --sdk-auth
```
Stel een omgevingsvariabele met de naam AzureServicesAuthConnectionString in op de volgende waarde:
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
Vervang {AppId}, {TenantId} en {ClientSecret} door waarden die in stap 1 zijn gegenereerd.
Voer de toepassing uit.

Zodra alles correct is ingesteld, zijn er geen verdere codewijzigingen meer nodig. AzureServiceTokenProvidergebruikt de omgevingsvariabele en het certificaat om te verifiëren bij Azure AD.

Een certificaat in Key Vault gebruiken om u aan te melden bij Azure AD

Met deze optie kunt u het clientcertificaat van een service-principal opslaan in Key Vault en gebruiken voor verificatie van service-principals. U kunt deze optie gebruiken voor de volgende scenario's:

Lokale verificatie, waarbij u zich wilt verifiëren met behulp van een expliciete service-principal en de referenties van de service-principal veilig in een sleutelkluis wilt bewaren. Ontwikkelaarsaccount moet toegang hebben tot de sleutelkluis.
Verificatie van Azure waarbij u expliciete referenties wilt gebruiken en de referenties van de service-principal veilig in een sleutelkluis wilt bewaren. U kunt deze optie gebruiken voor een scenario tussen tenants. De beheerde identiteit moet toegang hebben tot de sleutelkluis.

De beheerde identiteit of uw ontwikkelaarsidentiteit moet gemachtigd zijn om het clientcertificaat op te halen uit de Key Vault. De AppAuthentication-bibliotheek gebruikt het opgehaalde certificaat als de clientreferentie van de service-principal.

Een clientcertificaat gebruiken voor verificatie van service-principals:

Maak een service-principalcertificaat en sla dit automatisch op in uw Key Vault. Gebruik de 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
```
De certificaat-id is een URL in de indeling https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

Vervang in deze connection string door {KeyVaultCertificateSecretIdentifier} de certificaat-id:

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

Als uw sleutelkluis bijvoorbeeld myKeyVault heet en u een certificaat met de naam myCert hebt gemaakt, is de certificaat-id:

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

Ondersteuning voor verbindingsreeksen

AzureServiceTokenProvider Standaard worden de volgende verificatiemethoden geprobeerd om een token op te halen:

Een beheerde identiteit voor Azure-resources
Visual Studio-verificatie
Azure CLI-verificatie
Geïntegreerde Windows-verificatie

Als u het proces wilt beheren, gebruikt u een connection string doorgegeven aan de AzureServiceTokenProvider constructor of is opgegeven in de omgevingsvariabele AzureServicesAuthConnectionString. De volgende opties worden ondersteund:

Optie verbindingsreeks	Scenario	Opmerkingen
`RunAs=Developer;DeveloperTool=AzureCli`	Lokale ontwikkeling	`AzureServiceTokenProvider` gebruikt AzureCli om een token op te halen.
`RunAs=Developer;DeveloperTool=VisualStudio`	Lokale ontwikkeling	`AzureServiceTokenProvider` gebruikt Visual Studio om een token op te halen.
`RunAs=CurrentUser`	Lokale ontwikkeling	Niet ondersteund in .NET Core. `AzureServiceTokenProvider`maakt gebruik van Azure AD Geïntegreerde verificatie om een token op te halen.
`RunAs=App`	Beheerde identiteiten voor Azure-resources	`AzureServiceTokenProvider` gebruikt een beheerde identiteit om een token op te halen.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Door de gebruiker toegewezen identiteit voor Azure-resources	`AzureServiceTokenProvider` gebruikt een door de gebruiker toegewezen identiteit om een token op te halen.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	Verificatie van aangepaste services	`KeyVaultCertificateSecretIdentifier` is de geheime id van het certificaat.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	Service-principal	`AzureServiceTokenProvider`gebruikt certificaat om token op te halen uit Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	Service-principal	`AzureServiceTokenProvider`gebruikt certificaat om token op te halen uit Azure AD
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	Service-principal	`AzureServiceTokenProvider`gebruikt geheim om token op te halen uit Azure AD.

Voorbeelden

Raadpleeg de volgende codevoorbeelden om de Microsoft.Azure.Services.AppAuthentication bibliotheek in actie te zien.

Problemen met AppAuthentication oplossen

Veelvoorkomende problemen tijdens lokale ontwikkeling

Azure CLI is niet geïnstalleerd, u bent niet aangemeld of u hebt niet de nieuwste versie

Voer az account get-access-token uit om te zien of Azure CLI een token voor u weergeeft. Als wordt aangegeven dat een dergelijk programma niet is gevonden, installeert u de nieuwste versie van de Azure CLI. U wordt mogelijk gevraagd u aan te melden.

AzureServiceTokenProvider kan het pad voor Azure CLI niet vinden

AzureServiceTokenProvider zoekt naar Azure CLI op de standaardinstallatielocaties. Als De Azure CLI niet kan worden gevonden, stelt u de omgevingsvariabele AzureCLIPath in op de Azure CLI-installatiemap. AzureServiceTokenProvider voegt de omgevingsvariabele toe aan de omgevingsvariabele Pad.

U bent aangemeld bij Azure CLI met behulp van meerdere accounts, hetzelfde account heeft toegang tot abonnementen in meerdere tenants of u krijgt de foutmelding Toegang geweigerd wanneer u probeert aan te roepen tijdens de lokale ontwikkeling

Stel met behulp van Azure CLI het standaardabonnement in op een abonnement met het account dat u wilt gebruiken. Het abonnement moet zich in dezelfde tenant bevinden als de resource waartoe u toegang wilt: az account set --subscription [subscription-id]. Als er geen uitvoer wordt weergegeven, is dit gelukt. Controleer of het juiste account nu de standaardaccount is met az account list.

Veelvoorkomende problemen in omgevingen

Onbevoegde toegang, toegang geweigerd, verboden of soortgelijke fout

De gebruikte principal heeft geen toegang tot de resource waartoe deze toegang probeert te krijgen. Ververleent uw gebruikersaccount of de MSI-inzender van de App Service toegang tot een resource. Welke is afhankelijk van of u het voorbeeld uitvoert op uw lokale computer of in Azure naar uw App Service. Sommige resources, zoals sleutelkluizen, hebben ook hun eigen toegangsbeleid dat u gebruikt om toegang te verlenen tot principals, zoals gebruikers, apps en groepen.

Veelvoorkomende problemen bij implementatie in Azure App Service

Beheerde identiteit is niet ingesteld op de App Service

Controleer de omgevingsvariabelen MSI_ENDPOINT en MSI_SECRET bestaan met behulp van de Kudu-console voor foutopsporing. Als deze omgevingsvariabelen niet bestaan, wordt beheerde identiteit niet ingeschakeld op de App Service.

Veelvoorkomende problemen bij lokaal implementeren met IIS

Kan geen tokens ophalen bij het opsporen van fouten in een app in IIS

AppAuth wordt standaard uitgevoerd in een andere gebruikerscontext in IIS. Daarom heeft het geen toegang om uw ontwikkelaarsidentiteit te gebruiken om toegangstokens op te halen. U kunt IIS configureren voor uitvoering met uw gebruikerscontext door de volgende twee stappen uit te voeren:

Configureer de groep van toepassingen voor de web-app om te worden uitgevoerd als uw huidige gebruikersaccount. Meer informatie vindt u hier
Configureer setProfileEnvironment op True. Meer informatie vindt u hier.
- Ga naar %windir%\System32\inetsrv\config\applicationHost.config
- Zoek naar 'setProfileEnvironment'. Als deze is ingesteld op 'False', wijzigt u deze in 'True'. Als deze niet aanwezig is, voegt u het toe als een kenmerk aan het element processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) en stelt u het in op True.
Meer informatie over beheerde identiteiten voor Azure-resources.
Meer informatie over Azure AD verificatiescenario's.