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

Makale
04/05/2024

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ı (yani API Management'ı arka uca) kullanarak API'nin arka uç hizmetine erişimin güvenliğini sağlama hakkında bilgi için bkz . İstemci sertifikası kimlik doğrulamasını kullanarak arka uç hizmetlerinin güvenliğini sağlama.

API yetkilendirmesine kavramsal bir genel bakış için bkz . API Management'ta API'ler için 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

API Management güvenliğini iyileştirmeye yardımcı olduğundan anahtar kasası sertifikalarının kullanılması önerilir:

Anahtar kasalarında depolanan sertifikalar hizmetler arasında yeniden kullanılabilir
Anahtar kasalarında depolanan sertifikalara ayrıntılı erişim ilkeleri uygulanabilir
Anahtar kasasında güncelleştirilen sertifikalar API Management'ta otomatik olarak döndürülür. Anahtar kasasında güncelleştirmeden sonra API Management'taki bir sertifika 4 saat içinde güncelleştirilir. 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 adımları için bkz . Hızlı Başlangıç: Azure portalını kullanarak anahtar kasası oluşturma.

Anahtar kasasına sertifika oluşturmak veya içeri aktarmak için bkz . Hızlı Başlangıç: Azure portalını kullanarak Azure Key Vault'tan sertifika ayarlama ve alma.
API Management örneğinde sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği etkinleştirin.

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

Portalda anahtar kasanıza gidin.
Sol menüde Erişim yapılandırması'nı seçin ve yapılandırılan İzin modelini not edin.
İzin modeline bağlı olarak, API Management yönetilen kimliği için bir anahtar kasası erişim ilkesi veya Azure RBAC erişimi 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 dizi izinleri'nin altında Al ve Listele'yi ve ardından İleri'yi seçin.
4. Sorumlu sekmesinde Sorumluyu seçin, yönetilen kimliğinizin kaynak adını arayın ve İleri'yi seçin. Sistem tarafından atanan bir kimlik kullanıyorsanız, sorumlu API Management örneğinizin adıdır.
5. İleri'yi yeniden seçin. Gözden Geçir + oluştur sekmesinde Oluştur'u seçin.
Azure RBAC erişimini yapılandırmak için:
1. Sol menüde Erişim denetimi (IAM) öğesini seçin.
2. Erişim denetimi (IAM) sayfasında Rol ataması ekle'yi seçin.
3. Rol sekmesinde Key Vault Gizli Dizileri Kullanıcısı'nı seçin.
4. Üyeler sekmesinde Yönetilen kimlik>+ Üye seç'i seçin.
5. Yönetilen kimliği seçin sayfasında, API Management örneğiniz ile ilişkilendirilmiş sistem tarafından atanan yönetilen kimliği veya kullanıcı tarafından atanan yönetilen kimliği seçin ve ardından Seç'i seçin.
6. Gözden geçir + ata'yı seçin.

Key Vault güvenlik duvarı gereksinimleri

Anahtar kasanızda Key Vault güvenlik duvarı etkinleştirildiyse ek gereksinimler şunlardır:

Anahtar kasasına erişmek için API Management örneğinin sistem tarafından atanan yönetilen kimliğini kullanmanız gerekir.
Key Vault güvenlik duvarında Güvenilen Microsoft Hizmetleri'nin bu güvenlik duvarını atlamasına izin ver seçeneğini etkinleştirin.
Azure API Management'a eklemek üzere bir sertifika veya gizli dizi seçerken yerel istemci IP adresinizin anahtar kasasına geçici olarak erişmesine izin verildiğinden emin olun. 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 Azure Key Vault'a hizmet uç noktasını etkinleştirin.
AzureKeyVault ve AzureActiveDirectory hizmet etiketlerine giden trafiğe izin vermek için bir ağ güvenlik grubu (NSG) kuralı yapılandırın.

Ayrıntılar için bkz . Sanal ağda Azure API Management'ı ayarlarken ağ yapılandırması.

Anahtar kasası sertifikası ekleme

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

Önemli

API Management örneğinize bir anahtar kasası sertifikası eklerken, anahtar kasasından gizli dizileri 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:

Azure portalında API Management örneğine gidin.
Güvenlik bölümünde Sertifikalar'ı seçin.
Sertifikalar>+ Ekle'yi seçin.
Kimlik alanına istediğiniz bir ad girin.
Sertifika'da Anahtar kasası'na tıklayın.
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 bilgilerinin 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.
İstemci kimliği'nde sistem tarafından atanan veya mevcut kullanıcı tarafından atanan yönetilen kimliği seçin. API Management hizmetinizde yönetilen kimlikleri eklemeyi veya değiştirmeyi öğrenin.

Not

Kimlik, anahtar kasasından sertifika almak ve listelemek için izinlere ihtiyaç duyar. Anahtar kasasına erişimi henüz yapılandırmadıysanız API Management, kimliği gerekli izinlerle otomatik olarak yapılandırabilmesini ister.
Ekle'yi seçin.
Kaydet'i seçin.

Sertifikayı karşıya yükleyin

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

Azure portalında API Management örneğine gidin.
Güvenlik bölümünde Sertifikalar'ı seçin.
Sertifikalar>+ Ekle'yi seçin.
Kimlik alanına istediğiniz bir ad girin.
Sertifika'da Özel'i seçin.
Sertifika .pfx dosyasını seçmek için göz atın ve parolasını girin.
Ekle'yi seçin.
Kaydet'i seçin.

Not

Sertifikayı yalnızca API Management ile istemcinin kimliğini doğrulamak için kullanmak istiyorsanız, bir 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, Temel v2, Standart, Standart v2 veya Premium katmanlarında HTTP/2 üzerinden istemci sertifikalarını almak ve doğrulamak için, aşağıda gösterildiği gibi Özel etki alanı dikey penceresinde İstemci sertifikası anlaşması ayarını etkinleştirmeniz gerekir.

İstemci sertifikası anlaşması yapma

Tüketim katmanı

Tüketim katmanında istemci sertifikalarını almak ve doğrulamak için, Özel etki alanları dikey penceresinde İstemci sertifikası iste ayarını aşağıda gösterildiği gibi etkinleştirmeniz gerekir.

İstemci sertifikası isteme

İ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, özelliğini ve diğer context özellikleri kullanan context.Request.Certificate 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. Bunun nedeni Application Gateway'in, arka uç API Management hizmetiyle ayrı bir SSL bağlantısı kurarak Katman 7 yük dengeleyici olarak işlev göstermeleridir. Sonuç olarak, istemci tarafından ilk HTTP isteğine eklenen sertifika APIM'ye iletılmaz. Ancak, geçici bir çözüm olarak, sunucu değişkenleri seçeneğini kullanarak sertifikayı iletebilirsiniz. Ayrıntılı yönergeler için Karşılıklı Kimlik Doğrulama Sunucusu Değişkenleri'ne bakın.

Önemli

Mayıs 2021'den itibaren, context.Request.Certificate özellik yalnızca API Management örneğinin hostnameConfiguration özelliği True olarak ayarladığında sertifikayı negotiateClientCertificate 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. Bu durumda, istemcide TLS yeniden anlaşma ayarlarını etkinleştirin.
Sertifika yeniden anlaşması API Management v2 katmanlarında desteklenmez.

Vereni ve konuyu denetleme

Aşağıdaki ilkeler, bir istemci sertifikasının verenini ve konusunu denetlemek üzere 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.Verify()kullanıncontext.Request.Certificate.VerifyNoRevocation(). İstemci sertifikası otomatik olarak imzalanmışsa, kök (veya ara) CA sertifikaları ve çalışması için context.Request.Certificate.VerifyNoRevocation()context.Request.Certificate.Verify() API Management'a yüklenmelidir.

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

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

İpucu

Bu makalede açıklanan istemci sertifikası kilitlenme sorunu çeşitli yollarla kendini gösterebilir; örneğin istekler donuyor, istekler zaman aşımına uğradıktan sonra durum koduyla 403 Forbidden sonuçlanıyor, context.Request.Certificate şöyledir null: . 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, bu belgenin ilk görüntüsünde gösterildiği gibi "Özel etki alanları" dikey penceresinde istenen ana bilgisayar adları için "İstemci sertifikası anlaşması" ayarını açın. Bu özellik Tüketim katmanında kullanılamaz.

Sonraki adımlar

İstemci sertifikası kimlik doğrulamasını kullanarak arka uç hizmetlerinin güvenliğini sağlama
Azure API Management'ta özel CA sertifikası ekleme
API Management'ta ilkeler hakkında bilgi edinin