Microsoft Entra uygulamalarıyla ürünlere ve API'lere güvenli bir şekilde erişin

ŞUNLAR IÇIN GEÇERLIDIR: Geliştirici | Temel | Standart | Premium

API Management artık istemci kimlik bilgileri akışını kullanarak ürün API'lerine yerleşik OAuth 2.0 uygulama tabanlı erişimi destekliyor. Bu özellik, API yöneticilerinin Microsoft Entra ID uygulamalarını kaydetmesine olanak tanır ve OAuth 2.0 yetkilendirmesi aracılığıyla geliştiriciler için güvenli API erişiminin akışını sağlar.

Uyarı

Uygulamalar şu anda sınırlı önizleme aşamasındadır. Kaydolmak için bu formu doldurun.

Bu özellik ile:

• API yöneticileri, uygulama tabanlı erişimi etkinleştirmek için bir ürün özelliği ayarlar.
• API yöneticileri, belirli ürünlere erişimi sınırlamak için istemci uygulamalarını Microsoft Entra Id'ye kaydeder.
• Geliştiriciler API Management geliştirici portalını kullanarak istemci uygulaması kimlik bilgilerine erişebilir.
• Geliştiriciler veya uygulamalar, OAuth 2.0 istemci kimlik bilgileri akışını kullanarak API isteklerine ekleyebilecekleri belirteçleri alır
• API isteklerinde sunulan belirteçler, ürünün API'lerine erişim yetkisi vermek için API Management ağ geçidi tarafından doğrulanır.

Önkoşullar

• Premium, Standart, Temel veya Geliştirici katmanında dağıtılan bir API Management örneği. Bir örnek dağıtmanız gerekiyorsa API Yönetimi hizmeti örneği oluşturun'a bakın.

• API Yönetimi örneğinizde, en az bir API atanmış en az bir ürün bulunmalıdır.

  • Ürün, geliştiriciler tarafından geliştirici portalı üzerinden erişilebilmeleri için Yayımlandı durumunda olmalıdır.
  • Test için varsayılan Starter ürününü ve buna eklenen Echo API'sini kullanabilirsiniz.
  • Ürün oluşturmak istiyorsanız bkz. Ürün oluşturma ve yayımlama.

• En azından Ayrıcalıklı Rol Yöneticisi rolünü gerektiren Uygulama Yöneticisi rolünü atamak için Microsoft Entra kiracınızda yeterli izinler.

• İsteğe bağlı olarak API Management örneğinize bir veya daha fazla kullanıcı ekleyin.

• Azure PowerShell'i yerel olarak kullanmayı seçerseniz:
  • Az PowerShell modülünün en son sürümünü yükleyin.
  • Connect-AzAccount cmdlet'ini kullanarak Azure hesabınıza bağlanın.
• Azure Cloud Shell'i kullanmayı seçerseniz:
  • Daha fazla bilgi için bkz. Azure Cloud Shell'e genel bakış .

Yönetilen kimliği yapılandırma

1. API Management örneğinizde API Management için sistem tarafından atanan yönetilen kimliği etkinleştirin.

2. Kimliği Microsoft Entra Id'de Uygulama Yöneticisi RBAC rolüne atayın. Rolü atamak için:

   1. Portalda oturum açın ve Microsoft Entra Id'ye gidin.
   2. Sol menüdeRolleri ve yöneticileri> seçin.
   3. Uygulama yöneticisi'ni seçin.
   4. Soldakimenüden Atamaları>Yönet>+ Ödev ekle'yi seçin.
   5. Atamaları ekle sayfasında, API Management örneğinin yönetilen kimliğini adıyla (API Management örneğinin adı) arayın. Yönetilen kimliği ve ardından Ekle'yi seçin.

Ürün için uygulama tabanlı erişimi etkinleştirme

Bir ürün için Uygulama tabanlı erişimi etkinleştirmek için bu adımları izleyin. Sonraki adımlarda bir ürünün bir istemci uygulamasıyla ilişkilendirilmesi için bu ayarın etkinleştirilmesi gerekir.

Aşağıdaki örnekte Starter ürünü kullanılır. Ancak, en az bir API'nin atandığı herhangi bir yayımlanmış ürünü seçin.

1. Uygulamalar özelliği için aşağıdaki özel URL'de portalda oturum açın: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=uygulamalar
2. API Management örneğine gidin.
3. Soldaki menüde , API'ler'in altında Ürünler'i seçin.
4. Yapılandırmak istediğiniz ürünü seçin, örneğin Starter ürünü.
5. Soldaki menüde, Ürün altında Özellikler'i seçin.
6. Uygulama tabanlı erişim bölümünde OAuth 2.0 belirteci (en güvenli) ayarını etkinleştirin.
7. İsteğe bağlı olarak Abonelik anahtarı ayarını etkinleştirin. Hem uygulama tabanlı erişimi hem de abonelik gereksinimini etkinleştirirseniz, API Management ağ geçidi ürünün API'lerine erişim için OAuth 2.0 belirtecini veya abonelik anahtarını kabul edebilir.
8. Kaydetseçeneğini seçin.

Tavsiye

Yeni bir ürün oluştururken OAuth 2.0 belirteç ayarını da etkinleştirebilirsiniz.

Uygulama tabanlı erişimin etkinleştirilmesi, Microsoft Entra Id'de ürünü temsil eden bir arka uç kurumsal uygulaması oluşturur. Arka uç uygulama kimliği ürünün Özellikler sayfasında görüntülenir.

Uyarı

Bu uygulama kimliği, ürüne erişmek için bir istemci uygulaması oluştururken hedef kitle değeri olarak ayarlanır. Ürün API'sini çağırmak için belirteç oluştururken de bu değeri kullanın.

(İsteğe bağlı) Microsoft Entra Id'de ürün uygulaması ayarlarını gözden geçirme

İsteğe bağlı olarak, ürünü temsil etmek için Microsoft Entra Id'de oluşturulan arka uç kurumsal uygulamasının ayarlarını gözden geçirin.

Uygulama şu biçimde adlandırılır: APIMProductApplication<ürün adı>. Örneğin, ürün adı Starter ise uygulama adı APIMProductApplicationStarter'dır. Uygulamanın tanımlanmış bir Uygulama rolü vardır.

Uygulama kayıtlarında uygulama ayarlarını gözden geçirmek için:

1. Portalda oturum açın ve Microsoft Entra Id>Manage>App registrations bölümüne gidin.
2. Tüm uygulamalar'ı seçin.
3. API Management tarafından oluşturulan uygulamayı arayın ve seçin.
4. Soldaki menüde Yönet'in altında Uygulama rolleri'ni seçin.
5. Aşağıdaki ekran görüntüsünde gösterildiği gibi Azure API Management tarafından ayarlanan uygulama rolünü onaylayın:

Ürüne erişmek için istemci uygulamasını kaydetme

Şimdi bir veya daha fazla ürüne erişimi sınırlayan bir istemci uygulaması kaydedin.

• Bir ürünün bir istemci uygulamasıyla ilişkilendirilmesi için Uygulama tabanlı erişimin etkinleştirilmiş olması gerekir.
• Her istemci uygulamasının API Management örneğinde tek bir kullanıcısı (sahibi) vardır. Ürün API'lerine uygulama üzerinden yalnızca sahip erişebilir.
• Bir ürün birden fazla istemci uygulamasıyla ilişkilendirilebilir.

İstemci uygulamasını kaydetmek için:

1. Uygulamalar özelliği için aşağıdaki özel URL'de portalda oturum açın: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=uygulamalar

2. API Management örneğine gidin.

3. Soldaki menüde, API'ler'in altında Uygulamalar>+ Uygulamayı kaydet'i seçin.

4. Uygulamayı kaydet sayfasında aşağıdaki uygulama ayarlarını girin:

   • Ad: Uygulama için bir ad girin.
   • Sahip: API Management örneğindeki kullanıcıların açılan listesinden uygulamanın sahibini seçin.
   • Seçili ürünlere erişim izni ver: API Management örneğinde daha önce Uygulama tabanlı erişim için etkinleştirilen bir veya daha fazla ürün seçin.
   • Açıklama: İsteğe bağlı olarak bir açıklama girin.

   

5. Kaydıseçin.

Uygulama, Uygulamalar sayfasındaki uygulama listesine eklenir. İstemci Kimliği gibi ayrıntıları görüntülemek için uygulamayı seçin. Ürün API'sini çağırmak üzere bir belirteç oluşturmak için bu kimlik gereklidir.

Tavsiye

• Bir uygulama oluşturduktan sonra isteğe bağlı olarak diğer ürünlerle ilişkilendirin. Uygulamalar sayfasında uygulamayı seçin ve ardından Ayrıntılar>Ürünler>+ Ürün ekle'yi seçin.
• Ürünler sayfasından bir ürünü düzenleyerek de uygulama oluşturabilir veya ilişkilendirebilirsiniz.

İstemci gizli anahtarı oluşturma

İstemci uygulamasının OAuth 2.0 istemci kimlik bilgileri akışını kullanması için bir istemci gizli dizisi oluşturulmalıdır. Gizli anahtarın geçerlilik süresi bir yıldır, ancak herhangi bir zamanda yeniden oluşturulabilir.

1. Uygulamalar sayfasında, oluşturduğunuz uygulamayı seçin.

2. Uygulamanın Genel Bakış sayfasında, Müşteri Sırrı yanındaki Sır Ekle'ye tıklayın.

3. Yeni istemci gizli anahtarı sayfasında Oluştur'u seçin.

   İstemci gizli dizisi oluşturulur ve İstemci gizli dizisi alanında görüntülenir. Gizli değeri kopyalayıp güvenli bir şekilde depoladığınızdan emin olun. Sayfayı kapattıktan sonra yeniden alamazsınız.

4. Kapat'ıseçin.

(İsteğe bağlı) Microsoft Entra Id'de istemci uygulama ayarlarını gözden geçirme

İsteğe bağlı olarak Microsoft Entra Id'de istemci uygulamasının ayarlarını gözden geçirin.

Uygulama şu biçimde adlandırılır: APIMApplication<ürün adı>. Örneğin, ürün adı Starter ise, uygulama adı APIMApplicationStarter'a benzer.

Uygulama kayıtlarında uygulama ayarlarını gözden geçirmek için:

1. Portalda oturum açın ve Microsoft Entra Id>Manage>App registrations bölümüne gidin.

2. Tüm uygulamalar'ı seçin.

3. API Management tarafından oluşturulan istemci uygulamasını arayın ve seçin.

4. Soldaki menüde , Yönet'in altında API izinleri'ni seçin.

5. Uygulamanın arka uç ürün uygulamasına veya uygulamalarına erişme izinlerine sahip olduğunu onaylayın.

   Örneğin, istemci uygulaması Starter ürününe erişim verirse, uygulamanın APIMProductApplicationStarter uygulamasına erişmek için Product.Starter.All izinleri vardır.

   

Geliştirici portalında uygulama ayarlarını alma

Kullanıcılar, sahip oldukları istemci uygulamalarını görüntülemek için geliştirici portalında oturum açabilir.

1. bir istemci uygulamasının sahibi olarak ayarlanmış bir kullanıcı hesabını kullanarak geliştirici portalında (https://<your-apim-instance-name>.developer.azure-api.net) oturum açın.

2. Üst gezinti menüsünde Uygulamalar'ı seçin.

3. Kullanıcının sahip olduğu uygulamalar listede görünür.

4. İstemci Kimliği, İstemci sırrı ve Kapsam gibi ayrıntılarını görüntülemek için bir uygulama seçin. Bu değerler, ürün API'lerini çağırmak için bir belirteç oluşturmak için gereklidir.

   

Belirteç oluşturma ve API çağrısı ile kullanma

Bir ürün için uygulama tabanlı erişimi etkinleştirdikten ve bir istemci uygulamasını kaydettikten sonra, bir geliştirici veya uygulama ürünün API'lerini çağırmak için bir belirteç oluşturabilir. Belirtecin bir isteğin başlık bölümüne Authorization eklenmesi gerekir.

Örneğin, bir geliştirici veya uygulama aşağıdaki Azure PowerShell betiklerini çalıştırarak istemci uygulamasını çağırarak belirteç oluşturabilir ve ardından belirteci kullanarak API Management'ta bir ürün API'sini çağırabilir.

Dikkat

Aşağıdaki betikler yalnızca test amaçlı örneklerdir. İstemci sırrını depolamak ve almak için güvenli bir yöntem kullanın, üretimde.

Belirteç oluşturmak için istemci uygulamasını çağırma

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Belirteç kullanarak ürün API'si çağırma

Önceki adımda oluşturulan belirteç, bir ürün API'sini çağırmak için kullanılır. Belirteç, isteğin Yetkilendirme üst bilgisinde geçirilir. API Management örneği belirteci doğrular ve API'ye erişimi yetkilendirir.

Aşağıdaki betik, echo API'sine örnek bir çağrı gösterir.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Sorun giderme

Portala uygulama kaydederken iç sunucu hatası

Uygulamaları listeleyemiyorsanız veya portala uygulama kaydederken bir iç sunucu hatası alıyorsanız aşağıdakileri denetleyin:

• Uygulama Yöneticisi rolü, Microsoft Entra Id'de API Management örneğinin yönetilen kimliğine atanır.
• Uygulamalar özelliği için aşağıdaki özel URL'de portalda oturum açtınız: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications. Bu URL, API Management'taki uygulamalar özelliğine erişmek için gereklidir.

İlgili içerik

• Ürün oluşturma ve yayımlama
• API Management'ta API'lere kimlik doğrulaması ve yetkilendirme