Alkalmazáshitelesítési ügyfélkódtár a .NET-hez – 1.6.0-s verzió

Cikk
04/03/2023

Megjegyzés

A Microsoft.Azure.Services.AppAuthentication ki lett vonva, és már nem támogatott vagy karbantartott. A helyére a .NET, a Java, a TypeScript és a Python számára elérhető Azure Identity-ügyfélkódtár kerül. A migrálással Azure Identitykapcsolatos információk itt találhatók: AppAuthentication to Azure.Identity Migration Guidance.

Ahhoz, hogy az Azure-szolgáltatásokban szolgáltatásnévvel hitelesíthesse magát, szüksége van egy Azure Active Directory-hitelesítő adatra (Azure AD), egy megosztott titkos kódra vagy egy tanúsítványra.

Az ilyen hitelesítő adatok kezelése nehéz lehet. Csábító, hogy a hitelesítő adatokat egy alkalmazásba csomagolja úgy, hogy a forrás- vagy konfigurációs fájlokba foglalja őket. A Microsoft.Azure.Services.AppAuthentication .NET-kódtár leegyszerűsíti ezt a problémát. A fejlesztő hitelesítő adataival hitelesíti magát a helyi fejlesztés során. Amikor a megoldást később üzembe helyezi az Azure-ban, a kódtár automatikusan átvált az alkalmazás hitelesítő adataira. A fejlesztői hitelesítő adatok használata a helyi fejlesztés során biztonságosabb, mert nem kell Azure AD hitelesítő adatokat létrehoznia, vagy meg kell osztania a hitelesítő adatokat a fejlesztők között.

A Microsoft.Azure.Services.AppAuthentication tár automatikusan kezeli a hitelesítést, így a hitelesítő adatok helyett a megoldásra összpontosíthat. Támogatja a helyi fejlesztést a Microsoft Visual Studióval, az Azure CLI-vel vagy Azure AD integrált hitelesítéssel. Ha felügyelt identitást támogató Azure-erőforrásra van üzembe helyezve, a kódtár automatikusan felügyelt identitásokat használ az Azure-erőforrásokhoz. Nincs szükség kód- vagy konfigurációmódosításra. A kódtár támogatja Azure AD ügyfél hitelesítő adatainak közvetlen használatát is, ha egy felügyelt identitás nem érhető el, vagy ha a fejlesztő biztonsági környezete nem határozható meg a helyi fejlesztés során.

Forráskód | Csomag (nuget) | Az Azure Active Directory dokumentációja

Előfeltételek

Visual Studio 2019 vagy Visual Studio 2017 v15.5.
A Visual Studio apphitelesítési bővítménye, amely a Visual Studio 2017 Update 5 külön bővítményeként érhető el, és a termékkel együtt a 6- és újabb frissítésben található. A 6-os vagy újabb frissítéssel ellenőrizheti az Alkalmazáshitelesítés bővítmény telepítését, ha kiválasztja az Azure Fejlesztési eszközöket a Visual Studio telepítőből.

A kódtár használata

A .NET-alkalmazások esetében a legegyszerűbben a csomagon keresztül Microsoft.Azure.Services.AppAuthentication dolgozhat a felügyelt identitásokkal. Az első lépések a következők:

Válassza az Eszközök>NuGet Package Manager>Manage NuGet Packages for Solution (NuGet-csomagok kezelése megoldáshoz ) lehetőséget, és adjon hozzá hivatkozásokat a Microsoft.Azure.Services.AppAuthentication és a Microsoft.Azure.KeyVault NuGet-csomagokra a projektben.

Az AzureServiceTokenProvider használatával leegyszerűsítheti a hozzáférési jogkivonatok kérését az Azure-ügyfelek számára, az alábbi példákhoz hasonlóan:

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

A szálbiztos AzureServiceTokenProvider osztály gyorsítótárazza a tokent a memóriában, és közvetlenül a lejárat előtt lekéri Azure AD. Ez azt jelenti, hogy a metódus meghívása előtt soha nem kell ellenőriznie a jogkivonat lejáratát GetAccessTokenAsync .

A GetAccessTokenAsync metódushoz erőforrás-azonosító szükséges. A Microsoft Azure-szolgáltatásokról további információt a Mi az Azure-erőforrások felügyelt identitásai? című témakörben talál.

Helyi fejlesztési hitelesítés

