API Management'ta istemci sertifikası kimlik doğrulamasını kullanarak API'lerin güvenliğini sağlama

UYGULANANLAR: Tüm API Management katmanları

API Management, istemci sertifikalarını ve karşılıklı TLS kimlik doğrulamasını kullanarak API'lere, istemciden API Management’a, güvenli erişim olanağı sağlar. Bağlantı istemcisi tarafından sunulan sertifikaları doğrulayabilir ve ilke ifadelerini kullanarak sertifika özelliklerini istenen değerlerle karşılaştırabilirsiniz.

İstemci sertifikalarını veya API Management'ı kullanarak bir API'nin arka uç hizmetine erişimin güvenliğini sağlama hakkında bilgi için bkz. Arka uç hizmetlerinin güvenliğini sağlama.

API yetkilendirmesine kavramsal genel bakış için bkz. Kimlik doğrulaması ve yetkilendirme.

Sertifika seçenekleri

API Management, sertifika doğrulaması için, API Management örneğinizde yönetilen sertifikaları denetleyebilir. İstemci sertifikalarını yönetmek için API Management kullanmayı seçerseniz, aşağıdaki seçeneklere sahip olursunuz:

• Azure Key Vault'ta yönetilen bir sertifikaya başvurma
• Sertifika dosyasını doğrudan API Management’a ekleme

Not

Şu anda bu senaryo için çalışma alanları anahtar kasası entegrasyonuna sahip değildir.

Yaklaşım API Management güvenliğini iyileştirmeye yardımcı olduğundan anahtar kasası sertifikalarını kullanmanızı öneririz:

• Anahtar kasalarında depolanan sertifikalar hizmetler arasında yeniden kullanılabilir
• Anahtar kasalarında depolanan sertifikalara ayrıntılı erişim ilkeleri uygulayabilirsiniz
• Anahtar kasasında güncelleştirilen sertifikalar API Management'ta otomatik olarak döndürülür. Anahtar kasasında güncelleme yapıldıktan sonra, API Yönetimi'ndeki bir sertifika 4 saat içinde güncellenir. Ayrıca Azure portalını veya yönetim REST API'sini kullanarak sertifikayı el ile yenileyebilirsiniz.

Önkoşullar

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

• Azure anahtar kasasında yönetim için sertifikaya ve parolaya erişmeniz veya API Management hizmetine yüklemeniz gerekir. Sertifika CER veya PFX biçiminde olmalıdır. Otomatik olarak imzalanan sertifikalara izin verilir.

  Otomatik olarak imzalanan bir sertifika kullanıyorsanız, API Management örneğinize güvenilen kök ve ara CA sertifikalarını da yükleyin.

  Not

  Sertifika doğrulaması için CA sertifikaları Tüketim katmanında desteklenmez.

Anahtar kasası tümleştirmesi için önkoşullar

• Henüz bir anahtar kasanız yoksa bir tane oluşturun. Anahtar kasası oluşturma hakkında bilgi için bkz . Hızlı Başlangıç: Azure portalını kullanarak anahtar kasası oluşturma.

• API Management'ta sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği etkinleştirin.

Anahtar kasasına erişimi yapılandırma

1. Azure portalında anahtar kasanıza gidin.
2. Sol menüde Ayarlar>Erişim yapılandırması'nı seçin. Yapılandırılan İzin modelini not edin.
3. İzin modeline bağlı olarak API Management yönetilen kimliği için ya bir anahtar kasası erişim ilkesini ya da Azure RBAC erişimini yapılandırın.

Anahtar kasası erişim ilkesi eklemek için:

1. Sol menüde Erişim ilkeleri'ni seçin.
2. Erişim ilkeleri sayfasında + Oluştur'u seçin.
3. İzinler sekmesindeki Gizli izinler altında Getir ve Listele'yi ve ardından İleri'yi seçin.
4. Sorumlu sekmesinde, yönetilen kimliğinizin kaynak adını arayın ve İleri'yi seçin. Sistem tarafından atanan bir kimlik kullanıyorsanız, asıl kimlik API Yönetim örneğinizin adıdır.
5. İleri'yi yeniden seçin. Gözden Geçir + oluştur sekmesinde Oluştur'u seçin.

Anahtar kasasında sertifika oluşturmak veya sertifikayı anahtar kasasına aktarmak için bkz . Hızlı Başlangıç: Azure portalını kullanarak Azure Key Vault'tan sertifika ayarlama ve alma.

Key Vault güvenlik duvarı gereksinimleri

Anahtar kasanızda Key Vault firewall etkinleştirildiyse şu gereksinimleri karşılamanız gerekir:

• API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanarak anahtar kasasına erişim sağlamanız gerekir. API Management'tan erişim için kullanıcı tarafından atanan bir kimlik kullanamazsınız.

