Uykusuzluk ile ASP.NET Core web API'si çağırma

Bu makalede, Uykusuzluk kullanarak korumalı ASP.NET Core web API'sini nasıl çağırabileceğiniz gösterilmektedir. Uykusuzluk, yetkilendirme ve erişim denetimi (kimlik doğrulaması) ilkelerini test etmek için bir web API'sine HTTP istekleri göndermenizi sağlayan bir uygulamadır. Bu makalede, bir web uygulamasını ve bir web API'sini bir kiracıya kaydedersiniz. Web uygulaması, Microsoft kimlik platformu tarafından oluşturulan bir erişim belirtecini almak için kullanılır. Ardından, insomnia kullanarak web API'sine yetkili bir çağrı yapmak için belirteci kullanırsınız.

Bu makalede, Uykusuzluk kullanarak korumalı ASP.NET Core web API'sini nasıl çağırabileceğiniz gösterilmektedir. Uykusuzluk, yetkilendirme ve erişim denetimi (kimlik doğrulaması) ilkelerini test etmek için bir web API'sine HTTP istekleri göndermenizi sağlayan bir uygulamadır. Öğretici: API'nize bir korumalı uç nokta eklediğiniz bölümünden sonra, erişim belirteci oluşturmak için Microsoft Kimlik Platformu'na bir web uygulaması kaydetmeniz gerekir. Ardından, uykusuzluk kullanarak API'ye yetkili bir çağrı yapmak için belirteci kullanırsınız.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.
• Bu Azure hesabının uygulamaları yönetme izinleri olmalıdır. Aşağıdaki Microsoft Entra rollerinden herhangi biri gerekli izinleri içerir:
  • Uygulama Yöneticisi
  • Uygulama Geliştirici
  • Bulut Uygulaması Yöneticisi
• Insomnia'yı indirin ve yükleyin. Uykusuzluğu kullanarak API istekleriniz için bir erişim belirteci alırsınız.
• En düşük .NET 8.0 SDK gereksinimi.

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir hesap oluşturun.
• Bu Azure hesabının uygulamaları yönetme izinleri olmalıdır. Aşağıdaki Microsoft Entra rollerinden herhangi biri gerekli izinleri içerir:
  • Uygulama Yöneticisi
  • Uygulama Geliştirici
  • Bulut Uygulaması Yöneticisi
• Öğretici serisinin tamamlanması:
  • Öğretici: Web API'sini Microsoft kimlik platformuna kaydetme.
  • Öğretici: Kimlik doğrulaması için ASP.NET Core projesi oluşturma ve yapılandırma.
  • Öğretici: API'nize korumalı uç nokta uygulama.
• Insomnia'yı indirin ve yükleyin.

Bir uygulamayı kaydetme

Microsoft kimlik platformu, kimlik ve erişim yönetimi hizmetleri sağlamadan önce uygulamanızın kaydedilmesini gerektirir. Uygulama kaydı, uygulamanın adını ve türünü ve oturum açma hedef kitlesini belirtmenize olanak tanır. Oturum açma hedef kitlesi, belirli bir uygulamada hangi tür kullanıcı hesaplarının oturum açmasına izin verildiğini belirtir.

Web API'sini kaydetme

Web API kaydını oluşturmak için şu adımları izleyin:

1. Microsoft Entra yönetim merkezinde en azından Uygulama Geliştiricisi olarak oturum açın.

2. Birden çok kiracıya erişiminiz varsa, Dizinler + abonelikler menüsünden uygulamayı kaydetmek istediğiniz kiracıya geçmek için üst menüdeki Ayarlar simgesini kullanın.

3. Entra ID>Uygulama kayıtlarına gidin.

4. Yeni kayıt'ı seçin.

5. Uygulama için NewWebAPI1 gibi bir Ad girin.

