OAuth 2.0 kullanıcı yetkilendirmesini yapılandırarak geliştirici portalının test konsolunu yetkilendirme

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

Birçok API, API'nin güvenliğini sağlamak ve yalnızca geçerli kullanıcıların erişimi olduğundan ve yalnızca hak sahibi oldukları kaynaklara erişebildiklerinden emin olmak için OAuth 2.0'ı destekler. Azure API Management'ın etkileşimli geliştirici konsolunu bu TÜR API'lerle kullanmak için hizmet, OAuth 2.0 kullanıcı yetkilendirmesi için bir dış sağlayıcı yapılandırmanıza olanak tanır.

Geliştirici portalının test konsolunda OAuth 2.0 kullanıcı yetkilendirmesini yapılandırmak, geliştiricilere OAuth 2.0 erişim belirteci almak için kullanışlı bir yol sağlar. Daha sonra test konsolundan belirteç, API çağrısıyla arka uça geçirilir. Belirteç doğrulaması, JWT doğrulama ilkesi kullanılarak veya arka uç hizmetinde ayrı olarak yapılandırılmalıdır.

Önkoşullar

Bu makalede, API Management hizmet örneğinizi geliştirici portalının test konsolunda OAuth 2.0 yetkilendirmesini kullanacak şekilde nasıl yapılandırabileceğiniz gösterilmektedir, ancak OAuth 2.0 sağlayıcısını nasıl yapılandırabileceğinizi göstermez.

Henüz bir API Management hizmet örneği oluşturmadıysanız bkz . API Management hizmet örneği oluşturma.

Senaryoya genel bakış

API Management'ta OAuth 2.0 kullanıcı yetkilendirmesini yapılandırmak, yalnızca geliştirici portalının test konsolunu (ve Azure portalındaki test konsolunu) bir istemci olarak yetkilendirme sunucusundan belirteç almasına olanak tanır. Adımlar benzer olsa da her OAuth 2.0 sağlayıcısının yapılandırması farklıdır ve API Management hizmet örneğinizde OAuth 2.0'ı yapılandırmak için kullanılan gerekli bilgi parçaları aynıdır. Bu makalede, OAuth 2.0 sağlayıcısı olarak Microsoft Entra Id kullanan bir örnek gösterilmektedir.

Aşağıdakiler üst düzey yapılandırma adımlarıdır:

1. API'yi temsil etmesi için Microsoft Entra ID'de bir uygulama (arka uç uygulaması) kaydedin.

2. Bu durumda geliştirici portalının test konsolu olan API'yi çağırması gereken bir istemci uygulamasını temsil etmek için Microsoft Entra Id'ye başka bir uygulama (istemci-uygulama) kaydedin.

   Microsoft Entra ID'de, istemci uygulamasının arka uç uygulamasını çağırması için izinler verin.

3. OAuth 2.0 kullanıcı yetkilendirmesini kullanarak bir API'yi çağırmak için geliştirici portalındaki test konsolunu yapılandırın.

4. OAuth 2.0 kullanıcı yetkilendirmesini kullanmak için bir API yapılandırın.

5. Gelen her istek için OAuth 2.0 jetonunu önceden yetkilendirmek üzere bir ilke ekleyin. İlkeyi validate-jwt herhangi bir OAuth 2.0 sağlayıcısı için kullanabilirsiniz.

Bu yapılandırma aşağıdaki OAuth akışını destekler:

1. Geliştirici portalı, istemci-uygulama kimlik bilgilerini kullanarak Microsoft Entra Id'den bir belirteç istemektedir.

2. Doğrulama başarılı olduktan sonra, Microsoft Entra Kimliği erişim/yenileme belirtecini verir.

3. Bir geliştirici (geliştirici portalı kullanıcısı), yetkilendirme üst bilgisi ile bir API çağrısı yapar.

4. Belirteç, API Management'taki ilke Microsoft Entra Id tarafından kullanılarak validate-jwt doğrulanır.

5. Doğrulama sonucuna bağlı olarak, geliştirici yanıtı geliştirici portalında alır.

Yetkilendirme verme türleri

Azure API Management aşağıdaki OAuth 2.0 verme türlerini (akışlar) destekler. Verme türü, bir istemci uygulamasının (bu bağlamda geliştirici portalındaki test konsolu) arka uç API'nize erişim belirteci alma yolunu ifade eder. OAuth 2.0 sağlayıcınıza ve senaryolarınıza bağlı olarak bir veya daha fazla izin türü yapılandırabilirsiniz.

Aşağıda üst düzey bir özet yer alır. Verme türleri hakkında daha fazla bilgi için bkz . OAuth 2.0 Yetkilendirme Çerçevesi ve OAuth verme türleri.

Güvenlik konuları

Verme türünün belirteç oluşturma şeklini, belirtecin kapsamını ve belirtecin nasıl gösterilebileceğini düşünün. Güvenliği aşılmış bir belirteç, kötü amaçlı bir aktör tarafından belirtecin kapsamındaki ek kaynaklara erişmek için kullanılabilir.

Geliştirici portalının test konsolunda OAuth 2.0 kullanıcı yetkilendirmesini yapılandırırken:

• Belirteç kapsamını geliştiricilerin API'leri test etmek için gereken en düşük değerle sınırlayın. Kapsamı test konsoluyla veya etkilenen API'ler ile sınırlayın. Belirteç kapsamını yapılandırma adımları OAuth 2.0 sağlayıcınıza bağlıdır.

  Senaryolarınıza bağlı olarak, arka uç API'lerine erişmek için oluşturduğunuz diğer istemci uygulamaları için daha fazla veya daha az kısıtlayıcı belirteç kapsamları yapılandırabilirsiniz.

• İstemci Kimlik Bilgileri akışını etkinleştirirseniz daha dikkatli olun. Geliştirici portalındaki test konsolu, İstemci Kimlik Bilgileri akışıyla çalışırken kimlik bilgilerini istemez. Erişim belirteci yanlışlıkla geliştiricilere veya geliştirici konsolunun anonim kullanıcılarına açık olabilir.

Önemli bilgileri izleme

Bu öğretici boyunca, daha sonra başvurmak üzere önemli bilgileri kaydetmeniz istenir:

• Arka Uç Uygulaması (istemci) Kimliği: Arka uç API'sini temsil eden uygulamanın GUID'si
• Arka Uç Uygulama Kapsamları: API'ye erişmek için oluşturabileceğiniz bir veya daha fazla kapsam. Kapsam biçimi ( api://<Backend Application (client) ID>/<Scope Name> örneğin, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
• İstemci Uygulaması (istemci) Kimliği: Geliştirici portalını temsil eden uygulamanın GUID'si
• İstemci Uygulama Gizli Anahtarı Değeri: Microsoft Entra Id'de istemci uygulamasıyla etkileşim için gizli dizi görevi görecek GUID

Uygulamaları OAuth sunucusuna kaydetme

OAuth 2.0 sağlayıcınıza iki uygulama kaydetmeniz gerekir: biri korunacak arka uç API'sini, ikincisi de API'yi çağıran istemci uygulamasını temsil eder. Bu durumda geliştirici portalının test konsolu.

OAuth 2.0 sağlayıcısı olarak Microsoft Entra Id kullanan örnek adımlar aşağıda verilmiştır. Uygulama kaydı hakkında ayrıntılı bilgi için bkz . Hızlı Başlangıç: Web API'sini kullanıma açmak için uygulama yapılandırma.

API'yi temsil etmek için Bir uygulamayı Microsoft Entra Id'ye kaydetme

1. Azure portalında Uygulama kayıtları arayın ve seçin.

2. Yeni kayıt öğesini seçin.

3. Bir uygulamayı kaydet sayfası göründüğünde, uygulamanızın kayıt bilgilerini girin:

   • Ad bölümünde, arka uç-uygulama gibi uygulamanın kullanıcılarına görüntülenecek anlamlı bir uygulama adı girin.
   • Desteklenen hesap türleri bölümünde senaryonuza uygun bir seçenek belirleyin.

4. Yeniden Yönlendirme URI'sini boş bırakın. Daha sonra API Management'taki OAuth 2.0 yapılandırmasında oluşturulan bir yeniden yönlendirme URI'sini ekleyeceksiniz.

5. Uygulamayı kaydetmek için Kaydet'i seçin.

6. Uygulamaya Genel Bakış sayfasında Uygulama (istemci) kimliği değerini bulun ve daha sonra için kaydedin.

7. Yan menünün Yönet bölümünde Api'yi kullanıma sunma'yı seçin ve Uygulama Kimliği URI'sini varsayılan değerle ayarlayın. Bu değeri daha sonra için kaydedin.

8. Kapsam ekle düğmesini seçerek Kapsam ekle sayfasını görüntüleyin:

   1. API tarafından desteklenen bir kapsam için bir Kapsam adı girin (örneğin, Dosyalar.Okuma).
   2. Kim onay verebilir? bölümünde Yönetici ve kullanıcılar gibi senaryonuz için bir seçim yapın. Yalnızca daha yüksek ayrıcalıklı senaryolar için Yönetici seçin.
   3. onay görünen adını Yönetici girin ve onay açıklamasını Yönetici.
   4. Etkin kapsam durumunun seçili olduğundan emin olun.

9. Kapsamı oluşturmak için Kapsam ekle düğmesini seçin.

10. API'niz tarafından desteklenen tüm kapsamları eklemek için önceki iki adımı yineleyin.

11. Kapsamlar oluşturulduktan sonra, sonraki adımda kullanmak üzere bunları not edin.

Bir istemci uygulamasını temsil etmek için Microsoft Entra Id'ye başka bir uygulama kaydetme

API'yi çağıran her istemci uygulamasını Microsoft Entra Id'de bir uygulama olarak kaydedin.

1. Azure portalında Uygulama kayıtları arayın ve seçin.

2. Yeni kayıt öğesini seçin.

3. Bir uygulamayı kaydet sayfası göründüğünde, uygulamanızın kayıt bilgilerini girin:

   • Ad bölümünde, uygulamanın kullanıcılarına görüntülenecek istemci-uygulama gibi anlamlı bir uygulama adı girin.
   • Desteklenen hesap türleri bölümünde senaryonuza uygun bir seçenek belirleyin.

4. Yeniden Yönlendirme URI'si bölümünde Web'i seçin ve URL alanını şimdilik boş bırakın.

5. Uygulamayı kaydetmek için Kaydet'i seçin.

6. Uygulamaya Genel Bakış sayfasında Uygulama (istemci) kimliği değerini bulun ve daha sonra için kaydedin.

7. Bu uygulamanın sonraki bir adımda kullanması için bir istemci gizli dizisi oluşturun.

   1. Yan menünün Yönet bölümünde Sertifikalar ve gizli diziler'i seçin.
   2. İstemci gizli dizileri'nin altında + Yeni istemci gizli dizisi'ni seçin.
   3. İstemci gizli dizisi ekle'nin altında bir Açıklama sağlayın ve anahtarın süresinin ne zaman dolması gerektiğini seçin.
   4. Ekle'yi seçin.

Gizli dizi oluşturulduğunda, sonraki adımda kullanılacak anahtar değerini not edin. Portalda gizli diziye yeniden erişemezsiniz.

Microsoft Entra Id'de izinler verme

API'yi ve test konsolunu temsil etmek için iki uygulama kaydettiğinize göre, istemci-uygulamanın arka uç uygulamasını çağırmasına izin vermek için izin verin.

1. Azure portalında Uygulama kayıtları arayın ve seçin.

2. İstemci uygulamanızı seçin. Ardından yan menüde API izinleri'ni seçin.

3. + İzin Ekle'yi seçin.

4. API seçin altında API'lerim'i seçin ve ardından arka uç uygulamanızı bulup seçin.

5. Temsilci İzinleri'ni ve ardından arka uç uygulamanız için uygun izinleri seçin.

6. İzinler ekle'yi seçin.

İsteğe bağlı olarak:

1. İstemci uygulamanızın API izinleri sayfasına gidin.

2. Bu dizindeki tüm kullanıcılar adına onay vermek için Kiracınızın adı> için <yönetici onayı ver'i seçin.

API Management'ta OAuth 2.0 yetkilendirme sunucusu yapılandırma

1. Azure portalında API Management örneğine gidin.

2. Yan menüde Geliştirici portalı altında OAuth 2.0 + OpenID Bağlan'i seçin.

3. OAuth 2.0 sekmesinde + Ekle'yi seçin.

   

4. Ad ve Açıklama alanlarına bir ad ve isteğe bağlı bir açıklama girin.

   Not

   Bu alanlar geçerli API Management hizmeti içindeki OAuth 2.0 yetkilendirme sunucusunu tanımlar. Değerleri OAuth 2.0 sunucusundan gelmez.

5. İstemci kayıt sayfası URL'sini girin; örneğin, https://contoso.com/login. Bu sayfa, OAuth 2.0 sağlayıcınız hesapların kullanıcı yönetimini destekliyorsa kullanıcıların hesaplarını oluşturup yönetebileceği yerdir. Sayfa, kullanılan OAuth 2.0 sağlayıcısına bağlı olarak değişir.

   OAuth 2.0 sağlayıcınızda yapılandırılmış hesapların kullanıcı yönetimi yoksa, buraya şirketinizin URL'si gibi bir yer tutucu URL veya gibi http://localhostbir URL girin.

   

6. Formun sonraki bölümünde Yetkilendirme verme türleri, Yetkilendirme uç noktası URL'si ve Yetkilendirme isteği yöntemi ayarları yer alır.

   • İstenen bir veya daha fazla Yetkilendirme verme türünü seçin. Bu örnekte Yetkilendirme kodu (varsayılan) öğesini seçin. Daha fazla bilgi edinin

   • Yetkilendirme uç noktası URL'sini girin. Uygulama kayıtlarınızdan birinin Uç Noktalar sayfasından uç nokta URL'sini alabilirsiniz. Microsoft Entra Kimliği'ndeki tek kiracılı bir uygulama için bu URL, microsoft Entra kiracınızın kimliğiyle değiştirildiği {aad-tenant} aşağıdaki URL'lerden birine benzer olacaktır.

     v2 uç noktasının kullanılması önerilir; ancak API Management hem v1 hem de v2 uç noktalarını destekler.

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

   • Yetkilendirme isteği yöntemi, yetkilendirme isteğinin OAuth 2.0 sunucusuna nasıl gönderileceğini belirtir. POST'u seçin.

   

7. Belirteç uç noktası URL'si, İstemci kimlik doğrulama yöntemleri, Erişim belirteci gönderme yöntemi ve Varsayılan kapsam'ı belirtin.

   • Belirteç uç noktası URL'sini girin. Microsoft Entra Kimliği'ndeki tek bir kiracı uygulaması için, bu uygulama aşağıdaki URL'lerden birine benzer ve burada {aad-tenant} yerine Microsoft Entra kiracınızın kimliği eklenir. Daha önce seçtiğiniz uç nokta sürümünü (v2 veya v1) kullanın.

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

   • v1 uç noktalarını kullanıyorsanız bir gövde parametresi ekleyin:
     * Ad: kaynak.
     * Değer: arka uç uygulaması Uygulama (istemci) kimliği.

   • v2 uç noktalarını kullanıyorsanız:
     * Varsayılan kapsam alanına oluşturduğunuz arka uç uygulama kapsamını girin.
     * Özelliğin accessTokenAcceptedVersion 2 değerini hem arka uç-uygulama hem de istemci-uygulama kayıtları için uygulama bildiriminde olarak ayarlayın.

   • İstemci kimlik doğrulama yöntemleri ve Erişim belirteci gönderme yöntemi için varsayılan ayarları kabul edin.

8. İstemci kimlik bilgileri bölümünde, istemci uygulamanızın oluşturma ve yapılandırma işlemi sırasında edindiğiniz İstemci Kimliği ve İstemci gizli dizisini girin.

9. İstemci Kimliği ve İstemci gizli dizisi belirtildikten sonra yetkilendirme kodu için Yeniden Yönlendirme URI'si oluşturulur. Bu URI, OAuth 2.0 sunucu yapılandırmanızda yeniden yönlendirme URI'sini yapılandırmak için kullanılır.

   Geliştirici portalında URI soneki şu biçimdedir:

   • /signin-oauth/code/callback/{authServerName} yetkilendirme kodu verme akışı için
   • /signin-oauth/implicit/callback örtük verme akışı için

   

   uygun Yeniden Yönlendirme URI'sini istemci-uygulama kaydınızın Kimlik Doğrulama sayfasına kopyalayın. Uygulama kaydında Authentication>+ Platform>Web'i ekle'yi seçin ve yeniden yönlendirme URI'sini girin.

10. Yetkilendirme verme türleri Kaynak sahibi parolası olarak ayarlanırsa, bu kimlik bilgilerini belirtmek için Kaynak sahibi parolası kimlik bilgileri bölümü kullanılır; aksi takdirde boş bırakabilirsiniz.

11. API Management OAuth 2.0 yetkilendirme sunucusu yapılandırmasını kaydetmek için Oluştur'u seçin.

12. Geliştirici portalını yeniden yayımlayın .

    Önemli

    OAuth 2.0 ile ilgili değişiklikler yaparken, ilgili değişiklikler (örneğin, kapsam değişikliği) aksi takdirde portala yayılamadığından ve daha sonra API'leri denemek için kullanıldığından her değişiklikten sonra geliştirici portalını yeniden yayımladığınızdan emin olun.

API'yi OAuth 2.0 kullanıcı yetkilendirmesini kullanacak şekilde yapılandırma

OAuth 2.0 sunucu yapılandırmasını kaydettikten sonra, bu yapılandırmayı kullanmak için bir API veya API yapılandırın.

1. Soldaki API Management menüsünde API'ler'i seçin.

2. İstediğiniz API'nin adını seçin ve Ayarlar sekmesini seçin. Güvenlik bölümüne kaydırın ve ardından OAuth 2.0'ı seçin.

3. Açılan listeden istediğiniz Yetkilendirme sunucusunu seçin ve Kaydet'i seçin.

   

Geliştirici portalı - OAuth 2.0 kullanıcı yetkilendirmesini test edin

OAuth 2.0 yetkilendirme sunucunuzu yapılandırdıktan ve API'nizi bu sunucuyu kullanacak şekilde yapılandırdıktan sonra geliştirici portalına gidip bir API çağırarak test edebilirsiniz.

1. Azure API Management örneğine Genel Bakış sayfanızdan üstteki menüden Geliştirici portalı'nı seçin.

2. Geliştirici portalındaki API'nin altındaki herhangi bir işleme göz atın.

3. Sizi geliştirici konsoluna getirmek için Deneyin'i seçin.

4. Yetkilendirme bölümünde yeni eklediğiniz yetkilendirme sunucusuna karşılık gelen yeni bir öğeyi not edin.

5. Yetkilendirme açılan listesinden Yetkilendirme kodu'nu seçin.

   

6. İstendikten sonra Microsoft Entra kiracısında oturum açın.

   • Hesapta zaten oturum açtıysanız, sizden istenmeyebilir.

7. Oturum açma başarılı olduktan sonra, Authorization isteğe Microsoft Entra Id'den erişim belirteci içeren bir üst bilgi eklenir. Aşağıda kısaltılmış bir örnek belirteci (Base64 kodlanmış) verilmiştir:

   Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
   

8. Kalan parametreler için istenen değerleri yapılandırın ve GÖNDER'i seçerek API'yi çağırın.

İstekleri önceden yetkilendirmek için JWT doğrulama ilkesi yapılandırma

Şu ana kadar yapılandırmada API Management erişim belirtecini doğrulamaz. Yalnızca yetkilendirme üst bilgisindeki belirteci arka uç API'sine geçirir.

İstekleri önceden yetkilendirmek için, gelen her isteğin erişim belirtecini doğrulamak için bir validate-jwt ilkesi yapılandırın. İsteğin geçerli bir belirteci yoksa API Management bunu engeller.

Aşağıdaki örnek ilke, ilke bölümüne eklendiğinde <inbound> , Yetkilendirme üst bilgisinde sunulan Microsoft Entra Kimliği'nden alınan erişim belirtecinde hedef kitle talebi değerini denetler. Belirteç geçerli değilse bir hata iletisi döndürür. Bu ilkeyi senaryonuza uygun bir ilke kapsamında yapılandırın.

• URL'de openid-config , aad-tenant Microsoft Entra Id'deki kiracı kimliğidir. Bu değeri Azure portalında, örneğin Microsoft Entra kaynağınızın Genel Bakış sayfasında bulabilirsiniz. Gösterilen örnekte tek kiracılı bir Microsoft Entra uygulaması ve v2 yapılandırma uç noktası olduğu varsayılır.
• değerinin claim değeri, Microsoft Entra Id'ye kaydettiğiniz arka uç uygulamasının istemci kimliğidir.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

İlkeleri yapılandırma hakkında bilgi için bkz . İlkeleri ayarlama veya düzenleme. JWT doğrulamalarında daha fazla özelleştirme için validate-jwt başvurusuna bakın. Microsoft Entra hizmeti tarafından sağlanan bir JWT'yi doğrulamak için API Management ilkeyi validate-azure-ad-token de sağlar.

İlgili içerik

• OAuth 2.0 ve API Management kullanma hakkında daha fazla bilgi için bkz . Microsoft Entra ID ile OAuth 2.0 yetkilendirmesini kullanarak Azure API Management'ta web API'si arka ucu koruma.

• Microsoft kimlik platformu ve OAuth 2.0 yetkilendirme kodu akışı hakkında daha fazla bilgi edinin