Aracılığıyla paylaş

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

  • Makale

Bu makalede, İstemci URL'sini (cURL) kullanarak korumalı ASP.NET Core web API'sini nasıl çağırabileceğiniz gösterilir. cURL, geliştiricilerin bir sunucuya ve sunucudan veri aktarmak için kullandığı bir komut satırı aracıdı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, cURL kullanarak web API'sine yetkili bir çağrı yapmak için belirteci kullanırsınız.

Bu makalede, İstemci URL'sini (cURL) kullanarak korumalı ASP.NET Core web API'sini nasıl çağırabileceğiniz gösterilir. cURL, geliştiricilerin bir sunucuya ve sunucudan veri aktarmak için kullandığı bir komut satırı aracıdı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, cURL 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
  • İş istasyonu bilgisayarınıza cURL indirip yükleyin.
  • En düşük .NET 8.0 SDK gereksinimi.

Microsoft kimlik platformu ile uygulama 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ı, 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 simgesinikullanı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ölmesi görüntülenir. Uygulama kaynak kodunuzda 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 listelenir.

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

Web uygulamasını kaydetme

Ancak web API'sine sahip olmak yeterli değildir, çünkü oluşturduğunuz web API'sine erişmek için bir erişim belirteci almak için de bir web uygulaması gerekir.

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 gibi web-app-calls-web-apibir 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 simgesinikullanın.
  3. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.
  4. Yeni kayıt öğesini seçin.
  5. Uygulama için gibi web-app-calls-web-apibir 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, uygulama kaydı Genel Bakış bölmesinde görüntülenir. 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.

Web API'sine erişime izin vermek için uygulama izinleri ekleme

Web uygulaması kaydında bir web API'sinin kapsamlarını belirterek, web uygulaması 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.

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

  1. Web uygulamanızın Genel Bakış bölmesinden (web-app-that-calls-web-api), 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

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

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

  2. Klasöre ms-identity-docs-code-dotnet/web-api gidin ve dosyayı açın./appsettings.json, ve {DIRECTORY_TENANT_ID} öğesini {APPLICATION_CLIENT_ID} şununla değiştirin:

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

  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

  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

  1. 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}
...

Yetkilendirme kodu isteme

Yetkilendirme kodu akışı, istemcinin kullanıcıyı uç noktaya yönlendirmesiyle /authorize başlar. Bu istekte, istemci kullanıcıdan izin istemektedir Forecast.Read .

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

  1. URL'yi kopyalayın, aşağıdaki parametreleri değiştirin ve tarayıcınıza yapıştırın:

    • {tenant_id} , web uygulaması Dizin (kiracı) kimliğidir.
    • {web-app-calls-web-api_application_client_id}, web uygulamasının (web-app-calls-web-api) Genel Bakış bölmesindeki Uygulama (istemci) kimliğidir.
    • {web_API_application_client_id}, web API'sinin (NewWebAPI1) Genel Bakış bölmesindeki Uygulama (istemci) kimliğidir.

  2. Uygulamaların kaydedildiği Microsoft Entra kiracısında kullanıcı olarak oturum açın. Gerekirse erişim isteklerine onay verme.

  3. Tarayıcınız adresine http://localhost/yönlendirilir. Tarayıcınızın gezinti çubuğuna bakın ve aşağıdaki adımlarda kullanmak üzere öğesini kopyalayın {authorization_code} . URL aşağıdaki kod parçacığının biçimini alır:

    http://localhost/?code={authorization_code}

Erişim belirteci almak için yetkilendirme kodu ve cURL kullanma

cURL artık Microsoft kimlik platformu erişim belirteci istemek için kullanılabilir.

  1. Aşağıdaki kod parçacığındaki cURL komutunu kopyalayın. Parantez içindeki değerleri terminalinize aşağıdaki parametrelerle değiştirin. Parantezleri kaldırdığınızdan emin olun:

    curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
    • {tenant_id} , web uygulaması Dizin (kiracı) kimliğidir.
    • client_id={web-app-calls-web-api_application_client_id}ve session_state={web-app-calls-web-api_application_client_id} web uygulamasının (web-app-calls-web-api) Genel Bakış bölmesindeki Uygulama (istemci) kimliğidir.
    • api://{web_API_application_client_id}/Forecast.Read, web API'sinin (NewWebAPI1) Genel Bakış bölmesindeki Uygulama (istemci) kimliğidir.
    • code={authorization_code} , Yetkilendirme kodu isteme bölümünde alınan yetkilendirme kodudur. Bu, cURL aracının erişim belirteci istemesini sağlar.
    • client_secret={client_secret}, İstemci gizli dizisi ekleme bölümünde kaydedilen istemci gizli dizisi Değeridir.

  2. cURL komutunu çalıştırın ve doğru girilirse aşağıdaki çıkışa benzer bir JSON yanıtı almanız gerekir:

    {
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

Erişim belirteci ile web API'si çağırma

Önceki cURL komutunu çalıştırarak Microsoft kimlik platformu bir erişim belirteci sağlamıştır. Alınan belirteç artık web API'sini çağırmak için http isteğinde taşıyıcı olarak kullanılabilir.

  1. Web API'sini çağırmak için aşağıdaki cURL komutunu kopyalayın, parantez içinde aşağıdaki değerleri değiştirin ve terminalinize yapıştırın:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} önceki bölümdeki JSON çıkışından kaydedilen erişim belirteci değeri.
    • {port} terminalde API'yi çalıştırırken kaydedilen web API'sinden bağlantı noktası numarası. Bağlantı noktası numarası olduğundan https emin olun.

  2. İstekte geçerli bir erişim belirteci bulunduğunda, beklenen yanıt aşağıdaki çıkışa benzer bir çıkışla olur HTTP/2 200 :

    HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

Sonraki adımlar

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