Hızlı Başlangıç: Microsoft kimlik platformu tarafından korunan bir web API'sini çağırma

Şunlar için geçerlidir: İş gücü kiracılarıDış kiracılar (daha fazla bilgi edinin)

Bu hızlı başlangıçta, Microsoft kimlik platformunu kullanarak bir ASP.NET web API'sini nasıl koruyacağınızı göstermek için örnek bir web uygulaması kullanacaksınız. Örnek, kimlik doğrulaması ve yetkilendirmeyi işlemek için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanır.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
• Yeni bir uygulamayı Microsoft Entra yönetim merkezine kaydedin ve uygulamaya Genel Bakış sayfasından tanımlayıcılarını kaydedin. Daha fazla bilgi için bkz. Bir uygulama kaydetme.
  • Adı: NewWebAPI1
  • Desteklenen hesap türleri: Yalnızca bu kuruluş dizinindeki hesaplar (Tek kiracı)

ASP.NET

• Visual Studio 2022. Ücretsiz Visual Studioindirin.

ASP.NET Core

• Visual Studio Code

API'yi kullanıma sunma

API kaydedildikten sonra, API'nin istemci uygulamalarına sunduğu kapsamları tanımlayarak api'nin iznini yapılandırabilirsiniz. İstemci uygulamaları, korumalı web API'sine istekleriyle birlikte bir erişim belirteci geçirerek işlemleri gerçekleştirmek için izin istemektedir. Web API'si daha sonra istenen işlemi yalnızca aldığı erişim belirteci gerekli kapsamları içeriyorsa gerçekleştirir.

ASP.NET

1. Yönet'ialtında Api'yi kullanıma sunma>Kapsam ekleöğesini seçin. api://{clientId}devam et'i seçerek önerilen Uygulama Kimliği URI'sini () kabul edin ve ardından aşağıdaki bilgileri girin:

   1. Kapsam adıiçin access_as_usergirin.
   2. Kim onaylayabilir? için Yöneticiler ve kullanıcılar seçeneğinin belirlendiğinden emin olun.
   3. Yönetici onayı görünen adı kutusuna Access TodoListService as a user girin.
   4. Yönetici onayı açıklaması kutusuna yazınAccesses the TodoListService web API as a user.
   5. Kullanıcı onayı görünen adı kutusuna Access TodoListService as a user yazın.
   6. Kullanıcı onayı açıklaması kutusuna girinAccesses the TodoListService web API as a user.
   7. Durumiçin etkintutunuz.

2. Kapsam ekle'yi seçin.

ASP.NET Core

Temsilci izinleri (kapsamlar) ekleme

İstemci uygulamalarının kullanıcı için erişim belirtecini başarıyla alabilmesi için api'nin Temsilci İzinolarak da adlandırılan en az bir kapsam yayımlaması gerekir. Bir kapsam yayınlamak için şu adımları izleyin:

1. Uygulama kayıtları sayfasında, oluşturduğunuz API uygulamasını (ciam-ToDoList-api) seçerek Genel Bakış sayfasını açın.

2. Yönetaltında, Bir API'yi Kullanıma Sunmaseçin.

3. Sayfanın üst kısmında, Uygulama Kimliği URI'siyanındaki Ekle bağlantısını seçerek bu uygulama için benzersiz bir URI oluşturun.

4. api://{clientId}gibi önerilen Uygulama Kimliği URI'sini kabul edin ve Kaydetöğesini seçin. Web uygulamanız web API'si için bir erişim belirteci istediğinde, API için tanımladığınız her kapsam için ön ek olarak URI'yi ekler.

5. Bu API tarafından tanımlananKapsamlar altında Kapsam ekleöğesini seçin.

6. API'ye okuma erişimi tanımlayan aşağıdaki değerleri girin, ardından değişikliklerinizi kaydetmek için Kapsam ekle seçin:

   Mülkiyet	Değer
   Kapsam adı	YapılacaklarListesi.Oku
   Kim onay verebilir?	Yalnızca Yöneticiler
   Yönetici onayı gösterilen ad	'TodoListApi' kullanarak kullanıcıların ToDo listesini okuma
   Yönetici onayı açıklaması	'TodoListApi'kullanarak uygulamanın kullanıcının ToDo listesini okumasına izin verin.
   Devlet	Etkinleştirildi

7. Kapsam ekle'yi yeniden seçin ve API'ye okuma ve yazma erişim kapsamı tanımlayan aşağıdaki değerleri girin. Değişikliklerinizi kaydetmek için Kapsam ekle seçin:

   Mülkiyet	Değer
   Kapsam adı	ToDoList.ReadWrite
   Kim onay verebilir?	Yalnızca Yöneticiler
   Yönetici onayı gösterilen ad	Kullanıcıların ToDo listelerini 'ToDoListApi' kullanarak okuma ve yazma
   Yönetici onayı açıklaması	'ToDoListApi' kullanarak uygulamanın kullanıcının ToDo listesini okumasına ve yazmasına izin ver
   Devlet	Etkinleştirildi

Web API'sine yönelik izinler yayımlarken en az ayrıcalık ilkesi hakkında daha fazla bilgi edinin.

Uygulama izinleri ekleme (uygulama rolleri)

bir API'nin, istemci uygulamalarının kendileri gibi bir erişim belirteci elde etmesi için uygulamalar için uygulama izni olarak da adlandırılan en az bir uygulama rolü yayımlaması gerekir. Uygulama izinleri, istemci uygulamalarının kullanıcıların oturum açmasına gerek kalmadan kendi kimliklerini başarıyla doğrulayabilmesi için API'lerin yayımlaması gereken izin türüdür. Uygulama izni yayımlamak için şu adımları izleyin:

1. Uygulama kayıtları sayfasında, oluşturduğunuz uygulamayı (ciam-ToDoList-api gibi) seçerek Genel Bakış sayfasını açın.

2. Yönetaltında Uygulama rolleriseçin.

3. Uygulama rolü oluştur'u seçin, ardından aşağıdaki değerleri girin ve ardından Uygula'yı seçerek değişikliklerinizi kaydedin:

   Mülkiyet	Değer
   Ekran adı	ToDoList.Read.All
   İzin verilen üye türleri	Uygulamaları
   Değer	ToDoList.Read.All
   Açıklama	Uygulamanın 'TodoListApi' kullanarak her kullanıcının ToDo listesini okumasına izin ver
   Bu uygulama rolünü etkinleştirmek istiyor musunuz?	İşaretli tutun

4. Uygulama rolü oluştur'u yeniden seçin, ardından ikinci uygulama rolü için aşağıdaki değerleri girin ve ardından Değişikliklerinizi kaydetmek için Uygula'yı seçin:

   Mülkiyet	Değer
   Ekran adı	ToDoList.ReadWrite.All
   İzin verilen üye türleri	Uygulamaları
   Değer	ToDoList.ReadWrite.All
   Açıklama	Uygulamanın 'ToDoListApi' kullanarak her kullanıcının ToDo listesini okumasına ve yazmasına izin ver
   Bu uygulama rolünü etkinleştirmek istiyor musunuz?	İşaretli tutun

Örnek uygulamayı kopyalama veya indirme

Örnek uygulamayı edinmek için GitHub'dan kopyalayabilir veya .zip dosyası olarak indirebilirsiniz.

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• zip dosyası olarak indirin.

Tavsiye

Windows'ta yol uzunluğu sınırlamalarından kaynaklanan hataları önlemek için, arşivi ayıklamanızı veya depoyu sürücünüzün köküne yakın bir dizine kopyalamanızı öneririz.

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• .zip dosyasınıindirin. Dosya adının uzunluğu 260 karakterden az olan bir dosya yoluna ayıklayın.

Örnek uygulamayı yapılandırma

Kod örneğini kayıtlı web API'sine uyacak şekilde yapılandırın.

ASP.NET

1. Çözümü Visual Studio'da açın ve ardından TodoListService projesinin kökü altındaki appsettings.json dosyasını açın.

2. Enter_the_Application_Id_here değerini hem hem de ClientID özelliklerinde Audience portalına kaydettiğiniz uygulamadan İstemci Kimliği (Uygulama Kimliği) değeriyle değiştirin.

Yeni kapsamı app.config dosyasına ekle

Yeni kapsamı TodoListClient app.config dosyasına eklemek için şu adımları izleyin:

1. TodoListClient proje kök klasöründe app.config dosyasını açın.

2. TodoListService projeniz için kaydettiğiniz uygulamadan Uygulama Kimliğini TodoListServiceScope parametresine yapıştırın ve {Enter the Application ID of your TodoListService from the app registration portal} dizesini değiştirin.

Uyarı

Uygulama Kimliği'nin şu biçimi kullandığından emin olun: api://{TodoListService-Application-ID}/access_as_user (burada {TodoListService-Application-ID} TodoListService uygulamanızın Uygulama Kimliğini temsil eden GUID'dir).