A helyi fejlesztéshez két elsődleges hitelesítési forgatókönyv létezik: az Azure-szolgáltatások hitelesítése és az egyéni szolgáltatások hitelesítése.

Hitelesítés az Azure Servicesbe

A helyi gépek nem támogatják az Azure-erőforrások felügyelt identitását. Ennek eredményeképpen a kódtár a Microsoft.Azure.Services.AppAuthentication fejlesztői hitelesítő adatokat használja a helyi fejlesztési környezetben való futtatáshoz. A megoldás Azure-ban való üzembe helyezésekor a kódtár felügyelt identitással vált egy OAuth 2.0-s ügyfél hitelesítőadat-engedélyezési folyamatra. Ez a megközelítés azt jelenti, hogy ugyanazt a kódot helyileg és távolról is tesztelheti, anélkül, hogy aggódnia kellene.

Helyi fejlesztéshez AzureServiceTokenProvider lekéri a jogkivonatokat a Visual Studio, az Azure parancssori felülete (CLI) vagy Azure AD integrált hitelesítés használatával. Az egyes lehetőségeket egymás után próbálják ki, és a kódtár az első sikeres lehetőséget használja. Ha nincs lehetőség, a rendszer kivételt AzureServiceTokenProviderException jelez részletes információkkal.

Hitelesítés a Visual Studióval

Hitelesítés a Visual Studióval:

Jelentkezzen be a Visual Studióba, és az Eszközök>beállításaival nyissa meg a Beállítások elemet.
Válassza az Azure Service Authentication lehetőséget, válasszon ki egy fiókot a helyi fejlesztéshez, majd válassza az OK gombot.

Ha problémákba ütközik a Visual Studióval, például a jogkivonat-szolgáltató fájllal kapcsolatos hibákba, alaposan tekintse át az előző lépéseket.

Előfordulhat, hogy újra fel kell újítania a fejlesztői jogkivonatot. Ehhez válassza az Eszközök>beállításai, majd az Azure Service Authentication lehetőséget. Keressen egy újrahitelesítendő hivatkozást a kiválasztott fiók alatt. Válassza ki a hitelesítéshez.

Hitelesítés az Azure CLI-vel

Az Azure CLI helyi fejlesztéshez való használatához győződjön meg arról, hogy rendelkezik az Azure CLI 2.0.12-es vagy újabb verziójával.

Az Azure CLI használatához:

Keresse meg az Azure CLI-t a Windows tálcán a Microsoft Azure parancssorának megnyitásához.
Jelentkezzen be a Azure Portal: az login to sign to login to sign to Azure.
Ellenőrizze a hozzáférést az az account get-access-token --resource https://vault.azure.netbeírásával. Ha hibaüzenetet kap, ellenőrizze, hogy az Azure CLI megfelelő verziója megfelelően van-e telepítve.

Ha az Azure CLI nincs telepítve az alapértelmezett könyvtárba, hibaüzenet jelenhet meg, amely AzureServiceTokenProvider nem találja az Azure CLI elérési útját. Az Azure CLI telepítési mappájának meghatározásához használja az AzureCLIPath környezeti változót. AzureServiceTokenProvider Szükség esetén hozzáadja az AzureCLIPath környezeti változóban megadott könyvtárat a Path környezeti változóhoz.
Ha több fiókkal jelentkezett be az Azure CLI-be, vagy a fiókja több előfizetéshez is hozzáfér, meg kell adnia a használni kívánt előfizetést. Adja meg az az account set --subscription parancsot.

Ez a parancs csak hiba esetén hoz létre kimenetet. Az aktuális fiókbeállítások ellenőrzéséhez írja be a parancsot az account list.

Hitelesítés Azure AD hitelesítéssel

A Azure AD hitelesítés használatához ellenőrizze, hogy:

A helyi Active Directory szinkronizálódik a Azure AD. További információ: Mi a hibrid identitás az Azure Active Directoryval?
A kód tartományhoz csatlakoztatott számítógépen fut.

Hitelesítés egyéni szolgáltatásokhoz

Amikor egy szolgáltatás meghívja az Azure-szolgáltatásokat, az előző lépések azért működnek, mert az Azure-szolgáltatások hozzáférést biztosítanak a felhasználókhoz és az alkalmazásokhoz is.

Egyéni szolgáltatást meghívó szolgáltatás létrehozásakor használja Azure AD ügyfél-hitelesítő adatokat a helyi fejlesztési hitelesítéshez. Két lehetőség érhető el:

Szolgáltatásnév használata az Azure-ba való bejelentkezéshez:
1. Hozzon létre egy szolgáltatásnevet. További információ: Azure-szolgáltatásnév létrehozása az Azure CLI-vel.
2. Az Azure CLI használatával jelentkezzen be a következő paranccsal:
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  Mivel előfordulhat, hogy a szolgáltatásnév nem rendelkezik hozzáféréssel egy előfizetéshez, használja az --allow-no-subscriptions argumentumot.
Környezeti változók használatával adja meg a szolgáltatásnév részleteit. További információ: Az alkalmazás futtatása szolgáltatásnévvel.

Miután bejelentkezett az Azure-ba, AzureServiceTokenProvider a szolgáltatásnév használatával lekérhet egy jogkivonatot a helyi fejlesztéshez.

Ez a megközelítés csak a helyi fejlesztésre vonatkozik. Amikor a megoldás üzembe van helyezve az Azure-ban, a kódtár átvált egy felügyelt identitásra hitelesítés céljából.

Az alkalmazás futtatása felügyelt identitással vagy felhasználó által hozzárendelt identitással

Ha a kódot egy Azure App Service vagy olyan Azure-beli virtuális gépen futtatja, amelyen engedélyezve van a felügyelt identitás, a kódtár automatikusan a felügyelt identitást használja. Nincs szükség kódmódosításra, de a felügyelt identitásnak engedélyekkel kell rendelkeznie azokhoz az erőforrásokhoz, amelyeket megpróbál elérni. Például hozzáférési szabályzatokra van szükség ahhoz, hogy egy felügyelt identitás hozzáférjen a kulcstartóban lévő titkos kódokhoz.

Másik lehetőségként felhasználó által hozzárendelt identitással is végezhet hitelesítést. A felhasználó által hozzárendelt identitásokkal kapcsolatos további információkért lásd: Az Azure-erőforrások felügyelt identitásai. Ha felhasználó által hozzárendelt identitással szeretne hitelesíteni, meg kell adnia a felhasználó által hozzárendelt identitás ügyfél-azonosítóját a kapcsolati sztring. A kapcsolati sztring a kapcsolati sztring támogatásában van megadva.

Az alkalmazás futtatása szolgáltatásnévvel

Előfordulhat, hogy létre kell hoznia egy Azure AD ügyfél hitelesítő adatait a hitelesítéshez. Ez a helyzet a következő példákban fordulhat elő:

A kód helyi fejlesztési környezetben fut, de nem a fejlesztő identitása alatt. A Service Fabric például a NetworkService-fiókot használja a helyi fejlesztéshez.
A kód helyi fejlesztési környezetben fut, és hitelesítést végezhet egy egyéni szolgáltatásban, így nem használhatja a fejlesztői identitást.
A kód olyan Azure számítási erőforráson fut, amely még nem támogatja az Azure-erőforrások felügyelt identitását, például Azure Batch.

Az alkalmazás futtatásához három elsődleges módszer létezik a szolgáltatásnév használatával. Bármelyik használatához először létre kell hoznia egy szolgáltatásnevet. További információ: Azure-szolgáltatásnév létrehozása az Azure CLI-vel.

Tanúsítvány használata a helyi kulcstárban a Azure AD

Hozzon létre egy egyszerű szolgáltatástanúsítványt az Azure CLI az ad sp create-for-rbac paranccsal.
```
az ad sp create-for-rbac --create-cert
```
Ez a parancs létrehoz egy .pem fájlt (titkos kulcsot), amely a kezdőkönyvtárban van tárolva. Konvertálja a .pem fájlt PFX-tanúsítványsá a következő paranccsal:
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
Állítson be egy AzureServicesAuthConnectionString nevű környezeti változót a következő értékre:
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
Cserélje le a(z) {AppId}, {TenantId} és {Thumbprint} elemet az 1. lépésben létrehozott értékekre. Cserélje le a(z) {CertificateStore} elemet a LocalMachine vagy a CurrentUser értékre az üzembehelyezési terv alapján.
Futtassa az alkalmazást.

Közös titkos hitelesítő adatok használata a Azure AD

Hozzon létre egy egyszerű szolgáltatástanúsítványt jelszóval az Azure CLI az ad sp create-for-rbac paranccsal a --sdk-auth paraméterrel.
```
az ad sp create-for-rbac --sdk-auth
```
Állítson be egy AzureServicesAuthConnectionString nevű környezeti változót a következő értékre:
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
Cserélje le az {AppId}, {TenantId} és {ClientSecret} értéket az 1. lépésben létrehozott értékekre.
Futtassa az alkalmazást.

