.NET için Uygulama Kimlik Doğrulaması istemci kitaplığı - sürüm 1.6.0

Not

Microsoft.Azure.Services.AppAuthentication kullanımdan kaldırılmıştır ve artık desteklenmediğinden veya bakımı yapılmamaktadır. .NET, Java, TypeScript ve Python için kullanılabilen Azure Identity istemci kitaplığıyla değiştirilir. 'a Azure Identitygeçiş yapma hakkında bilgi burada bulunabilir: AppAuthentication to Azure.Identity Migration Guidance.

Hizmet sorumlusuyla Azure hizmetlerinde kimlik doğrulaması yapmak için paylaşılan gizli dizi veya sertifika gibi bir Azure Active Directory (Azure AD) kimlik bilgilerine sahip olmanız gerekir.

Bu tür kimlik bilgilerini yönetmek zor olabilir. Kimlik bilgilerini kaynak veya yapılandırma dosyalarına ekleyerek bir uygulamada paketlemek cazip bir yöntemdir. Microsoft.Azure.Services.AppAuthentication.NET kitaplığı için bu sorunu basitleştirir. Yerel geliştirme sırasında kimlik doğrulaması yapmak için geliştiricinin kimlik bilgilerini kullanır. Çözüm daha sonra Azure'a dağıtıldığında kitaplık otomatik olarak uygulama kimlik bilgilerine geçer. Yerel geliştirme sırasında geliştirici kimlik bilgilerini kullanmak daha güvenlidir çünkü Azure AD kimlik bilgileri oluşturmanız veya geliştiriciler arasında kimlik bilgilerini paylaşmanız gerekmez.

Kitaplık Microsoft.Azure.Services.AppAuthentication , kimlik doğrulamasını otomatik olarak yönetir ve böylece kimlik bilgileriniz yerine çözümünüz üzerinde odaklanmanıza olanak tanır. Microsoft Visual Studio, Azure CLI veya Azure AD Tümleşik Kimlik Doğrulaması ile yerel geliştirmeyi destekler. Yönetilen kimliği destekleyen bir Azure kaynağına dağıtıldığında kitaplık, Azure kaynakları için yönetilen kimlikleri otomatik olarak kullanır. Kod veya yapılandırma değişikliği gerekmez. Kitaplık, yönetilen kimlik kullanılamadığında veya yerel geliştirme sırasında geliştiricinin güvenlik bağlamı belirlenemiyorsa Azure AD istemci kimlik bilgilerinin doğrudan kullanımını da destekler.

Kaynak kodu | Paket (nuget) | Azure Active Directory belgeleri

Önkoşullar

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

• Visual Studio 2017 Güncelleştirme 5 için ayrı bir uzantı olarak kullanılabilen ve Güncelleştirme 6 ve sonraki sürümlerde ürünle birlikte sunulan Visual Studio için Uygulama Kimlik Doğrulaması uzantısı. Güncelleştirme 6 veya üzeri ile, Visual Studio yükleyicisinden Azure Geliştirme araçlarını seçerek Uygulama Kimlik Doğrulaması uzantısının yüklenmesini doğrulayabilirsiniz.

Kitaplığı kullanma

.NET uygulamaları için, yönetilen kimlikle çalışmanın en basit yolu paketi kullanmaktır Microsoft.Azure.Services.AppAuthentication . Şu şekilde başlayabilirsiniz:

1. Projenize Microsoft.Azure.Services.AppAuthentication ve Microsoft.Azure.KeyVault NuGet paketlerine başvurular eklemek için Araçlar>NuGet Paket Yöneticisi>Çözüm için NuGet Paketlerini Yönet'i seçin.

2. Aşağıdaki örnekler gibi Azure istemcileriniz için erişim belirteçleri isteme işlemini basitleştirmek için AzureServiceTokenProvider'ı kullanın:

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

İş parçacığı güvenli AzureServiceTokenProvider sınıfı belirteci bellekte önbelleğe alır ve süre dolmadan hemen önce Azure AD'dan alır. Bu, yöntemi çağırmadan önce belirtecin süre sonunu denetlemeniz gerekmeyecek anlamına GetAccessTokenAsync gelir.

GetAccessTokenAsync yöntemi bir kaynak tanımlayıcısı gerektirir. Microsoft Azure hizmetleri hakkında daha fazla bilgi edinmek için bkz. Azure kaynakları için yönetilen kimlikler nedir?

Yerel geliştirme kimlik doğrulaması

Yerel geliştirme için iki birincil kimlik doğrulama senaryosu vardır: Azure hizmetlerinde kimlik doğrulaması yapma ve özel hizmetlerde kimlik doğrulaması yapma.

Azure Hizmetleri'ne kimlik doğrulaması

Yerel makineler Azure kaynakları için yönetilen kimlikleri desteklemez. Sonuç olarak kitaplık, Microsoft.Azure.Services.AppAuthentication yerel geliştirme ortamınızda çalıştırmak için geliştirici kimlik bilgilerinizi kullanır. Çözüm Azure'a dağıtıldığında kitaplık, OAuth 2.0 istemci kimlik bilgisi verme akışına geçmek için yönetilen bir kimlik kullanır. Bu yaklaşım, aynı kodu yerel olarak ve uzaktan endişelenmeden test etmeniz anlamına gelir.

Yerel geliştirme için Visual Studio, AzureServiceTokenProviderAzure komut satırı arabirimi (CLI) veya Tümleşik Kimlik Doğrulaması Azure AD kullanarak belirteçleri getirir. Her seçenek sırayla denendi ve kitaplık başarılı olan ilk seçeneği kullanır. Hiçbir seçenek işe yaramazsa, ayrıntılı bilgilerle bir AzureServiceTokenProviderException özel durum oluşturulur.

Visual Studio ile kimlik doğrulaması

Visual Studio kullanarak kimlik doğrulaması yapmak için:

1. Visual Studio'da oturum açın ve Seçenekler'i açmak için Araçlar>Seçenekleri'ni kullanın.

2. Azure Hizmet Kimlik Doğrulaması'nı seçin, yerel geliştirme için bir hesap seçin ve Tamam'ı seçin.

Visual Studio'yu kullanırken belirteç sağlayıcısı dosyasını içeren hatalar gibi sorunlarla karşılaşırsanız, önceki adımları dikkatle gözden geçirin.

Geliştirici belirtecinizi yeniden doğrulamanız gerekebilir. Bunu yapmak için Araçlar>Seçenekleri'ni ve ardından Azure Hizmet Kimlik Doğrulaması'nı seçin. Seçili hesabın altında Yeniden kimlik doğrulaması bağlantısı arayın. Kimlik doğrulaması yapmak için seçin.

Azure CLI ile kimlik doğrulaması

Yerel geliştirme için Azure CLI'yi kullanmak için Azure CLI v2.0.12 veya sonraki bir sürümüne sahip olduğunuzdan emin olun.

Azure CLI’yi kullanmak için:

1. Microsoft Azure Komut İstemi'ni açmak için Windows Görev Çubuğu'nda Azure CLI'yi arayın.

2. Azure portal oturum açın: Azure'da oturum açmak için az login.

3. az account get-access-token --resource https://vault.azure.netgirerek erişimi doğrulayın. Hata alırsanız Doğru Azure CLI sürümünün doğru yüklenip yüklenmediğini denetleyin.

   Azure CLI varsayılan dizine yüklenmediyse, Azure CLI yolunu bulamadığını belirten AzureServiceTokenProvider bir hata bildirimi alabilirsiniz. Azure CLI yükleme klasörünü tanımlamak için AzureCLIPath ortam değişkenini kullanın. AzureServiceTokenProvider gerektiğinde AzureCLIPath ortam değişkeninde belirtilen dizini Path ortam değişkenine ekler.

4. Azure CLI'da birden çok hesap kullanarak oturum açtıysanız veya hesabınızın birden çok aboneliğe erişimi varsa, kullanılacak aboneliği belirtmeniz gerekir. az account set --subscription komutunu girin.

Bu komut yalnızca hata durumunda çıkış oluşturur. Geçerli hesap ayarlarını doğrulamak için komutunu az account listgirin.

Azure AD kimlik doğrulaması ile kimlik doğrulaması

Azure AD kimlik doğrulamasını kullanmak için şunları doğrulayın:

• şirket içi Active Directory Azure AD eşitlenir. Daha fazla bilgi için bkz. Azure Active Directory ile karma kimlik nedir?.

• Kodunuz etki alanına katılmış bir bilgisayarda çalışıyor.

Özel hizmetlerde kimlik doğrulaması

Bir hizmet Azure hizmetlerini çağırdığında, Azure hizmetleri hem kullanıcılara hem de uygulamalara erişim sağladığından önceki adımlar çalışır.

Özel hizmeti çağıran bir hizmet oluştururken, yerel geliştirme kimlik doğrulaması için Azure AD istemci kimlik bilgilerini kullanın. İki seçenek vardır:

• Azure'da oturum açmak için hizmet sorumlusu kullanın:

  1. Hizmet sorumlusu oluşturma. Daha fazla bilgi için bkz. Azure CLI ile Azure hizmet sorumlusu oluşturma.

  2. Aşağıdaki komutla oturum açmak için Azure CLI'yi kullanın:

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

     Hizmet sorumlusunun aboneliğe erişimi olmadığından bağımsız değişkenini --allow-no-subscriptions kullanın.

• Hizmet sorumlusu ayrıntılarını belirtmek için ortam değişkenlerini kullanın. Daha fazla bilgi için bkz. Hizmet sorumlusu kullanarak uygulamayı çalıştırma.

Azure'da oturum açtıktan sonra, AzureServiceTokenProvider yerel geliştirme için bir belirteç almak için hizmet sorumlusunu kullanır.

Bu yaklaşım yalnızca yerel geliştirme için geçerlidir. Çözümünüz Azure'a dağıtıldığında kitaplık, kimlik doğrulaması için yönetilen kimliğe geçer.

Yönetilen kimlik veya kullanıcı tarafından atanan kimlik kullanarak uygulamayı çalıştırma

Kodunuzu bir Azure App Service veya yönetilen kimliği etkinleştirilmiş bir Azure VM'sinde çalıştırdığınızda, kitaplık otomatik olarak yönetilen kimliği kullanır. Kod değişikliği gerekmez, ancak yönetilen kimliğin erişmeye çalışacağı kaynaklar için izinleri olmalıdır. Örneğin, yönetilen kimliğin bir anahtar kasasındaki gizli dizilere erişmesi için erişim ilkeleri gereklidir.

Alternatif olarak, kullanıcı tarafından atanan bir kimlikle kimlik doğrulaması da alabilirsiniz. Kullanıcı tarafından atanan kimlikler hakkında daha fazla bilgi için bkz. Azure kaynakları için Yönetilen Kimlikler Hakkında. Kullanıcı tarafından atanan kimlikle kimlik doğrulaması yapmak için bağlantı dizesinde kullanıcı tarafından atanan kimliğin İstemci Kimliğini belirtmeniz gerekir. Bağlantı dizesi Bağlantı Dizesi Desteği'nde belirtilir.

Hizmet Sorumlusu kullanarak uygulamayı çalıştırma

Kimlik doğrulaması için bir Azure AD İstemci kimlik bilgisi oluşturmak gerekebilir. Bu durum aşağıdaki örneklerde oluşabilir:

• Kodunuz yerel bir geliştirme ortamında çalışır ancak geliştiricinin kimliği altında çalışmaz. Örneğin Service Fabric, yerel geliştirme için NetworkService hesabını kullanır.

• Kodunuz yerel bir geliştirme ortamında çalışır ve özel bir hizmette kimlik doğrulaması yaptığınızdan geliştirici kimliğinizi kullanamazsınız.

• Kodunuz, Azure Batch gibi Azure kaynakları için yönetilen kimlikleri henüz desteklemeyen bir Azure işlem kaynağında çalışıyor.

Uygulamanızı çalıştırmak için Hizmet Sorumlusu kullanmanın üç birincil yöntemi vardır. Bunlardan herhangi birini kullanmak için önce bir hizmet sorumlusu oluşturmanız gerekir. Daha fazla bilgi için bkz. Azure CLI ile Azure hizmet sorumlusu oluşturma.

Azure AD oturum açmak için yerel anahtar deposunda sertifika kullanma

1. Azure CLI az ad sp create-for-rbac komutunu kullanarak bir hizmet sorumlusu sertifikası oluşturun.

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

   Bu komut, giriş dizininizde depolanan bir .pem dosyası (özel anahtar) oluşturur. komutunu kullanarak .pem dosyasını PFX sertifikasına dönüştürün:

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

2. AzureServicesAuthConnectionString adlı bir ortam değişkenini aşağıdaki değere ayarlayın:

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

   {AppId}, {TenantId} ve {Thumbprint} değerlerini 1. Adımda oluşturulan değerlerle değiştirin. Dağıtım planınıza göre {CertificateStore} öğesini LocalMachine' veya CurrentUser ile değiştirin.

3. Uygulamayı çalıştırın.

Azure AD oturum açmak için paylaşılan gizli kimlik bilgilerini kullanma

1. --sdk-auth parametresiyle Azure CLI az ad sp create-for-rbac komutunu kullanarak parolayla bir hizmet sorumlusu sertifikası oluşturun.

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

2. AzureServicesAuthConnectionString adlı bir ortam değişkenini aşağıdaki değere ayarlayın:

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

   {AppId}, {TenantId} ve {ClientSecret} değerlerini 1. Adımda oluşturulan değerlerle değiştirin.

3. Uygulamayı çalıştırın.

Her şey doğru şekilde ayarlandıktan sonra başka kod değişikliği gerekmez. AzureServiceTokenProviderAzure AD kimlik doğrulaması yapmak için ortam değişkenini ve sertifikayı kullanır.

Azure AD oturum açmak için Key Vault'da sertifika kullanma

Bu seçenek, bir hizmet sorumlusuna ait istemci sertifikasını Key Vault depolamanıza ve hizmet sorumlusu kimlik doğrulaması için kullanmanıza olanak tanır. Bu seçeneği aşağıdaki senaryolar için kullanabilirsiniz:

• Açık bir hizmet sorumlusu kullanarak kimlik doğrulaması yapmak ve hizmet sorumlusu kimlik bilgilerini bir anahtar kasasında güvenli bir şekilde tutmak istediğiniz yerel kimlik doğrulaması. Geliştirici hesabının anahtar kasasına erişimi olmalıdır.

• Açık kimlik bilgilerini kullanmak ve hizmet sorumlusu kimlik bilgilerini güvenli bir şekilde bir anahtar kasasında tutmak istediğiniz Azure kimlik doğrulaması. Kiracılar arası bir senaryo için bu seçeneği kullanabilirsiniz. Yönetilen kimliğin anahtar kasasına erişimi olmalıdır.

Yönetilen kimliğin veya geliştirici kimliğinizin Key Vault istemci sertifikasını alma iznine sahip olması gerekir. AppAuthentication kitaplığı, hizmet sorumlusunun istemci kimlik bilgisi olarak alınan sertifikayı kullanır.

Hizmet sorumlusu kimlik doğrulaması için istemci sertifikası kullanmak için:

1. Bir hizmet sorumlusu sertifikası oluşturun ve otomatik olarak Key Vault depolayın. Azure CLI az ad sp create-for-rbac --keyvault keyvaultname <--cert <certificatename>> --create-cert --skip-assignment komutunu kullanın:

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

   Sertifika tanımlayıcısı biçiminde bir URL olacaktır https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

2. Bu bağlantı dizesindeki değerini sertifika tanımlayıcısıyla değiştirin {KeyVaultCertificateSecretIdentifier} :

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

   Örneğin, anahtar kasanız myKeyVault olarak adlandırıldıysa ve myCert adlı bir sertifika oluşturduysanız, sertifika tanımlayıcısı şu şekilde olur:

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

Bağlantı Dizesi Desteği

Varsayılan olarak, AzureServiceTokenProvider belirteç almak için aşağıdaki kimlik doğrulama yöntemlerini dener:

• Azure kaynakları için yönetilen kimlik
• Visual Studio kimlik doğrulaması
• Azure CLI kimlik doğrulaması
• Tümleşik Windows kimlik doğrulaması

İşlemi denetlemek için oluşturucuya AzureServiceTokenProvider geçirilen veya AzureServicesAuthConnectionString ortam değişkeninde belirtilen bir bağlantı dizesi kullanın. Aşağıdaki seçenekler desteklenir:

Bağlantı dizesi seçeneği	Senaryo	Yorumlar
RunAs=Developer;DeveloperTool=AzureCli	Yerel geliştirme	AzureServiceTokenProvider belirteci almak için AzureCli kullanır.
RunAs=Developer;DeveloperTool=VisualStudio	Yerel geliştirme	AzureServiceTokenProvider belirteci almak için Visual Studio kullanır.
RunAs=CurrentUser	Yerel geliştirme	.NET Core'da desteklenmez. AzureServiceTokenProviderbelirteci almak için Azure AD Tümleşik Kimlik Doğrulaması kullanır.
RunAs=App	Azure kaynakları için yönetilen kimlikler	AzureServiceTokenProvider belirteç almak için yönetilen kimlik kullanır.
RunAs=App;AppId={ClientId of user-assigned identity}	Azure kaynakları için kullanıcı tarafından atanan kimlik	AzureServiceTokenProvider belirteci almak için kullanıcı tarafından atanan bir kimlik kullanır.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}	Özel hizmetler kimlik doğrulaması	KeyVaultCertificateSecretIdentifier sertifikanın gizli dizi tanımlayıcısıdır.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}	Hizmet sorumlusu	AzureServiceTokenProviderAzure AD'dan belirteç almak için sertifika kullanır.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}	Hizmet sorumlusu	AzureServiceTokenProviderAzure AD'dan belirteç almak için sertifika kullanır
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}	Hizmet sorumlusu	AzureServiceTokenProviderAzure AD belirteci almak için gizli dizi kullanır.

Örnekler

Kitaplığın Microsoft.Azure.Services.AppAuthentication çalıştığını görmek için aşağıdaki kod örneklerine bakın.

• Çalışma zamanında Azure Key Vault'dan gizli dizi almak için yönetilen kimlik kullanma

• Yönetilen kimliğe sahip bir Azure VM'sinden program aracılığıyla Bir Azure Resource Manager şablonu dağıtın.

• Bir Azure Linux VM'sinden Azure hizmetlerini çağırmak için .NET Core örneğini ve yönetilen kimliği kullanın.

AppAuthentication Sorunlarını Giderme

Yerel geliştirme sırasında sık karşılaşılan sorunlar

Azure CLI yüklü değil, oturum açmadıysanız veya en son sürüme sahip değilsiniz

Azure CLI'nın sizin için bir belirteç gösterip göstermediğini görmek için az account get-access-token komutunu çalıştırın. Böyle bir program bulunamadı yazıyorsa Azure CLI'nın en son sürümünü yükleyin. Oturum açmanız istenebilir.

AzureServiceTokenProvider, Azure CLI yolunu bulamıyor

AzureServiceTokenProvider, Azure CLI'yi varsayılan yükleme konumlarında arar. Azure CLI'yı bulamazsa AzureCLIPath ortam değişkenini Azure CLI yükleme klasörüne ayarlayın. AzureServiceTokenProvider ortam değişkenini Yol ortam değişkenine ekler.

Azure CLI'da birden çok hesap kullanarak oturum açtınız, aynı hesabın birden çok kiracıdaki aboneliklere erişimi var veya yerel geliştirme sırasında arama yapmaya çalışırken Erişim Reddedildi hatası alıyorsunuz

Azure CLI'yı kullanarak, varsayılan aboneliği kullanmak istediğiniz hesabı içeren bir abonelik olarak ayarlayın. Abonelik, erişmek istediğiniz kaynakla aynı kiracıda olmalıdır: az account set --subscription [subscription-id]. Hiçbir çıkış görülmezse başarılı olur. Az account list komutunu kullanarak doğru hesabın artık varsayılan hesap olduğunu doğrulayın.

Ortamlar genelinde sık karşılaşılan sorunlar

Yetkisiz erişim, erişim reddedildi, yasak veya benzer bir hata

Kullanılan sorumlunun erişmeye çalıştığı kaynağa erişimi yok. Bir kaynağa kullanıcı hesabınıza veya App Service MSI "Katkıda Bulunanı" erişimi verin. Hangisi örneği yerel bilgisayarınızda çalıştırıp çalıştırmadığınıza veya Azure'da App Service dağıtıp dağıtmadığınıza bağlıdır. Anahtar kasaları gibi bazı kaynakların, kullanıcılar, uygulamalar ve gruplar gibi sorumlulara erişim izni vermek için kullandığınız kendi erişim ilkeleri de vardır.

Azure App Service dağıtılırken sık karşılaşılan sorunlar

Yönetilen kimlik App Service

Kudu hata ayıklama konsolunu kullanarak MSI_ENDPOINT ve MSI_SECRET ortam değişkenlerini denetleyin. Bu ortam değişkenleri yoksa, yönetilen kimlik App Service etkinleştirilmez.

IIS ile yerel olarak dağıtılırken sık karşılaşılan sorunlar

IIS'de uygulamada hata ayıklarken belirteçler alınamıyor

Varsayılan olarak, AppAuth IIS'de farklı bir kullanıcı bağlamında çalışır. Bu nedenle, erişim belirteçlerini almak için geliştirici kimliğinizi kullanma erişimi yoktur. IIS'yi aşağıdaki iki adımla kullanıcı bağlamınızla çalışacak şekilde yapılandırabilirsiniz:

• Web uygulamasının geçerli kullanıcı hesabınız olarak çalışması için Uygulama Havuzunu yapılandırın. Burada daha fazla bilgi bulabilirsiniz

• "setProfileEnvironment" öğesini "True" olarak yapılandırın. Burada daha fazla bilgi bulabilirsiniz.

  • %windir%\System32\inetsrv\config\applicationHost.config konumuna gidin
  • "setProfileEnvironment" için arama yapın. "Yanlış" olarak ayarlandıysa, "True" olarak değiştirin. Yoksa, processModel öğesine (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) özniteliği olarak ekleyin ve bunu "True" olarak ayarlayın.

• Azure kaynakları için yönetilen kimlikler hakkında daha fazla bilgi edinin.

• Azure AD kimlik doğrulama senaryoları hakkında daha fazla bilgi edinin.