6. Desteklenen hesap türleri içinYalnızca bu kuruluş dizinindeki Hesaplar'ı seçin. Farklı hesap türleri hakkında bilgi için Yardım et seçeneğini belirleyin.

7. Kayıt Ol'u seçin.

   

8. Kayıt tamamlandığında uygulamanın Genel Bakış bölmesini görebilirsiniz. Sonraki adımlarda kullanılacak Dizin (kiracı) kimliğini ve Uygulama (istemci) kimliğini kaydedin.

   

Not

Desteklenen hesap türleri, Uygulama tarafından desteklenen hesapları değiştirme konusuna başvurarak değiştirilebilir.

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 geçerliyse gerçekleştirir.

1. Yönet'in altında API'yi > kullanıma sunma Kapsam ekle'yi seçin. Kaydet ve devam et'i seçerek önerilen (api://{clientId}) kabul edin. {clientId}, Genel Bakış sayfasından kaydedilen değerdir. Ardından aşağıdaki bilgileri girin:

   1. Kapsam adı olarak girinForecast.Read.
   2. Kim onaylayabilir? için Yöneticiler ve kullanıcılar seçeneğinin belirlendiğinden emin olun.
   3. Yönetici onayı için görünen ad kutusuna Read forecast data girmelisiniz.
   4. Yönetici onayı açıklaması kutusuna yazınAllows the application to read weather forecast data.
   5. Kullanıcı onayı görüntüleme adı kutusuna girinRead forecast data.
   6. Kullanıcı onayı açıklaması kutusuna girinAllows the application to read weather forecast data.
   7. Durum'unEtkin olarak ayarlandığından emin olun.

2. Kapsam ekle'yi seçin. Kapsam doğru girilmişse, API'yi kullanıma sunma bölmesinde görünür.

   

Web uygulamasını kaydetme

Web API'sine sahip olmak yeterli değildir; web API'sine erişmek için erişim belirteci almak için bir web uygulamasına da ihtiyacınız vardır.

Web uygulaması kaydını oluşturmak için şu adımları izleyin:

1. Giriş sayfasına dönmek için Giriş'i seçin. Entra ID>Uygulama kayıtlarına gidin.
2. Yeni kayıt'ı seçin.
3. Uygulama için web-app-calls-web-api gibi bir Ad girin.
4. Desteklenen hesap türleri içinYalnızca bu kuruluş dizinindeki Hesaplar'ı seçin. Farklı hesap türleri hakkında bilgi için Bana yardım et seçeneğini belirleyin.
5. Yeniden Yönlendirme URI'si (isteğe bağlı) altındaWeb'i seçin ve URL metin kutusuna girinhttp://localhost.
6. Kayıt Ol'u seçin.

1. Microsoft Entra yönetim merkezinde en azından Uygulama Geliştiricisi olarak oturum açın.
2. Birden çok kiracıya erişiminiz varsa, Dizinler + abonelikler menüsünden uygulamayı kaydetmek istediğiniz kiracıya geçmek için üst menüdeki Ayarlar simgesini kullanın.
3. Entra ID>Uygulama kayıtlarına gidin.
4. Yeni kayıt'ı seçin.
5. Uygulama için web-app-calls-web-api gibi bir Ad girin.
6. Desteklenen hesap türleri içinYalnızca bu kuruluş dizinindeki Hesaplar'ı seçin. Farklı hesap türleri hakkında bilgi için Bana yardım et seçeneğini belirleyin.
7. Yeniden Yönlendirme URI'si (isteğe bağlı) altındaWeb'i seçin ve URL metin kutusuna girinhttp://localhost.
8. Kayıt Ol'u seçin.

Kayıt tamamlandığında uygulamanın Genel Bakış bölmesini görebilirsiniz. Sonraki adımlarda kullanılacak Dizin (kiracı) kimliğini ve Uygulama (istemci) kimliğini kaydedin.

İstemci gizli dizisi ekleme

İstemci gizli dizisi, uygulamanızın kendisini kimlik doğrulaması için kullanabileceği bir dize değeridir ve bazen uygulama parolası olarak da adlandırılır. Web uygulaması, belirteç istediğinde kimliğini kanıtlamak için istemci gizli dizisini kullanır.

İstemci gizli dizisini yapılandırmak için şu adımları izleyin:

1. Genel Bakış bölmesindeki Yönet'in altında Sertifikalar ve sırlar>İstemci sırları> seçin.

2. İstemci gizli anahtarınız için bir açıklama ekleyin, örneğin İstemci gizli anahtarım.

3. Gizli dizi için bir süre sonu seçin veya özel bir yaşam süresi belirtin.

   • Bir gizli anahtarın ömrü iki yıl (24 ay) veya daha kısa bir süreyle sınırlıdır. 24 aydan uzun bir özel yaşam süresi belirtemezsiniz.
   • Microsoft, 12 aydan kısa bir süre sonu değeri ayarlamanızı önerir.

4. Ekle'yi seçin.

5. İstemci gizli anahtarının Değerini kaydettiğinizden emin olun. Bu gizli değer, bu sayfadan ayrıldıktan sonra bir daha görüntülenmez.

İstemci gizli anahtarınızı güvenli bir şekilde depolama hakkında daha fazla bilgi için bkz. Key Vault'ta gizli yönetimi için en iyi yöntemler.

Web API'nize erişim izinleri ekleme

Web uygulaması, bir web API'sinin kapsamlarını belirterek Microsoft kimlik platformu tarafından sağlanan kapsamları içeren bir erişim belirteci alabilir. Kod içinde web API'si daha sonra erişim belirtecinde bulunan kapsamlara göre kaynaklarına izin tabanlı erişim sağlayabilir.

İstemcinin web API'sine yönelik izinlerini yapılandırmak için şu adımları izleyin:

1. Uygulamanızın Genel Bakış bölmesindeki Yönet'in altında API izinleriKuruluşumun kullandığı izin >API'leri>ekle'yiseçin.
2. YeniWebAPI1'i veya izin eklemek istediğiniz API'yi seçin.
3. İzinleri Seç altında, Forecast.Read'in yanındaki kutuyu işaretleyin. İzin listesini genişletmeniz gerekebilir. Bu, istemci uygulamasının oturum açmış kullanıcı adına sahip olması gereken izinleri seçer.
4. İşlemi tamamlamak için İzin ekle'yi seçin.

BU izinleri API'nize ekledikten sonra , Yapılandırılmış izinler altında seçili izinleri görmeniz gerekir.

Microsoft Graph API'sinin User.Read iznini de fark edebilirsiniz. Bu izin, bir uygulamayı kaydettiğinizde otomatik olarak eklenir.

Web API'sini test edin

API'nizin çalışır durumda olduğundan ve istekleri işlemeye hazır olduğundan emin olmak için şu adımları izleyin:

1. ms-identity-docs-code-dotnet deposunu kopyalayın.

   git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
   

2. adresine ms-identity-docs-code-dotnet/web-api gidin ve dosyasını açınappsettings.json, ve {APPLICATION_CLIENT_ID} değerlerini aşağıdaki değerlerle değiştirin{DIRECTORY_TENANT_ID}:

   • {APPLICATION_CLIENT_ID}, uygulamanın Genel Bakış bölmesindeki web API'si Uygulaması (istemci) kimliğidir.
   • {DIRECTORY_TENANT_ID}, uygulamanın Genel Bakış bölmesindeki web API Dizini (kiracı) kimliğidir.

3. Uygulamayı başlatmak için aşağıdaki komutu yürütebilirsiniz:

   dotnet run
   

4. Aşağıdakine benzer bir çıkış görüntülenir. BAĞLANTı noktası numarasını URL'ye https://localhost:{port} kaydedin.

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:{port}
   ...
   

Web API'sini test edin

API'nizin çalışır durumda olduğundan ve istekleri işlemeye hazır olduğundan emin olmak için şu adımları izleyin:

1. Oluşturulan web API'ye gidin Öğretici: ASP.NET Core projesi oluşturma ve API'yi yapılandırma, örneğin NewWebAPILocal, ve klasörü açın.

2. Yeni bir terminal penceresi açın ve web API projesinin bulunduğu klasöre gidin.

   .NET 6.0

   1. Uygulamayı başlatmak için aşağıdaki komutu yürütebilirsiniz:

      dotnet run
      

   .NET 7.0

   1. Yeni bir terminal açın ve uygulamayı profilde https başlatmak için aşağıdaki komutu çalıştırın:

      dotnet run -launch-profile https`
      

3. Aşağıdakine benzer bir çıkış görüntülenir. BAĞLANTı noktası numarasını URL'ye https://localhost:{port} kaydedin.

   ...
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:{port}
   ...
   

Uykusuzluk içinde web API'sine yetkili bir istek yapılandırma

API istekleriniz için erişim belirteci almak için şu adımları izleyin:

1. Uykusuzluk uygulamasını başlatın.

2. Yeni HTTP İsteği'ni seçin veya yeni bir HTTP İsteği oluşturmak için Ctrl + N tuşlarını kullanabilirsiniz.

3. Yeni İstek penceresi bölümünde açılan listeden bir GET metodu seçin.

4. İstek URL'si için web API'si https://localhost:{port}/weatherforecasttarafından kullanıma sunulan uç noktanın URL'sini girin.

5. Kimlik Doğrulama açılan menüsündeN OAuth 2.0'ı seçin. Bu, OAuth 2.0 formunu görüntüler.

6. OAuth 2.0 formuna aşağıdaki değerleri girin:

   Ayar	Değer
   Hibe Türü	Yetkilendirme Kodu'nu seçin
   YETKILENDIRME URL'si	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize {tenantId} değerini Dizin (kiracı) Kimliği ile değiştirin
   ERİŞİM JETONU URL	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token {tenantId} ile Dizin (kiracı) kimliği değiştirin
   İstemci Kimliği	Web uygulaması kaydınızın Uygulama (istemci) Kimliği değeri
   İSTEMCI GIZLI ANAHTARı	Web uygulaması kaydınızın istemci sırrı Değeri
   YENIDEN YÖNLENDIRME URL'si	YENIDEN YÖNLENDIRME URL'sini Microsoft Entra Kimliği ile kaydedilen Yeniden Yönlendirme URI'sine ayarlayan girin http://localhost.
   Gelişmiş Seçenekler>KAPSAM	api://{application_client_id}/Forecast.Read Web uygulaması kaydınıza gidin, Yönet'in altında API izinleri'ne ve ardından Tahmin.Oku'ya tıklayın. Kapsam değerini içeren metin kutusundaki değeri kopyalayın

Erişim belirteci alma ve web API'sine istek gönderme

1. Bu değerler girildikten sonra formun sonundaki Belirteçleri Getir'i seçin. Bu, kullanıcı kimlik bilgilerinizle kimlik doğrulaması yaptığınız bir Uykusuzluk tarayıcı penceresi başlatır. Tarayıcıdaki Uykusuzluk uygulamasından açılır pencerelere izin verileceğinden emin olun.
2. Kimlik doğrulamasından sonra, isteği korumalı web API'si uç noktasına göndermek için Gönder'i seçin.

İstekte geçerli bir erişim belirteci bulunduğundan, beklenen yanıt 200 Tamam'dır ve şuna benzer bir çıkış vardır:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

İlgili içerik

OAuth 2.0 yetkilendirme kodu akışı ve uygulama türleri hakkında daha fazla bilgi için bkz:

• Microsoft kimlik platformu ve OAuth 2.0 yetkilendirme kodu akışı
• Microsoft kimlik platformu için uygulama türleri