• Key Vault güvenlik duvarında Güvenilen Microsoft Hizmetlerinin bu güvenlik duvarını atlamasına izin ver seçeneğini etkinleştirin:

  1. Anahtar kasanızda Ayarlar>Ağ'ı seçin.
  2. Güvenlik duvarları ve sanal ağlar'ın altında Belirli sanal ağlardan ve IP adreslerinden genel erişime izin ver'i seçin.
  3. Özel Durum'un altında Güvenilen Microsoft hizmetlerinin bu güvenlik duvarını atlamasına izin ver'i seçin.

  API Yönetimi, kontrol düzlemi seçenekleri için anahtar kasasına erişmek amacıyla güvenilir hizmet bağlantısını destekler.

• Yerel istemci IP adresinizin anahtar kasasına geçici olarak erişmesine izin verildiğinden emin olun. Azure API Management'a eklemek için bir sertifika veya gizli dizi seçmelisiniz. Daha fazla bilgi için bkz . Azure Key Vault ağ ayarlarını yapılandırma.

  Yapılandırmayı tamamladıktan sonra, anahtar kasası güvenlik duvarında istemci adresinizi engelleyebilirsiniz.

Sanal ağ gereksinimleri

API Management örneği bir sanal ağda dağıtıldıysa, aşağıdaki ağ ayarlarını da yapılandırın:

• API Management alt ağındaki Key Vault'a bir hizmet uç noktasını etkinleştirin.
• AzureKeyVault ve AzureActiveDirectoryhizmet etiketlerine giden trafiğe izin vermek için bir ağ güvenlik grubu (NSG) kuralı yapılandırın.

Daha fazla bilgi için bkz . Sanal ağda API Management'ı ayarlarken ağ yapılandırması.

Anahtar kasasına sertifika ekleyin

Bkz . Anahtar kasası tümleştirmesi için önkoşullar.

Önemli

API Management örneğinize bir anahtar kasası sertifikası eklemek için anahtar kasasından sırları listeleme izniniz olmalıdır.

Dikkat

API Management'ta anahtar kasası sertifikası kullanırken, anahtar kasasına erişmek için kullanılan sertifikayı, anahtar kasasını veya yönetilen kimliği silmemeye dikkat edin.

API Management'a anahtar kasası sertifikası eklemek için:

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

2. Güvenlik bölümünde Sertifikalar'ı seçin.

3. Sertifikalar'ı ve ardından + Ekle'yi seçin.

4. Kimlik alanına bir ad girin.

5. Sertifika'da Anahtar kasası'na tıklayın.

6. Anahtar kasası sertifikasının tanımlayıcısını girin veya bir anahtar kasasından sertifika seçmek için Seç'i seçin.

   Önemli

   Kendiniz bir anahtar kasası sertifika tanımlayıcısı girerseniz sürüm bilgisi olmadığından emin olun. Aksi takdirde sertifika, anahtar kasasında yapılan bir güncelleştirmeden sonra API Management'ta otomatik olarak döndürülmeyecektir.

7. İstemci kimliği'nde sistem tarafından atanan bir kimliği veya mevcut kullanıcı tarafından atanan yönetilen kimliği seçin. Daha fazla bilgi için bkz. Azure API Management'ta yönetilen kimlikleri kullanma.

   Not

   Kimliğin anahtar kasasından sertifika alma ve listeleme izinlerine sahip olması gerekir. Anahtar kasasına erişimi henüz yapılandırmadıysanız API Management, kimliği gerekli izinlerle otomatik olarak yapılandırabilmesi için sizi uyarır.

8. Ekle'yi seçin.

   

9. Kaydet'i seçin.

Bir sertifika yükleyin

API Management'a bir istemci sertifikası yüklemek için:

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

2. Güvenlik bölümünde Sertifikalar'ı seçin.

3. Sertifikalar'ı ve ardından + Ekle'yi seçin.

4. Kimlik alanına bir ad girin.

5. "Sertifika"da Özel'i seçin.

6. Sertifika .pfx dosyasını seçmek için göz atın ve parolasını girin.

7. Ekle'yi seçin.

   

8. Kaydet'i seçin.

Not

Sertifikayı yalnızca API Management ile istemcinin kimliğini doğrulamak için kullanmak istiyorsanız, cer dosyasını karşıya yükleyebilirsiniz.

API Management örneğinin istemci sertifikalarını almasını ve doğrulamasını etkinleştirme

Geliştirici, Temel, Standart veya Premium katmanı

Geliştirici, Temel, Standart veya Premium katmanlarında HTTP/2 üzerinden istemci sertifikalarını almak ve doğrulamak için İstemci sertifikası anlaşması'nı etkinleştirmeniz gerekir.

1. Dağıtım + altyapı'yı ve ardından Özel etki alanları'nı seçin.

2. Ağ geçidi host adını seçin.

3. Ağ Geçidi sayfasında İstemci sertifikasını müzakere et ve ardından Güncelleştir seçin.

   

Tüketim, Temel v2, Standart v2 veya Premium v2 katmanı

Tüketim, Temel v2, Standart v2 veya Premium v2 katmanında istemci sertifikalarını almak ve doğrulamak için İstemci sertifikası iste'yi etkinleştirmeniz gerekir.

1. Dağıtım + altyapı'yı ve ardından Özel etki alanları'nı seçin.

