Aracılığıyla paylaş

Microsoft Entra belirtecini doğrulama

  • Makale

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

Microsoft Entra dışında bir kimlik sağlayıcısı tarafından sağlanan bir JWT'yi doğrulamak için API Management genel ilkeyi validate-jwt 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, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    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 Microsoft Entra</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 Microsoft Entra</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>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Özellikler

Öznitelik Açıklama Zorunlu Varsayılan
tenant-id Kiracı Kimliği veya Microsoft Entra Kimliği kiracısının URL'si veya aşağıdaki iyi bilinen kiracılardan biri:

- organizations veya https://login.microsoftonline.com/organizations - herhangi bir kuruluş dizinindeki (herhangi bir Microsoft Entra dizini) hesaplardan belirteçlere izin vermek için
- common veya https://login.microsoftonline.com/common - herhangi bir kuruluş dizinindeki hesaplardan (herhangi bir Microsoft Entra dizini) ve kişisel Microsoft hesaplarından (örneğin, Skype, XBox) belirteçlere izin vermek için

İlke ifadelerine izin verilir.		 Yes Yok
üst bilgi-adı Belirteci tutan HTTP üst bilgisinin adı. İlke ifadelerine izin verilir. veya biri header-namequery-parameter-name token-value belirtilmelidir. Authorization
query-parameter-name Belirteci tutan sorgu parametresinin adı. İlke ifadelerine izin verilir. veya biri header-namequery-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-namequery-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 Dizgi. 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. Hayır
gerekli talepler Belirtecin geçerli kabul edilmesi için belirteçte bulunması beklenen talep değerlerinin öğelerinin listesini claim içerir. özniteliği olarak allayarlandığında, doğrulamanın match başarılı olması için ilkedeki her talep değeri belirteçte bulunmalıdır. özniteliği olarak anyayarlandığı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
decryption-keys Asimetrik key anahtarla imzalanan bir belirtecin şifresini çözmek için kullanılan alt öğe listesi. Birden çok anahtar varsa, tüm anahtarlar tükenene (bu durumda doğrulama başarısız olana) veya bir anahtar başarılı olana kadar her anahtar denenir.

API Management'a yüklenen bir certificate-id sertifikanın tanımlayıcısına ayarlanmış değere sahip bir öznitelik kullanarak ortak anahtarı belirtin.		 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ı Dizgi. Ç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

anahtar öznitelikleri

Öznitelik Açıklama Zorunlu Varsayılan
sertifika kimliği Asimetrik anahtarla imzalanmış bir belirteci doğrulamak için ortak anahtarı belirtmek için kullanılan API Management'a yüklenen sertifika varlığının tanımlayıcısı. Yes Yok

Kullanım

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. Microsoft kiracı kimliği, herhangi bir kuruluş dizinindeki hesaplardan belirteçlere izin veren iyi bilinen organizations kiracıdır. Konak adı bir ilke ifadesi kullanılarak, istemci uygulama kimliği ise adlandırılmış bir değer 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="organizations" 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 içerik

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