JWT Doğrulama

UYGULANANLAR: Tüm API Management katmanları

İlke, validate-jwt bir kimlik sağlayıcısı tarafından sağlanan desteklenen bir JSON web belirtecinin (JWT) varlığını ve geçerliliğini zorlar. JWT, belirtilen bir HTTP üst bilgisinden ayıklanabilir, belirtilen bir sorgu parametresinden ayıklanabilir veya belirli bir değerle eşleştirilebilir.

İlke bildirimi

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Özellikler

Öğeler

anahtar öznitelikleri

talep öznitelikleri

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, çalışma alanı

Kullanım notları

• İlkevalidate-jwt, öznitelik belirtilmediği ve olarak ayarlanmadığı sürece require-expiration-time kayıtlı talebin JWT belirtecine eklenmesini falsegerektirirexp.
• İlke hem simetrik hem de asimetrik imzalama algoritmalarını destekler:
  • Simetrik - Aşağıdaki şifreleme algoritmaları desteklenir: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
    • İlkede kullanılırsa anahtar, Base64 ile kodlanmış biçimde ilke içinde satır içinde sağlanmalıdır.
  • Asimetrik - Aşağıdaki şifreleme algoritmaları desteklenir: PS256, RS256, RS512, ES256.
    • İlkede kullanılırsa, anahtar openID yapılandırma uç noktası aracılığıyla veya ortak anahtarı içeren karşıya yüklenen bir sertifikanın (PFX biçiminde) kimliği veya ortak anahtarın modulus-üstel çifti sağlanarak sağlanabilir.
• İlkeyi şirket içinde barındırılan bir ağ geçidiyle kullanılmak üzere bir veya daha fazla OpenID yapılandırma uç noktasıyla yapılandırmak için OpenID yapılandırma uç noktaları URL'lerine bulut ağ geçidi tarafından da erişilebilir olmalıdır.
• Erişim kısıtlama ilkelerini farklı amaçlarla farklı kapsamlar için kullanabilirsiniz. Örneğin, ilkeyi API düzeyinde uygulayarak validate-jwt 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 .
• Özel üst bilgi ()header-name kullanılırken, yapılandırılan gerekli düzen (require-scheme) yoksayılır. Gerekli bir düzeni kullanmak için üst bilgide Authorization JWT belirteçleri sağlanmalıdır.

Örnekler

Basit belirteç doğrulama

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

RSA sertifikası ile belirteç doğrulama

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Microsoft Entra Id tek kiracı belirteci doğrulaması

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>00001111-aaaa-2222-bbbb-3333cccc4444</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Microsoft Entra Id müşteri kiracı belirteci doğrulaması

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Azure Active Directory B2C belirteci doğrulama

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>11112222-bbbb-3333-cccc-4444dddd5555</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Şifre çözme anahtarını kullanarak belirteç doğrulama

Bu örnekte, şifre çözme anahtarı kullanılarak şifresi çözülen bir belirteci doğrulamak için ilkenin nasıl kullanılacağı validate-jwt gösterilmektedir. Anahtar, ortak anahtarı içeren karşıya yüklenen bir sertifikanın kimliği (PFX biçiminde) kullanılarak belirtilir.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</validate-jwt>

Belirteç taleplerine göre işlemlere erişimi yetkilendirme

Bu örnekte, belirteç talepleri değerine göre işlemlere erişimi yetkilendirmek için ilkenin validate-jwt nasıl kullanılacağı gösterilmektedir.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

İlgili ilkeler

• Kimlik doğrulama ve yetkilendirme

İlgili içerik

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

• Öğretici: API'nizi dönüştürme ve koruma
• İlke deyimlerinin ve ayarlarının tam listesi için ilke başvurusu
• İlke ifadeleri
• İlkeleri ayarlama veya düzenleme
• İlke yapılandırmalarını yeniden kullanma
• İlke kod parçacıkları deposu
• Azure API Management ilke araç seti
• Azure'da Microsoft Copilot kullanarak ilke yazma