2. İstemci sertifikaları'nın altında İstemci sertifikası iste'yi etkinleştirin.

   

İstemci sertifikalarını doğrulama ilkesi

API Management örneğinizde barındırılan API'lere erişmek için kullanılan bir istemci sertifikasının bir veya daha fazla özniteliğini doğrulamak için validate-client-certificate ilkesini kullanın.

sertifika veren, konu, parmak izi, sertifikanın çevrimiçi iptal listesinde doğrulanıp doğrulanmadığını ve diğer öznitelikleri doğrulamak için ilkeyi yapılandırın.

Bağlam değişkenleriyle sertifika doğrulama

İstemci sertifikalarını denetlemek için değişkeniyle context ilke ifadeleri de oluşturabilirsiniz. Aşağıdaki bölümlerdeki örnekler, context.Request.Certificate özelliğini ve diğer context özelliklerini kullanan ifadeleri gösterir.

Not

Api Management ağ geçidi uç noktası Application Gateway aracılığıyla kullanıma sunulduğunda karşılıklı sertifika kimlik doğrulaması düzgün çalışmayabilir. Application Gateway, katman 7 yük dengeleyici olarak çalışır ve arka uç API Management hizmetiyle ayrı bir TLS bağlantısı kurar. İstemci tarafından ilk HTTP isteğine eklenen sertifika APIM'ye iletilmez.

Geçici bir çözüm olarak, sunucu değişkenleri seçeneğini kullanarak sertifikayı iletebilirsiniz. Daha fazla bilgi için bkz. Karşılıklı Kimlik Doğrulama Sunucusu Değişkenleri.

Önemli

• Mayıs 2021'den itibaren, API Management örneğinin context.Request.Certificate özelliği True olarak ayarlandığında hostnameConfiguration özelliği yalnızca sertifikayı istemektedir. Varsayılan olarak False negotiateClientCertificate olarak ayarlanır.
• İstemcinizde TLS yeniden anlaşması devre dışı bırakılırsa, özelliğini kullanarak context.Request.Certificate sertifika isteğinde bulunurken TLS hataları görebilirsiniz. Hatalar görünürse, istemcide TLS yeniden anlaşma ayarlarını etkinleştirin.
• Sertifika yeniden anlaşması API Management v2 katmanlarında desteklenmez.

Düzenleyiciyi ve konuyu kontrol etme

Aşağıdaki ilkeler, bir istemci sertifikasının verenini ve konusunu denetlemek için yapılandırılabilir:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Not

Sertifika iptal listesini denetlemeyi devre dışı bırakmak için yerine context.Request.Certificate.VerifyNoRevocation()kullanıncontext.Request.Certificate.Verify().

İstemci sertifikası kendinden imzalıysa, ve context.Request.Certificate.Verify()'nin çalışması için kök (veya ara) CA sertifikalarının API Management'a context.Request.Certificate.VerifyNoRevocation().

Parmak izini denetleme

İstemci sertifikasının parmak izini denetlemek için aşağıdaki ilkeler yapılandırılabilir:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Not

Sertifika iptal listesini denetlemeyi devre dışı bırakmak için yerine context.Request.Certificate.VerifyNoRevocation()kullanıncontext.Request.Certificate.Verify().

İstemci sertifikası kendinden imzalıysa, ve context.Request.Certificate.Verify()'nin çalışması için kök (veya ara) CA sertifikalarının API Management'a context.Request.Certificate.VerifyNoRevocation().

API Management'a yüklenen sertifikalarda parmak izini denetleme

Aşağıdaki örnekte, API Management'a yüklenen sertifikalara karşı istemci sertifikasının parmak izini denetleme işlemi gösterilmektedir:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Not

Sertifika iptal listesini denetlemeyi devre dışı bırakmak için yerine context.Request.Certificate.VerifyNoRevocation()kullanıncontext.Request.Certificate.Verify().

İstemci sertifikası kendinden imzalıysa, ve context.Request.Certificate.Verify()'nin çalışması için kök (veya ara) CA sertifikalarının API Management'a context.Request.Certificate.VerifyNoRevocation().

İpucu

Bu makalede açıklanan istemci sertifikası kilitlenme sorunu çeşitli yollarla kendini gösterebilir. Örneğin, istekler donabilir, istekler zaman aşımına uğradıktan sonra 403 Forbidden durum koduyla sonuçlanabilir veya context.Request.Certificatenull şeklindedir. Bu sorun genellikle içerik uzunluğu yaklaşık 60 KB veya daha büyük olan istekleri etkiler POSTPUT .

Bu sorunun oluşmasını önlemek için, makalede daha önce gösterildiği gibi, Özel etki alanları için istenen ana bilgisayar isimleri için İstemci sertifikası ayarını müzakere et seçeneğini açın. Bu özellik Tüketim katmanında kullanılamaz.

İlgili içerik

• Azure API Management'ta arka uç hizmetlerinin güvenliğini sağlama
• Azure API Management'ta özel CA sertifikası ekleme
• Azure API Management'ta ilkeler