Korumalı web API'si: Uygulama kaydı

Bu makalede, korumalı bir web API'sine yönelik uygulama kaydının özellikleri açıklanmaktadır.

Bir uygulamayı kaydetmeye yönelik yaygın adımlar için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile uygulama kaydetme.

Kabul edilen belirteç sürümü

Microsoft kimlik platformu v1.0 belirteçleri ve v2.0 belirteçleri verebilir. Bu belirteçler hakkında daha fazla bilgi için bkz . Erişim belirteçleri.

API'nizin kabul edebileceği belirteç sürümü, Azure portalında web API'si uygulama kaydınızı oluşturduğunuzda Desteklenen hesap türleri seçiminize bağlıdır.

• Desteklenen hesap türlerinin değeri herhangi bir kuruluş dizinindeki hesaplar ve kişisel Microsoft hesapları (örneğin Skype, Xbox, Outlook.com) ise, kabul edilen belirteç sürümü v2.0 olmalıdır.
• Aksi takdirde, kabul edilen belirteç sürümü v1.0 olabilir.

Uygulamayı oluşturduktan sonra, şu adımları izleyerek kabul edilen belirteç sürümünü belirleyebilir veya değiştirebilirsiniz:

1. Azure portalında uygulamanızı ve ardından Bildirim'i seçin.
2. bildirimde accessTokenAcceptedVersion özelliğini bulun.
3. değeri Microsoft Entra'ya web API'sinin hangi belirteç sürümünü kabul ettiği belirtir.
   • Değer 2 ise, web API'si v2.0 belirteçlerini kabul eder.
   • Değer null ise, web API'si v1.0 belirteçlerini kabul eder.
4. Belirteç sürümünü değiştirdiyseniz Kaydet'i seçin.

Web API'sinin kabul ettiği belirteç sürümünü belirtir. bir istemci web API'niz için Microsoft kimlik platformu bir belirteç istediğinde, istemci web API'sinin hangi belirteç sürümünü kabul ettiğini gösteren bir belirteç alır.

Yeniden yönlendirme URI'sı yok

Hiçbir kullanıcı etkileşimli olarak oturum açmadığından Web API'lerinin yeniden yönlendirme URI'sini kaydetmesi gerekmez.

Kullanıma sunulan API

Web API'lerine özgü diğer ayarlar, kullanıma sunulan API ve kullanıma sunulan kapsamlar veya uygulama rolleridir.

Kapsamlar ve Uygulama Kimliği URI'si

Kapsamlar genellikle biçimindedir resourceURI/scopeName. Microsoft Graph için kapsamların kısayolları vardır. Örneğin, User.Read için https://graph.microsoft.com/user.readbir kısayoldur.

Uygulama kaydı sırasında şu parametreleri tanımlayın:

• Kaynak URI'si
• Bir veya daha fazla kapsam
• Bir veya daha fazla uygulama rolü

Varsayılan olarak, uygulama kayıt portalı kaynak URI'sini api://{clientId}kullanmanızı önerir. Bu URI benzersizdir ancak insan tarafından okunamaz. URI'yi değiştirirseniz, yeni değerin benzersiz olduğundan emin olun. Uygulama kayıt portalı, yapılandırılmış bir yayımcı etki alanı kullandığınızdan emin olur.

İstemci uygulamalarında kapsamlar temsilci izinleri olarak, uygulama rolleri ise web API'niz için uygulama izinleri olarak gösterilir.

Kapsamlar, uygulamanızın kullanıcılarına sunulan onay penceresinde de görünür. Bu nedenle, kapsamı açıklayan ilgili dizeleri sağlayın:

• Bir kullanıcı tarafından görüldüğü gibi.
• Yönetici onayı verebilen bir kiracı yöneticisi tarafından görüldüğü gibi.

Uygulama rolleri bir kullanıcı tarafından onaylanamaz (web API'sini kendisi adına çağıran bir uygulama tarafından kullanıldığından). Kiracı yöneticisinin web API'nizin uygulama rollerini ortaya çıkarmak için istemci uygulamalarına onay vermesi gerekir. Ayrıntılar için bkz. Yönetici onay.

Temsilci izinlerini (kapsamlar) kullanıma sunma

Temsilci izinlerini veya kapsamlarını kullanıma açmak için Web API'sini kullanıma açmak için uygulama yapılandırma makalesindeki adımları izleyin.

Bu makale kümesinde açıklanan web API senaryosunu takip ediyorsanız şu ayarları kullanın:

• Uygulama Kimliği URI'si: Önerilen uygulama kimliği URI'sini (api://< clientId>) kabul edin (istenirse)
• Kapsam adı: access_as_user
• Kim onay verebilir: Yönetici ve kullanıcılar
• Yönetici onay görünen adı: Kullanıcı olarak TodoListService'e erişme
• Yönetici onay açıklaması: TodoListService web API'sine kullanıcı olarak erişir
• Kullanıcı onayı görünen adı: Kullanıcı olarak TodoListService'e erişme
• Kullanıcı onayı açıklaması: TodoListService web API'sine kullanıcı olarak erişir
• Durum: Etkin

Web API'niz bir hizmet veya daemon uygulaması tarafından çağrılırsa

API'nize daemon'lar, hizmetler veya diğer etkileşimli olmayan (insan) uygulamalar tarafından erişilmesi gerekiyorsa, temsilci izinleri yerine uygulama izinlerini kullanıma sunma. Daemon ve hizmet türündeki uygulamalar katılımsız çalıştırıldığından ve kendi kimlikleriyle kimlik doğrulaması yaptıklarından, izinlerini "temsil eden" kullanıcı yoktur.

Uygulama izinlerini kullanıma sunma (uygulama rolleri)

Uygulama izinlerini kullanıma açmak için Uygulamanıza uygulama rolleri ekleme makalesindeki adımları izleyin.

Uygulama rolü oluştur bölmesinde İzin verilen üye türleri'nin altında Uygulamalar'ı seçin. Ya da makalede açıklandığı gibi Uygulama bildirim düzenleyicisini kullanarak rolü ekleyin.

Erişim belirteçlerini belirli istemci uygulamalarıyla kısıtlama

Uygulama rolleri, bir uygulama geliştiricisinin uygulama izinlerini kullanıma sunmada kullandığı mekanizmadır. Web API'nizin kodu, arayanlardan aldığı erişim belirteçlerinde uygulama rollerini denetlemelidir.

Microsoft Entra kiracı yöneticisi, başka bir güvenlik katmanı eklemek için kiracısını yapılandırarak Microsoft kimlik platformu yalnızca API erişimi için onayladığı istemci uygulamalarına güvenlik belirteçleri verebilir.

Belirteç verme işlemini yalnızca uygulama rolleri atanmış istemci uygulamalarıyla kısıtlayarak güvenliği artırmak için:

1. Microsoft Entra yönetim merkezinde, Kimlik>Uygulamaları> Uygulama kayıtları altında uygulamanızı seçin.
2. Uygulamanın genel bakış sayfasında, Kurumsal Uygulamaya Genel Bakış sayfasına gitmek için Yerel dizinde yönetilen uygulaması bağlantısını seçin.
3. Yönet'in altında Özellikler'i seçin.
4. Atama gerekli mi? değerini Evet olarak ayarlayın.
5. Kaydet'i seçin.

Microsoft Entra Id artık web API'niz için erişim belirteçleri isteyen istemci uygulamalarının uygulama rolü atamalarını denetleyecek. İstemci uygulamasına herhangi bir uygulama rolü atanmamışsa, Microsoft Entra Id istemciye invalid_client: AADSTS501051: Uygulama uygulaması adı> web API'si> için <bir role atanmamış gibi bir hata iletisi <döndürür.

Sonraki adımlar

Bu serinin sonraki makalesi Uygulama kodu yapılandırmasıdır.