Web uygulamasını kaydetme (TodoListClient)

TodoListClient uygulamanızı Microsoft Entra yönetim merkezindeki Uygulama kayıtlarına kaydedin ve ardından Kodu TodoListClient projesinde yapılandırın. İstemci ve sunucu aynı uygulama olarak kabul edilirse, 2. adımda kaydedilen uygulamayı yeniden kullanabilirsiniz. Kullanıcıların kişisel bir Microsoft hesabıyla oturum açmasını istiyorsanız aynı uygulamayı kullanın.

Uygulamayı kaydetme

TodoListClient uygulamasını kaydetmek için şu adımları izleyin:

1. En az bir bulut uygulaması yöneticisi olarak Microsoft Entra yönetim merkezinde oturum açın.

2. Entra ID>Uygulama kayıtları'na gidin ve Yeni kayıt'ı seçin.

3. Yeni kayıtseçin.

4. Uygulama kaydetme sayfası açıldığında, uygulamanızın kayıt bilgilerini girin:

   1. Adı bölümünde, uygulamanın kullanıcılarına görüntülenecek anlamlı bir uygulama adı girin (örneğin, NativeClient-DotNet-TodoListClient).
   2. Desteklenen hesap türleriiçin, herhangi bir kuruluş dizinindeki hesapları seçin.
   3. Uygulamayı kaydetmek için Kaydet'i seçin.

   Uyarı

   TodoListClient proje app.config dosyasında, varsayılan ida:Tenant değeri commonolarak ayarlanır. Olası değerler şunlardır:

   • common: bir iş veya okul hesabı ya da kişisel bir Microsoft hesabı kullanarak oturum açabilirsiniz (önceki bir adımda herhangi bir kuruluş dizininde Hesaplar'ı seçtiğinizden).
   • organizations: İş veya okul hesabı kullanarak oturum açabilirsiniz.
   • consumers: Yalnızca bir Microsoft kişisel hesabı kullanarak oturum açabilirsiniz.

5. Uygulama Genel Bakış sayfasında Kimlik Doğrulaması'ni seçin ve ardından platform eklemek için şu adımları tamamlayın:

   1. Platform yapılandırmalarıaltında Platform ekle düğmesini seçin.
   2. Mobil ve masaüstü uygulamalarıiçin Mobil ve masaüstü uygulamalarıöğesini seçin.
   3. Yönlendirme URI'leriiçin https://login.microsoftonline.com/common/oauth2/nativeclient onay kutusunu seçin.
   4. 'i seçin ve'i yapılandırın.

6. API izinlerini seçin ve izin eklemek için şu adımları tamamlayın:

   1. İzin ekleyin düğmesini seçin.
   2. API'lerim sekmesini seçin.
   3. API'ler listesinde AppModelv2-NativeClient-DotNet-TodoListService API veya web API'sine girdiğiniz adı seçin.
   4. Henüz seçili değilse access_as_user izin onay kutusunu seçin. Gerekirse Arama kutusunu kullanın.
   5. İzin ekle düğmesini seçin.

Projenizi yapılandırma

Uygulama Kimliğini app.config dosyasına ekleyerek TodoListClient projenizi yapılandırın.

1. Uygulama kayıtları portalının Genel Bakış sayfasında, Uygulama (istemci) kimliğinin değerini kopyalayın.

2. TodoListClient proje kök klasöründen app.config dosyasını açın ve uygulama kimliği değerini ida:ClientId parametresine yapıştırın.

ASP.NET Core

1. IDE'nizde, örneği içeren ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI proje klasörünü açın.

2. Aşağıdaki kod parçacığını içeren appsettings.json dosyasını açın:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Aşağıdaki değerleri bulun:

   • ClientId - İstemci olarak da adlandırılan uygulamanın tanımlayıcısı. Tırnak içindeki value metni, daha önce kayıtlı uygulamanın Genel Bakış sayfasından kaydedilen Uygulama (istemci) kimliği ile değiştirin.
   • TenantId - Uygulamanın kaydedildiği kiracının tanımlayıcısı. Daha önce kayıtlı uygulamanın value sayfasından kaydedilmiş olan Dizin (kiracı) kimliği değeriyle tırnak içindeki metnini değiştirin.
   • Instance - Microsoft Kimlik Doğrulama Kitaplığı'nın (MSAL) belirteç isteğinde bulunabileceği dizini belirtir. senaryonuza bağlı olarak değerini aşağıdaki değerlerden biriyle değiştirin Enter_the_Authority_URL_Here :
     • İş gücü kiracıları için örnek olarak kullanın https://login.microsoftonline.com/ .
     • Dış kiracılar için şu biçimde bir yetkili URL'si ekleyin: https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Örnek uygulamayı çalıştırma

ASP.NET

Her iki projenin de başlatılmasını sağlayın. Visual Studio kullanıcıları için;

1. Visual Studio çözümüne sağ tıklayın ve Özellikler'ni seçin

2. Ortak Özellikler'deBaşlangıç Projesi'ni ve ardından Birden çok başlangıç projesi'ni seçin.

3. Her iki proje için eylem olarak Başlangıç'ı seçin

4. TodoListService hizmetinin önce yukarı oku kullanarak listedeki ilk konuma taşıyarak başlatıldığından emin olun.

TodoListClient projenizi çalıştırmak için oturum açın.

1. Projeleri başlatmak için F5 tuşuna basın. Hizmet sayfası ve masaüstü uygulaması açılır.

2. TodoListClient'da, sağ üstteki oturum aç'ı seçin ve ardından uygulamanızı kaydetmek için kullandığınız kimlik bilgileriyle oturum açın veya aynı dizinde bir kullanıcı olarak oturum açın.

   İlk kez oturum açıyorsanız TodoListService web API'sini onaylamanız istenebilir.

   TodoListService web API'sine erişmenize ve Yapılacaklar listesini değiştirmenize yardımcı olmak için, oturum açma işlemi access_as_user kapsamına bir erişim belirteci de ister.

İstemci uygulamanızı önceden yetkilendirme

İstemci uygulamasının web API'nize erişmesi için önceden yetki vererek diğer dizinlerden kullanıcıların web API'nize erişmesine izin vekleyebilirsiniz. Bunu yapmak için istemci uygulamasındaki Uygulama Kimliği'ni web API'niz için önceden doğrulanmış uygulamalar listesine eklersiniz. Önceden yetkilendirilmiş bir istemci ekleyerek, kullanıcıların onay vermek zorunda kalmadan web API'nize erişmesine izin vermiş olacaksınız.

1. Uygulama kayıtları portalında TodoListService uygulamanızın özelliklerini açın.
2. API'yi kullanıma sunma bölümünde, Yetkili istemci uygulamalarıaltında, İstemci uygulaması ekleöğesini seçin.
3. İstemci Kimliği kutusuna TodoListClient uygulamasının Uygulama Kimliğini yapıştırın.
4. Yetkili kapsamlar bölümünde api://<Application ID>/access_as_user web API'sinin kapsamını seçin.
5. Uygulama ekle'yi seçin.

Projenizi çalıştırma

1. Projenizi çalıştırmak için F5 basın. TodoListClient uygulamanız açılır.
2. Sağ üst oturum aç'ı seçin ve ardından live.com veya hotmail.com hesabı ya da iş veya okul hesabı gibi kişisel bir Microsoft hesabı kullanarak oturum açın.

İsteğe bağlı: Oturum açma erişimini belirli kullanıcılarla sınırla

Varsayılan olarak, outlook.com veya live.com hesapları gibi tüm kişisel hesaplar ya da Microsoft Entra Id ile tümleştirilen kuruluşların iş veya okul hesapları belirteç isteyebilir ve web API'nize erişebilir.

TenantId dosyasındaki özelliğini değiştirerek uygulamanızda kimlerin oturum açabileceğini belirtmek için.

ASP.NET Core

1. Uygulamayı başlatmak için web API proje dizininizin kökünden aşağıdaki komutu çalıştırın:

   dotnet run
   

2. Her şey düzgün çalıştıysa terminaliniz aşağıdakine benzer bir çıkış görüntüler:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Bağlantı noktası numarasını https://localhost:{port} URL'sine kaydedin.

3. Uç noktanın korunduğunu doğrulamak için, aşağıdaki cURL komutundaki temel URL'yi önceki adımda aldığınızla eşleşecek şekilde güncelleştirin ve ardından komutunu çalıştırın:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Beklenen yanıt 401 Yetkisiz'dir.

Sonraki adımlar

Microsoft kimlik platformuyla ASP.NET Core web API'sini korumayı öğrenin.

Öğretici: Microsoft kimlik platformu ile ASP.NET Core web API'sini oluşturma ve güvenliğini sağlama