Microsoft Entra belirtecini doğrulama
UYGULANANLAR: Tüm API Management katmanları
İlke, validate-azure-ad-token
dizindeki belirli bir sorumlu kümesi için Microsoft Entra (eski adı Azure Active Directory) hizmeti tarafından sağlanan bir JSON web belirtecinin (JWT) varlığını ve geçerliliğini zorlar. JWT, belirtilen bir HTTP üst bilgisinden, sorgu parametresinden veya ilke ifadesi veya bağlam değişkeni kullanılarak sağlanan değerden ayıklanabilir.
Not
Api Management, başka bir kimlik sağlayıcısı tarafından sağlanan bir JWT'yi doğrulamak için genel validate-jwt
ilkeyi de sağlar.
Not
İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.
İlke bildirimi
<validate-azure-ad-token
tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
failed-validation-httpcode="HTTP status code to return on failure"
failed-validation-error-message="error message to return on failure"
output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
<client-application-ids>
<application-id>Client application ID from Azure Active Directory</application-id>
<!-- If there are multiple client application IDs, then add additional application-id elements -->
</client-application-ids>
<backend-application-ids>
<application-id>Backend application ID from Azure Active Directory</application-id>
<!-- If there are multiple backend application IDs, then add additional application-id elements -->
</backend-application-ids>
<audiences>
<audience>audience string</audience>
<!-- if there are multiple possible audiences, then add additional audience elements -->
</audiences>
<required-claims>
<claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
<value>claim value as it is expected to appear in the token</value>
<!-- if there is more than one allowed value, then add additional value elements -->
</claim>
<!-- if there are multiple possible allowed values, then add additional value elements -->
</required-claims>
</validate-azure-ad-token>
Özellikler
Öznitelik | Açıklama | Zorunlu | Varsayılan |
---|---|---|---|
tenant-id | Microsoft Entra hizmetinin Kiracı Kimliği veya URL'si. İlke ifadelerine izin verilir. | Yes | Yok |
üst bilgi-adı | Belirteci tutan HTTP üst bilgisinin adı. İlke ifadelerine izin verilir. | veya biri header-name query-parameter-name token-value belirtilmelidir. |
Authorization |
query-parameter-name | Belirteci tutan sorgu parametresinin adı. İlke ifadelerine izin verilir. | veya biri header-name query-parameter-name token-value belirtilmelidir. |
Yok |
belirteç-değer | Belirteci içeren bir dize döndüren ifade. Belirteç değerinin bir parçası olarak dönmemelisiniz Bearer . İlke ifadelerine izin verilir. |
veya biri header-name query-parameter-name token-value belirtilmelidir. |
Yok |
failed-validation-httpcode | JWT doğrulamayı geçmezse döndürülecek HTTP durum kodu. İlke ifadelerine izin verilir. | Hayır | 401 |
failed-validation-error-message | JWT doğrulamayı geçmezse HTTP yanıt gövdesinde döndürülecek hata iletisi. Bu iletide özel karakterlerin düzgün bir şekilde kaçış karakteri olması gerekir. İlke ifadelerine izin verilir. | Hayır | Varsayılan hata iletisi doğrulama sorununa bağlıdır, örneğin "JWT yok." |
output-token-variable-name | Dize. Başarılı belirteç doğrulamasından sonra belirteç değerini türünde Jwt bir nesne olarak alacak bağlam değişkeninin adı. İlke ifadelerine izin verilmez. |
Hayır | YOK |
Öğeler
Öğe | Açıklama | Gerekli |
---|---|---|
Kitle -lere | Belirteçte mevcut olabilecek kabul edilebilir hedef kitle taleplerinin listesini içerir. Birden çok audience değer varsa, tümü tükenene (bu durumda doğrulama başarısız olana) veya biri başarılı olana kadar her değer denenir. İlke ifadelerine izin verilir. |
Hayır |
backend-application-ids | Kabul edilebilir arka uç uygulama kimliklerinin listesini içerir. Bu yalnızca seçeneklerin yapılandırılması için gelişmiş durumlarda gereklidir ve genel olarak kaldırılabilir. İlke ifadelerine izin verilmez. | Hayır |
client-application-ids | Kabul edilebilir istemci uygulaması kimliklerinin listesini içerir. Birden çok application-id öğe varsa, tümü tükenene (bu durumda doğrulama başarısız olana) veya biri başarılı olana kadar her değer denenir. İstemci uygulama kimliği sağlanmadıysa, bir veya daha fazla audience talep belirtilmelidir. İlke ifadelerine izin verilmez. |
Yes |
gerekli talepler | Belirtecin geçerli kabul edilmesi için belirteçte bulunması beklenen talep değerlerinin öğelerinin listesini claim içerir. özniteliği olarak all ayarlandığında, doğrulamanın match başarılı olması için ilkedeki her talep değeri belirteçte bulunmalıdır. özniteliği olarak any ayarlandığında, doğrulamanın match başarılı olması için belirteçte en az bir talep bulunmalıdır. İlke ifadelerine izin verilir. |
Hayır |
talep öznitelikleri
Öznitelik | Açıklama | Zorunlu | Varsayılan |
---|---|---|---|
Adı | Belirtecin içinde gösterilmesi beklenen talebin adı. İlke ifadelerine izin verilir. | Yes | Yok |
match | match öğesindeki özniteliği, doğrulamanın claim başarılı olması için ilkedeki her talep değerinin belirteçte bulunup bulunmayacağını belirtir. Olası değerler şunlardır:- all - doğrulamanın başarılı olması için ilkedeki her talep değerinin belirteçte mevcut olması gerekir.- any - Doğrulamanın başarılı olması için belirteçte en az bir talep değeri bulunmalıdır.İlke ifadelerine izin verilir. |
Hayır | tümü |
Ayırıcı | Dize. Çok değerli bir talepten bir değer kümesi ayıklamak için kullanılacak bir ayırıcı (örneğin, ",") belirtir. İlke ifadelerine izin verilir. | Hayır | YOK |
Kullanım
- İlke bölümleri: gelen
- İlke kapsamları: genel, çalışma alanı, ürün, API, işlem
- Ağ geçitleri: klasik, v2, tüketim, şirket içinde barındırılan
Kullanım notları
- Erişim kısıtlama ilkelerini farklı amaçlarla farklı kapsamlar için kullanabilirsiniz. Örneğin, ilkeyi API düzeyinde uygulayarak
validate-azure-ad-token
Microsoft Entra kimlik doğrulaması ile tüm API'nin güvenliğini sağlayabilir veya API işlem düzeyinde uygulayıp daha ayrıntılı denetim için kullanabilirsinizclaims
. - Müşteriler için Microsoft Entra Id (önizleme) desteklenmez.
Örnekler
Basit belirteç doğrulama
Aşağıdaki ilke, ilkenin en düşük biçimidir validate-azure-ad-token
. JWT'nin şema kullanılarak varsayılan Authorization
üst bilgide sağlanmasını Bearer
bekler. Bu örnekte, Microsoft Entra kiracı kimliği ve istemci uygulama kimliği adlandırılmış değerler kullanılarak sağlanır.
<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
<client-application-ids>
<application-id>{{aad-client-application-id}}</application-id>
</client-application-ids>
</validate-azure-ad-token>
hedef kitlenin ve talebin doğru olduğunu doğrulama
Aşağıdaki ilke, hedef kitlenin API Management örneğinin ana bilgisayar adı olduğunu ve talebin ctry
olduğunu US
denetler. Konak adı bir ilke ifadesi kullanılarak sağlanır ve Microsoft Entra kiracı kimliği ve istemci uygulama kimliği adlandırılmış değerler kullanılarak sağlanır. Kodu çözülen JWT, doğrulamadan jwt
sonra değişkende sağlanır.
İsteğe bağlı talepler hakkında daha fazla bilgi için bkz . Uygulamanıza isteğe bağlı talepler sağlama.
<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" output-token-variable-name="jwt">
<client-application-ids>
<application-id>{{aad-client-application-id}}</application-id>
</client-application-ids>
<audiences>
<audience>@(context.Request.OriginalUrl.Host)</audience>
</audiences>
<required-claims>
<claim name="ctry" match="any">
<value>US</value>
</claim>
</required-claims>
</validate-azure-ad-token>
İlgili ilkeler
İlgili içerik
İlkelerle çalışma hakkında daha fazla bilgi için bkz: