Web API'sini kullanıma açmak için uygulama yapılandırma

Bu nasıl yapılır kılavuzunda, bir web API'sini Microsoft kimlik platformuna kaydedecek ve bir kapsam ekleyerek istemci uygulamalarına göstereceksiniz. Web API'nizi kaydedip kapsamlar aracılığıyla kullanıma sunarak, sahip ve uygulama rolü atayarak, API'nize erişen yetkili kullanıcılara ve istemci uygulamalarına kaynaklarına izin tabanlı erişim sağlayabilirsiniz.

Önkoşullar

• Aktif bir aboneliğe sahip bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturun.
• Microsoft Entra yönetim merkezine kayıtlı bir uygulama. Uygulamanız yoksa şimdi bir uygulama kaydedin.

Web API'sini kaydetme

API'lere erişim, erişim kapsamlarının ve rollerinin yapılandırılmasını gerektirir. Kaynak uygulama web API'lerinizi istemci uygulamalarına göstermek istiyorsanız, API için erişim kapsamlarını ve rolleri yapılandırın. bir istemci uygulamasının bir web API'sine erişmesini istiyorsanız, uygulama kaydında API'ye erişim izinlerini yapılandırın. Web API'nizdeki kaynaklara kapsamlı erişim sağlamak için öncelikle API'yi Microsoft kimlik platformu kaydetmeniz gerekir.

1. Microsoft Entra yönetim merkezine en az bir Bulut Uygulaması Yöneticisi olarak oturum açın.
2. Birden çok kiracıya erişiminiz varsa, Üst menüdeki Ayarlar simgesini kullanarak Dizinler + abonelikler menüsünden uygulama kaydını içeren kiracıya geçin.
3. Uygulamayı kaydetme adımlarını gerçekleştirin ve Yeniden Yönlendirme URI'sini (isteğe bağlı) atlayın. Hiçbir kullanıcı etkileşimli olarak oturum açmadığından, web API'sinde yeniden yönlendirme URI'sini yapılandırmanız gerekmez.

Uygulama sahibi atayın

1. Uygulama kaydınızda Yönet'in altında, Sahipler'i ve Sahip ekle'yi seçin.
2. Yeni pencerede, uygulamaya atamak istediğiniz sahipleri bulun ve seçin. Seçili sahipler sağ panelde görünür. İşiniz bittiğinde Select ile onaylayın. Uygulama sahipleri artık sahip listesinde görünür.

Not

Hem API uygulamasına hem de izin eklemek istediğiniz uygulamaya sahip atandığından emin olun; aksi takdirde API izinleri istenirken API listelenmez.

Uygulama rolü atayın

1. Uygulama kaydınızda Yönet'in altında Uygulama rolleri'ne ve Uygulama rolü oluştur'a tıklayın.

2. Ardından, Uygulama rolü oluştur bölmesinde uygulama rolünün özniteliklerini belirtin. Bu kılavuz için örnek değerleri kullanabilir veya kendi değerlerinizi belirtebilirsiniz.

   Alan	Açıklama	Örnek
   Görünen ad	Uygulama rolünüzün adı	Çalışan Kayıtları
   İzin verilen üye türleri	Uygulama rolünün kullanıcılara/gruplara ve/veya uygulamalara atanıp atanamayacağını belirtir	Uygulamalar
   Değer	Belirtecin "roller" talebinde görüntülenen değer	Employee.Records
   Açıklama	Uygulama rolünün daha ayrıntılı bir açıklaması	Uygulamaların çalışan kayıtlarına erişimi vardır

3. Uygulama rolünü etkinleştirmek için onay kutusunu seçin ve ardından Uygula'yı seçin.

Kapsam ekle

Web API'sinin kayıtlı olması, bir uygulama rolüne ve sahipe atanmasıyla, tüketicilere ayrıntılı izinler sağlayabilmesi için API'nin koduna kapsamlar ekleyebilirsiniz.

