Hızlı Başlangıç: Web API'sini kullanıma açmak için uygulama yapılandırma

  • Makale

Bu hızlı başlangıçta, bir web API'sini Microsoft kimlik platformu kaydedecek ve 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

Web API'sini kaydetme

API'lere erişim için erişim kapsamlarının ve rollerin yapılandırılması gerekir. 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.

Hızlı Başlangıç: Uygulamayı Microsoft kimlik platformu kaydetme bölümünün Uygulama kaydetme bölümündeki adımları gerçekleştirin.

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 atama

  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.

Dekont

Hem API uygulamasının hem de izin eklemek istediğiniz uygulamanın sahibi olduğundan emin olun; aksi takdirde API izinleri istenirken API listelenmez.

Uygulama rolü atama

  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 Veri Akışı Açıklaması Ö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.

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.

Kapsam ekle

Bahşiş

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

İ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.

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

  1. Microsoft Entra yönetim merkezinde en az Bulut Uygulaması Yönetici istrator 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. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları ve ardından API'nizin uygulama kaydını seçin.

  4. API'yi kullanıma sunma'ya tıklayın

  5. Henüz yapılandırmadıysanız Uygulama Kimliği URI'si'nin yanındaki Ekle'yi seçin.

    varsayılan değerini api://<application-client-id> veya desteklenen başka bir Uygulama Kimliği URI'si desenini kullanabilirsiniz. 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.

  6. Kapsam ekle'yi seçin:

    An app registration's Expose an API pane in the Azure portal

  7. 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 Veri Akışı Açıklaması Ö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ığı. Daha yüksek ayrıcalıklı izinler için Yalnızca yöneticiler’i seçin. Yönetici'ler ve kullanıcılar
    Yönetici onayı görünen adı Kapsamın yalnızca yöneticilerin göreceği amacının kısa bir açıklaması. Read-only access to Employee records
    Yönetici onayı açıklaması Yalnızca yöneticilerin göreceği kapsam tarafından verilen iznin daha ayrıntılı bir açıklaması. Allow the application to have read-only access to all Employee data.
    Kullanıcı onayı görünen adı Kapsamın amacının kısa bir açıklaması. Kullanıcılara yalnızca Yönetici ve kullanıcılara Kimlerin onay verebileceğini ayarlarsanız gösterilir. Read-only access to your Employee records
    Kullanıcı onayı açıklaması Kapsam tarafından verilen iznin daha ayrıntılı bir açıklaması. Kullanıcılara yalnızca Yönetici ve kullanıcılara Kimlerin onay verebileceğini ayarlarsanız gösterilir. Allow the application to have read-only access to your Employee data.

  8. Durumu Etkin olarak ayarlayın ve kapsam ekle'yi seçin.

  9. (İ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. Önceden 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.

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 şu değerleri belirtin:

Alan Örnek değer
Kapsam adı Employees.Write.All
Kimler onaylayabilir Yalnızca Yönetici
Yönetici onayı görünen adı Write access to Employee records
Yönetici onayı açıklaması Allow the application to have write access to all Employee data.
Kullanıcı onayı görünen adı Yok (boş bırakın)
Kullanıcı onayı açıklaması Yok (boş bırakın)

Durumu Etkin olarak ayarlayın ve kapsam ekle'yi seçin.

Kullanıma sunulan kapsamları doğrulama

Ö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:

Screenshot of the Expose an API pane showing two exposed scopes.

Görüntüde gösterildiği gibi, 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.

Gerekirse daha sonra ek kapsamları kullanıma sunabilirsiniz. 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ımlar

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