Ha minden megfelelően van beállítva, nincs szükség további kódmódosításra. AzureServiceTokenProvidera környezeti változót és a tanúsítványt használja a hitelesítéshez a Azure AD.

Tanúsítvány használata a Key Vault-ben a Azure AD

Ezzel a beállítással a szolgáltatásnév ügyféltanúsítványát Key Vault tárolhatja, és szolgáltatásnév-hitelesítéshez használhatja. Ezt a lehetőséget a következő esetekben használhatja:

Helyi hitelesítés, ahol explicit szolgáltatásnévvel szeretne hitelesíteni, és biztonságosan szeretné megőrizni a szolgáltatásnév hitelesítő adatait egy kulcstartóban. A fejlesztői fióknak hozzáféréssel kell rendelkeznie a kulcstartóhoz.
Az Azure-ból történő hitelesítés, ahol explicit hitelesítő adatokat szeretne használni, és biztonságosan szeretné megőrizni a szolgáltatásnév hitelesítő adatait egy kulcstartóban. Ezt a lehetőséget bérlők közötti forgatókönyvekhez is használhatja. A felügyelt identitásnak hozzáféréssel kell rendelkeznie a Key Vaulthoz.

A felügyelt identitásnak vagy a fejlesztői identitásnak engedéllyel kell rendelkeznie ahhoz, hogy lekérje az ügyféltanúsítványt a Key Vault. Az AppAuthentication kódtár a lekért tanúsítványt használja a szolgáltatásnév ügyfél-hitelesítő adataiként.

Ügyféltanúsítvány használata egyszerű szolgáltatáshitelesítéshez:

Hozzon létre egy egyszerű szolgáltatástanúsítványt, és automatikusan tárolja azt a Key Vault. Használja az Azure CLI az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment parancsot:
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
A tanúsítványazonosító egy URL-cím lesz a formátumban https://<keyvaultname>.vault.azure.net/secrets/<certificatename>
Cserélje le {KeyVaultCertificateSecretIdentifier} a kapcsolati sztring a tanúsítványazonosítóra:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
Ha például a kulcstartó neve myKeyVault , és létrehozott egy myCert nevű tanúsítványt, a tanúsítványazonosító a következő:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

Kapcsolati sztring támogatása

Alapértelmezés szerint AzureServiceTokenProvider a következő hitelesítési módszereket próbálja meg lekérni egy jogkivonathoz:

Felügyelt identitás azure-erőforrásokhoz
Visual Studio-hitelesítés
Azure CLI-hitelesítés
Integrált Windows-hitelesítés

A folyamat szabályozásához használja a konstruktornak átadott vagy az AzureServiceTokenProviderAzureServicesAuthConnectionString környezeti változóban megadott kapcsolati sztring. A következő lehetőségek támogatottak:

Kapcsolati sztring beállítás	Eset	Megjegyzések
`RunAs=Developer;DeveloperTool=AzureCli`	Helyi fejlesztés	`AzureServiceTokenProvider` az AzureCli-t használja a jogkivonat lekéréséhez.
`RunAs=Developer;DeveloperTool=VisualStudio`	Helyi fejlesztés	`AzureServiceTokenProvider` a Visual Studiót használja a jogkivonat lekéréséhez.
`RunAs=CurrentUser`	Helyi fejlesztés	A .NET Core nem támogatott. `AzureServiceTokenProvider`Azure AD integrált hitelesítést használ a jogkivonat lekéréséhez.
`RunAs=App`	Azure-erőforrások felügyelt identitásai	`AzureServiceTokenProvider` egy felügyelt identitást használ a jogkivonat lekéréséhez.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Felhasználó által hozzárendelt identitás azure-erőforrásokhoz	`AzureServiceTokenProvider` felhasználó által hozzárendelt identitást használ a jogkivonat lekéréséhez.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	Egyéni szolgáltatások hitelesítése	`KeyVaultCertificateSecretIdentifier` a tanúsítvány titkos azonosítója.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	Szolgáltatásnév	`AzureServiceTokenProvider`tanúsítványt használ a jogkivonat lekéréséhez Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	Szolgáltatásnév	`AzureServiceTokenProvider`tanúsítványt használ a jogkivonat lekéréséhez Azure AD
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	Szolgáltatásnév	`AzureServiceTokenProvider`a titkos kód használatával lekéri a tokent Azure AD.

