Aracılığıyla paylaş

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

  • Makale

Bu makalede, Uykusuzluk kullanarak korumalı bir 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ı bir 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: Korumalı bir api oluşturduğunuz API'nize korumalı uç nokta uygulama bölümünden erişim belirteci oluşturmak için Microsoft kimlik platformu 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 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
  • Uykusuzluğu 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.

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

İpucu

Bu makaledeki adımlar, başladığınız portala göre biraz değişiklik gösterebilir.

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. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.

  4. Yeni kayıt öğesini seçin.

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

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

  7. Kaydet'i seçin.

    Bir ad girmeyi ve hesap türünü seçmeyi gösteren ekran görüntüsü.

  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.

    Genel bakış sayfasındaki tanımlayıcı değerlerini gösteren ekran görüntüsü.

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 Uygulama Kimliği URI'sini (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ı görünen adı kutusuna girinRead forecast data.
    4. Yönetici onayı açıklaması kutusuna yazınAllows the application to read weather forecast data.
    5. Kullanıcı onayı görünen adı kutusuna girinRead forecast data.
    6. Kullanıcı onayı açıklaması kutusuna girinAllows the application to read weather forecast data.
    7. Durum'un Etkin 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.

    Kapsamı bir API'ye eklerken alan değerlerini gösteren ekran görüntüsü.

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. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
  2. Yeni kayıt öğesini seçin.
  3. Uygulama için web-app-calls-web-api gibi bir Ad girin.
  4. Desteklenen hesap türleri için Yalnı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ında Web'i seçin ve URL metin kutusuna girinhttp://localhost.
  6. Kaydet'i 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. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
  4. Yeni kayıt öğesini seçin.
  5. Uygulama için web-app-calls-web-api gibi bir Ad girin.
  6. Desteklenen hesap türleri için Yalnı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ında Web'i seçin ve URL metin kutusuna girinhttp://localhost.
  8. Kaydet'i 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 gizli diziler>İstemci gizli dizileri Yeni istemci gizli dizisi'ni> seçin.

  2. İstemci gizli diziniz için bir açıklama ekleyin, örneğin Müşteri gizli dizim.

  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 dizisinin Değerini kaydettiğinizden emin olun. Bu gizli dizi değeri, bu sayfadan ayrıldıktan sonra bir daha görüntülenmez.

İstemci gizli dizinizi güvenli bir şekilde depolama hakkında daha fazla bilgi için bkz . Key Vault'ta gizli dizi 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 izinleri Kuruluşumun kullandığı izin>API'leri>ekle'yi seçin.
  2. YeniWebAPI1'i veya izin eklemek istediğiniz API'yi seçin.
  3. İzinleri seç'in altında, Tahmin.Okuma'nın 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 {DIRECTORY_TENANT_ID} değerlerini aşağıdaki değerlerle değiştirin{APPLICATION_CLIENT_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. Öğretici: ASP.NET Core projesi oluşturma bölümünde oluşturulan web API'sine gidin ve API'yi (örneğin , NewWebAPILocal) yapılandırın ve klasörü açın.

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

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

      dotnet run

  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 kalıcı bölümünde açılan listeden bir GET yöntemi 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 Value
    VERME TÜRÜ Yetkilendirme Kodu'nu seçin
    YETKILENDIRME URL'si https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    değerini Dizin (kiracı)Kimliği ile değiştirin {tenantId}
    ERIŞIM BELIRTECI URL'SI https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    değerini Dizin (kiracı) kimliğiyle değiştirin {tenantId}
    İstemci Kimliği Web uygulaması kaydınızın Uygulama (istemci) Kimliği değeri
    İSTEMCI GIZLI ANAHTARı Web uygulaması kaydınızın gizli dizi 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>KAPSAMI 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: