JWT Doğrulama

Makale
03/18/2024

UYGULANANLAR: Tüm API Management katmanları

İlke, validate-jwt belirtilen bir HTTP üst bilgisinden ayıklanan, belirtilen sorgu parametresinden ayıklanan veya belirli bir değerle eşleşen desteklenen bir JSON web belirtecinin (JWT) varlığını ve geçerliliğini zorlar.

Not

Microsoft Entra hizmeti tarafından sağlanan bir JWT'yi doğrulamak için API Management ilkeyi validate-azure-ad-token de sağlar.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. Portal, bu ilkeyi yapılandırmanıza yardımcı olmak için kılavuzlu, form tabanlı bir düzenleyici sağlar. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İ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>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </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

Öznitelik	Açıklama	Zorunlu	Varsayılan
üst bilgi-adı	Belirteci tutan HTTP üst bilgisinin adı. İlke ifadelerine izin verilir.	veya biri `header-namequery-parameter-nametoken-value` belirtilmelidir.	Yok
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."
süre sonu gerektirme	Boole. Belirteçte bir süre sonu talebi gerekip gerekmediğini belirtir. İlke ifadelerine izin verilir.	Hayır	true
require-scheme	Belirteç düzeninin adı( örneğin, "Taşıyıcı"). Bu öznitelik ayarlandığında, ilke Belirtilen düzenin Yetkilendirme üst bilgisi değerinde mevcut olduğundan emin olur. İlke ifadelerine izin verilir.	Hayır	YOK
imzalı belirteçleri gerektirme	Boole. bir belirtecin imzalanması gerekip gerekmediğini belirtir. İlke ifadelerine izin verilir.	Hayır	true
saat eğme	Timespan. Belirteç verenin sistem saatleri ile API Management örneği arasında beklenen en yüksek zaman farkını belirtmek için kullanın. İlke ifadelerine izin verilir.	Hayır	0 saniye
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
openid-config	İmzalama anahtarlarının ve verenin alınabileceği uyumlu bir OpenID yapılandırma uç noktası URL'si belirtmek için bu öğelerden birini veya daha fazlasını ekleyin. JSON Web Anahtar Kümesi (JWKS) dahil olmak üzere yapılandırma her 1 saatte bir uç noktadan alınır ve önbelleğe alınır. Doğrulanan belirteç, önbelleğe alınmış yapılandırmada eksik olan bir doğrulama anahtarına (talep kullanılarak `kid` ) başvuruda bulunursa veya alma başarısız olursa, API Management uç noktadan 5 dakikada bir en fazla bir kez çeker. Bu aralıklar bildirimde bulunmadan değiştirilebilir. Yanıt, URL'de tanımlanan belirtimlere göre olmalıdır: `https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata`. Microsoft Entra Id için uygulama kaydınızda yapılandırılan OpenID Bağlan meta veri uç noktasını kullanın: - v2 `https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration` - v2 Çok Kiracılı `https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration` - v1 `https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration` - Müşteri kiracısı (önizleme) `https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration` Dizin kiracı adınızı veya kimliğinizi (örneğin `contoso.onmicrosoft.com`, ) `{tenant-name}`yerine yazın.	Hayır
veren-imzalama anahtarları	İmzalı belirteçleri doğrulamak için kullanılan alt öğelerde `key` Base64 ile kodlanmış güvenlik anahtarlarının listesi. Birden çok güvenlik anahtarı varsa, tümü tükenene (bu durumda doğrulama başarısız olana) veya biri başarılı olana (belirteç geçişi için yararlıdır) her anahtar denenir. İsteğe bağlı olarak, bir taleple eşleştirmek için özniteliğini `id` kullanarak bir `kid` anahtar belirtin. Asimetrik anahtarla imzalanmış bir belirteci doğrulamak için isteğe bağlı olarak, API Management'a yüklenen bir `certificate-id` sertifikanın tanımlayıcısı veya Base64url ile kodlanmış biçimde imzalama anahtarının `e` RSA modulus `n` ve üs çifti ile bir öznitelik kullanarak ortak anahtarı belirtin.	Hayır
decryption-keys	Belirteçlerin şifresini çözmek için kullanılan alt öğelerde `key` Base64 ile kodlanmış anahtarların listesi. Birden çok güvenlik 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. İsteğe bağlı olarak, bir taleple eşleştirmek için özniteliğini `id` kullanarak bir `kid` anahtar belirtin. Asimetrik anahtarla şifrelenmiş bir belirtecin şifresini çözmek için isteğe bağlı olarak, API Management'a yüklenen bir `certificate-id` sertifikanın tanımlayıcısı veya Base64url ile kodlanmış biçimde anahtarın `e` RSA modulus `n` ve üs çifti ile bir öznitelik kullanarak ortak anahtarı belirtin.	Hayır
Kitle -lere	Belirteçte mevcut olabilecek, alt öğelerde `audience` kabul edilebilir hedef kitle taleplerinin listesi. Birden çok hedef kitle değeri varsa, her değer tümü tükenene (bu durumda doğrulama başarısız olana) veya biri başarılı olana kadar denenir. En az bir hedef kitle belirtilmelidir.	Hayır
Ihraççılar	Belirteci veren alt öğelerde `issuer` kabul edilebilir sorumluların listesi. Birden çok veren değeri 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.	Hayır
gerekli talepler	Geçerli kabul edilmesi için belirteçte bulunması beklenen alt öğelerdeki `claim` taleplerin listesi. Birden çok talep mevcut olduğunda belirtecin, öznitelik değerine göre talep değerleriyle `match` eşleşmesi gerekir.	Hayır

anahtar öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
id	Dize. JWT'de sunulan talebi eşleştirmek `kid` için kullanılan tanımlayıcı.	Hayır	YOK
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ı.	Hayır	YOK
n	Asimetrik anahtarla imzalanan bir belirtecin verenini doğrulamak için kullanılan ortak anahtarın modulus. üs `e`değeriyle belirtilmelidir. İlke ifadelerine izin verilmez.	Hayır	YOK
e	Asimetrik anahtarla imzalanan bir belirtecin verenini doğrulamak için kullanılan ortak anahtarın üssü. modulus `n`değeriyle belirtilmelidir. İlke ifadelerine izin verilmez.	Hayır	YOK

talep öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
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.	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.	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ı

İ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 algortithm'leri desteklenir: PS256, RS256, RS512.
  - İ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>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</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>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</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>

Kimlik doğrulama ve yetkilendirme

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