Példák

A kódtár működés közbeni Microsoft.Azure.Services.AppAuthentication megtekintéséhez tekintse meg az alábbi kódmintákat.

Az AppAuthentication hibaelhárítása

A helyi fejlesztés során felmerülő gyakori problémák

Az Azure CLI nincs telepítve, nincs bejelentkezve, vagy nem a legújabb verzióval rendelkezik

Futtassa az az account get-access-token parancsot annak megtekintéséhez, hogy az Azure CLI megjeleníti-e Önnek a jogkivonatot. Ha azt mondja, hogy nem található ilyen program, telepítse az Azure CLI legújabb verzióját. Előfordulhat, hogy a rendszer arra kéri, hogy jelentkezzen be.

Az AzureServiceTokenProvider nem találja az Azure CLI elérési útját

Az AzureServiceTokenProvider az alapértelmezett telepítési helyen keresi az Azure CLI-t. Ha nem találja az Azure CLI-t, állítsa az AzureCLIPath környezeti változót az Azure CLI telepítési mappájába. Az AzureServiceTokenProvider hozzáadja a környezeti változót a Path környezeti változóhoz.

A rendszer több fiókkal jelentkezik be az Azure CLI-be, ugyanaz a fiók több bérlő előfizetéseihez rendelkezik hozzáféréssel, vagy hozzáférés megtagadva hibaüzenet jelenik meg, amikor hívásokat próbál kezdeményezni a helyi fejlesztés során

Az Azure CLI használatával állítsa az alapértelmezett előfizetést olyanra, amely rendelkezik a használni kívánt fiókkal. Az előfizetésnek ugyanabban a bérlőben kell lennie, mint a elérni kívánt erőforrásnak: az account set --subscription [subscription-id]. Ha nem látható kimenet, sikeres volt. Ellenőrizze, hogy a megfelelő fiók lett-e az alapértelmezett az az account list használatával.

Gyakori problémák a különböző környezetekben

Jogosulatlan hozzáférés, hozzáférés megtagadva, tiltott vagy hasonló hiba

A résztvevőnek nincs hozzáférése ahhoz az erőforráshoz, amelyet megpróbál elérni. Adjon hozzáférést a felhasználói fiókjához vagy a App Service MSI-közreműködőjéhez egy erőforráshoz. Attól függ, hogy a mintát a helyi számítógépen futtatja-e, vagy az Azure-ban helyezi üzembe a App Service. Egyes erőforrások, például a kulcstartók, saját hozzáférési szabályzatokkal is rendelkeznek, amelyek hozzáférést biztosítanak a rendszerbiztonsági tagoknak, például a felhasználóknak, az alkalmazásoknak és a csoportoknak.

A Azure App Service üzembe helyezésekor felmerülő gyakori problémák

A felügyelt identitás nincs beállítva a App Service

Ellenőrizze a kudu hibakeresési konzollal MSI_ENDPOINT és MSI_SECRET környezeti változókat. Ha ezek a környezeti változók nem léteznek, a felügyelt identitás nincs engedélyezve a App Service.

Az IIS-ben helyileg üzembe helyezett gyakori problémák

Nem sikerült lekérni a jogkivonatokat az alkalmazás IIS-ben történő hibakeresésekor

Alapértelmezés szerint az AppAuth egy másik felhasználói környezetben fut az IIS-ben. Ezért nem rendelkezik hozzáféréssel a fejlesztői identitás használatához a hozzáférési jogkivonatok lekéréséhez. Az IIS a következő két lépésben konfigurálható úgy, hogy a felhasználói környezettel fusson:

Konfigurálja a webalkalmazás alkalmazáskészletét úgy, hogy az aktuális felhasználói fiókként fusson. További információt itt talál
Konfigurálja a "setProfileEnvironment" beállítást "Igaz" értékre. További információt itt talál.
- Ugrás a következőre: %windir%\System32\inetsrv\config\applicationHost.config
- Keressen rá a "setProfileEnvironment" kifejezésre. Ha "Hamis" értékre van állítva, módosítsa "Igaz" értékre. Ha nincs jelen, adja hozzá attribútumként a processModel elemhez (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment), és állítsa "True" értékre.
További információ az Azure-erőforrások felügyelt identitásairól.
További információ a Azure AD hitelesítési forgatókönyvekről.