İstemci uygulamasındaki kod, istekleriyle birlikte korumalı kaynağa (web API'sine) bir erişim belirteci geçirerek web API'niz tarafından tanımlanan işlemleri gerçekleştirme izni ister. Ardından web API'niz istenen işlemi yalnızca aldığı erişim belirteci işlem için gereken kapsamları içeriyorsa gerçekleştirir.

Yönetici ve kullanıcı onayı gerektiren bir kapsam ekleme

İlk olarak, adlı Employees.Read.Allörnek bir kapsam oluşturmak için şu adımları izleyin:

1. Bir API’yi kullanıma sunma'yı seçin.

2. Sayfanın üst kısmında Uygulama Kimliği URI'si'nin yanındaki Ekle'yi seçin. Bu varsayılan olarak api://<application-client-id> olur. Uygulama Kimliği URI'si, API'nizin kodunda başvurabileceğiniz kapsamlar için ön ek görevi görür ve genel olarak benzersiz olmalıdır. Kaydet'i seçin.

3. Bir kapsam ekle seçin.

   

4. Ardından Kapsam ekle bölmesinde kapsamın özniteliklerini belirtin. Bu kılavuz için örnek değerleri kullanabilir veya kendi değerlerinizi belirtebilirsiniz.

   Alan	Açıklama	Örnek
   Kapsam adı	Kapsamınızın adı. Yaygın bir kapsam adlandırma kuralıdır resource.operation.constraint.	Employees.Read.All
   Kimler onaylayabilir	Bu kapsamın kullanıcılar tarafından onaylanıp onay verilemeyeceği veya yönetici onayının gerekli olup olmadığı. Yöneticiler yalnızca daha yüksek ayrıcalıklı izinler için kullanılmalıdır.	Yöneticiler ve kullanıcılar
   Yönetici onayı görüntü adı	Kapsamın yalnızca yöneticilerin göreceği amacının kısa bir açıklaması.	Çalışan kayıtlarına salt okunur erişim
   Yönetici onayı açıklaması	Yalnızca yöneticilerin göreceği, kapsamın verdiği iznin daha ayrıntılı bir açıklaması.	Uygulamanın tüm Çalışan verilerine salt okunur erişimine izin verin.
   Kullanıcı onayı görünen adı	Kapsamın amacının kısa bir açıklaması. Kullanıcılara yalnızca Yöneticilere ve kullanıcılara Kimlerin onay verebileceğini ayarlarsanız gösterilir.	Çalışan kayıtlarınıza yalnızca okuma izni
   Kullanıcı onayı açıklaması	Kapsamın verdiği iznin daha ayrıntılı bir açıklaması. Kullanıcılara yalnızca Yöneticilere ve kullanıcılara Kimlerin onay verebileceğini ayarlarsanız gösterilir.	Uygulamanın Çalışan verilerinize salt okunur erişimine izin verin.
   Eyalet	Kapsamın etkin mi yoksa devre dışı mı olduğu.	Etkin

5. Kapsam ekle'yi seçin.

6. (İsteğe bağlı) Uygulamanızın kullanıcılarının tanımladığınız kapsamlara onay istemesini engellemek için, istemci uygulamasının web API'nize erişmesi için önceden yetki verebilirsiniz. Kullanıcılarınız onayı reddetme fırsatına sahip olmayacağından yalnızca güvendiğiniz istemci uygulamalarını önceden yetkilendirilin.

   1. Yetkili istemci uygulamaları'nın altında İstemci uygulaması ekle'yi seçin.
   2. Ön yetkilendirmek istediğiniz istemci uygulamasının Uygulama (istemci) kimliğini girin. Örneğin, daha önce kaydettiğiniz bir web uygulaması.
   3. Yetkili kapsamlar'ın altında, onay istemini engellemek istediğiniz kapsamları seçin ve ardından Uygulama ekle'yi seçin.

   Bu isteğe bağlı adımı izlediyseniz, istemci uygulaması artık önceden yetkilendirilmiş bir istemci uygulamasıdır (PCA) ve kullanıcılardan oturum açarken onayları istenmez.

Yönetici onayı gerektiren bir kapsam ekleme

Ardından, yalnızca yöneticilerin onay verebileceği adlı Employees.Write.All başka bir örnek kapsam ekleyin. Yönetici onayı gerektiren kapsamlar genellikle daha yüksek ayrıcalıklı işlemlere erişim sağlamak için ve genellikle bir kullanıcıda etkileşimli olarak oturum açmayan arka uç hizmetleri veya daemon'lar olarak çalışan istemci uygulamaları tarafından kullanılır.

Örnek kapsamı eklemek Employees.Write.All için Kapsam ekle bölümündeki adımları izleyin ve Kapsam ekle bölmesinde bu değerleri belirtin. İşiniz bittiğinde Kapsam ekle'yi seçin.

Alan	Örnek değer
Kapsam adı	Employees.Write.All
Kimler onaylayabilir	Yalnızca yöneticiler
Yönetici onayı görüntü adı	Çalışan kayıtlarına yazma erişimi
Yönetici onayı açıklaması	Uygulamanın tüm Çalışan verilerine yazma erişimine sahip olmasını sağlayın.
Kullanıcı onayı görünen adı	Yok (boş bırakın)
Kullanıcı onayı açıklaması	Yok (boş bırakın)
Eyalet	Etkin

Açıkta kalan kapsamları doğrulayın

Önceki bölümlerde açıklanan her iki örnek kapsamı da başarıyla eklediyseniz, bunlar aşağıdaki görüntüye benzer şekilde web API'nizin uygulama kaydının API'yi kullanıma sunma bölmesinde görünür:

Kapsamın tam dizesi, web API'nizin Uygulama Kimliği URI'sinin ve kapsamın Kapsam adının birleştirilmiş halidir. Örneğin, web API'nizin uygulama kimliği URI'si https://contoso.com/api ve kapsam adı ise Employees.Read.All, tam kapsam şöyledir:

https://contoso.com/api/Employees.Read.All

Kullanıma sunulan kapsamları kullanma

Bu serinin sonraki makalesinde, bu makaledeki adımları izleyerek bir istemci uygulamasının web API'nize ve tanımladığınız kapsamlara erişimi olan kaydını yapılandıracaksınız.

Bir istemci uygulama kaydına web API'nize erişim izni verildikten sonra, istemciye kimlik platformu tarafından bir OAuth 2.0 erişim belirteci verilebilir. İstemci web API'sini çağırdığında, kapsamı (scp) talebi istemcinin uygulama kaydında belirttiğiniz izinlere ayarlanmış bir erişim belirteci sunar.

İhtiyaç duyarsanız daha sonra ek kapsamları kullanıma açabilirsiniz. Web API'nizin birkaç işlemle ilişkili birden çok kapsamı kullanıma çıkarabileceğini düşünün. Kaynağınız, aldığı OAuth 2.0 erişim belirtecindeki kapsam (scp) taleplerini değerlendirerek çalışma zamanında web API'sine erişimi denetleyebiliyor.

Sonraki adım

Kapsamlarını yapılandırarak web API'nizi kullanıma sunduğunuza göre, istemci uygulamanızın kaydını kapsamlara erişim izniyle yapılandırın.

Web API'si erişimi için uygulama kaydı yapılandırma