Microsoft Entra belirtecini doğrulama

Makale
04/05/2024

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-namequery-parameter-nametoken-value` belirtilmelidir.	`Authorization`
query-parameter-name	Belirteci tutan sorgu parametresinin adı. İlke ifadelerine izin verilir.	veya biri `header-namequery-parameter-nametoken-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-namequery-parameter-nametoken-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 kullanabilirsiniz claims .
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 USdenetler. 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>

Kimlik doğrulama ve yetkilendirme

İlkelerle çalışma hakkında daha fazla bilgi için bkz: