مشاركة عبر

التحقق من صحة JWT

  • مقالة

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

validate-jwt يفرض النهج وجود وصلاحية رمز ويب JSON معتمد (JWT) مستخرج من رأس HTTP محدد، مستخرج من معلمة استعلام محددة، أو مطابقة قيمة معينة.

إشعار

للتحقق من صحة JWT التي تم توفيرها بواسطة خدمة Microsoft Entra، توفر APIM أيضا النهج validate-azure-ad-token .

إشعار

تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. لمساعدتك في تكوين هذا النهج، يتيح المدخل محررًا موجهًا يستند إلى النموذج. تعلم كيفية إعداد نُهج APIM أو تعديلها.

نهج السياسة

<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>

سمات

السمة ‏‏الوصف مطلوبة افتراضي
header-name اسم عنوان HTTP الذي يتضمن الرمز المميز. يتم السماح بتعبيرات النهج. يجب تحديد واحد من header-name، أو query-parameter-name، أو token-value. ‏‫غير متوفر‬
query-parameter-name اسم معلمة الاستعلام التي تحمل الرمز المميز. يتم السماح بتعبيرات النهج. يجب تحديد واحد من header-name، أو query-parameter-name، أو token-value. ‏‫غير متوفر‬
token-value يعيد التعبير سلسلة تحتوي على الرمز المميز. يجب عدم إعادة Bearer كجزء من قيمة الرمز المميز. يتم السماح بتعبيرات النهج. يجب تحديد واحد من header-name، أو query-parameter-name، أو token-value. ‏‫غير متوفر‬
failed-validation-httpcode التعليمة البرمجية لحالة HTTP التي تعود إذا لم تنجح عملية التحقق من صحة JWT. يتم السماح بتعبيرات النهج. لا 401
failed-validation-error-message رسالة خطأ لإرجاعها في نص استجابة HTTP إذا لم يجتاز JWT التحقق من الصحة. يجب أن تتضمن هذه الرسالة أي أحرف خاصة تم تخطيها بشكل صحيح. يتم السماح بتعبيرات النهج. لا تعتمد رسالة الخطأ الافتراضية على مشكلة التحقق من الصحة، على سبيل المثال "JWT غير موجود".
require-expiration-time منطقي. تحديد ما إذا كانت مطالبة انتهاء الصلاحية مطلوبة في الرمز المميز. يتم السماح بتعبيرات النهج. لا صحيح
require-scheme اسم نظام الرمز المميز، على سبيل المثال، "Bearer". عند تعيين هذه السمة، سيتأكد النهج من وجود نظام محدد في قيمة عنوان التخويل. يتم السماح بتعبيرات النهج. لا ‏‫غير متاح
require-signed-tokens منطقي. تحديد ما إذا كان الرمز المميز مطلوب توقيعه. يتم السماح بتعبيرات النهج. لا صحيح
clock-skew الفترة الزمنية. تُستخدم لتحديد الحد الأقصى لفارق الوقت المتوقع بين ساعات النظام الخاصة بمصدر الشهادة الخاص بالرمز المميز ومثيل APIM. يتم السماح بتعبيرات النهج. لا 0 ثانية
إخراج اسم الرمز المميز المتغير السلسلة. اسم متغير السياق الذي سيتلقى قيمة الرمز المميز كعنصر من النوع Jwt عند التحقق من صحة الرمز المميز بنجاح. تعبيرات النهج غير مسموح بها. لا ‏‫غير متاح

عناصر

العنصر الوصف مطلوب
openid-config أضف عنصرا واحدا أو أكثر من هذه العناصر لتحديد عنوان URL لنقطة نهاية تكوين OpenID متوافقة يمكن من خلالها الحصول على مفاتيح التوقيع ومصدر الشهادة.

يتم سحب التكوين بما في ذلك مجموعة مفاتيح ويب JSON (JWKS) من نقطة النهاية كل ساعة واحدة وتخزينها مؤقتا. إذا كان الرمز المميز الذي يتم التحقق من صحته يشير إلى مفتاح التحقق من الصحة (باستخدام kid المطالبة) مفقود في التكوين المخزن مؤقتا، أو إذا فشل الاسترداد، تسحب APIM من نقطة النهاية مرة واحدة على الأكثر لكل 5 دقائق. هذه الفواصل الزمنية عرضة للتغيير دون إشعار.

ينبغي أن تكون الاستجابة وفقًا للمواصفات المحددة في عنوان URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

بالنسبة لمعرف Microsoft Entra، استخدم نقطة نهاية بيانات تعريف OpenID الاتصال التي تم تكوينها في تسجيل التطبيق الخاص بك مثل:
- v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- v2 متعدد المستأجرين https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
- مستأجر العميل (معاينة) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

استبدال اسم مستأجر الدليل أو معرفه، على سبيل المثال contoso.onmicrosoft.com، ل {tenant-name}.		 لا
issuer-signing-keys قائمة بمفاتيح الأمان المرمزة ب Base64، في key العناصر الفرعية، المستخدمة للتحقق من صحة الرموز المميزة الموقعة. في حالة وجود مفاتيح أمان متعددة، فسيتم تجريب كل مفتاح حتى يتم استنفادها كلها (في هذه الحالة فشل التحقق من الصحة) أو حتى ينجح واحد منها (مفيدة للتمرير فوق الرمز المميز).

حدد مفتاحا اختياريا باستخدام السمة id لمطابقة kid مطالبة. للتحقق من صحة رمز مميز موقع بمفتاح غير متماثل، حدد المفتاح العام اختياريا باستخدام certificate-id سمة بقيمة معرف الشهادة التي تم تحميلها إلى APIM، أو معامل n RSA والزوج الأسي e لمفتاح التوقيع بتنسيق Base64url المشفرة.		 لا
decryption-keys قائمة بالمفاتيح المشفرة Base64، في key العناصر الفرعية، المستخدمة لفك تشفير الرموز المميزة. في حالة وجود مفاتيح أمان متعددة، فسيتم تجريب كل مفتاح حتى يتم استنفادها جميع المفاتيح (في هذه الحالة فشل التحقق من الصحة) أو حتى ينجح مفتاح منها.

حدد مفتاحا اختياريا باستخدام السمة id لمطابقة kid مطالبة. لفك تشفير رمز مميز مشفر بمفتاح غير متماثل، حدد المفتاح العام اختياريا باستخدام certificate-id سمة بقيمة معرف الشهادة التي تم تحميلها إلى APIM، أو معامل n RSA والزوج الأسي e للمفتاح بتنسيق Base64url المشفرة.		 لا
audiences قائمة بمطالبات الجمهور المقبولة، في audience العناصر الفرعية، التي يمكن أن تكون موجودة على الرمز المميز. في حالة وجود قيم جمهور متعددة، فسيتم تجريب كل قيمة حتى يتم استنفادها كلها (في هذه الحالة فشل التحقق من الصحة) أو حتى تنجح واحدة منها. يجب تحديد جمهور واحد على الأقل. لا
issuers قائمة من الأساسيات المقبولة، في issuer العناصر الفرعية، التي أصدرت الرمز المميز. في حالة وجود قيم المصدر متعددة، فسيتم تجريب كل قيمة حتى يتم استنفادها كلها (في هذه الحالة فشل التحقق من الصحة) أو حتى تنجح واحدة منها. لا
required-claims ومن المتوقع أن تكون قائمة المطالبات، في claim العناصر الفرعية، موجودة على الرمز المميز لكي تعتبر صالحة. عند وجود مطالبات متعددة، يجب أن يتطابق الرمز المميز مع قيم المطالبة وفقا لقيمة السمة match . لا

السمات الرئيسية

السمة ‏‏الوصف مطلوبة افتراضي
المعرف السلسلة. المعرف المستخدم لمطابقة kid المطالبة المقدمة في JWT. لا ‏‫غير متاح
مُعرِّف الشهادة معرف كيان شهادة تم تحميله إلى APIM، يستخدم لتحديد المفتاح العام للتحقق من رمز مميز موقع بمفتاح غير متماثل. لا ‏‫غير متاح
n معامل المفتاح العام المستخدم للتحقق من مصدر رمز مميز موقع بمفتاح غير متماثل. يجب تحديد بقيمة الأس e. تعبيرات النهج غير مسموح بها. لا ‏‫غير متاح
E أس المفتاح العام المستخدم للتحقق من مصدر الرمز المميز الموقع باستخدام مفتاح غير متماثل. يجب تحديد بقيمة المعامل n. تعبيرات النهج غير مسموح بها. لا ‏‫غير متاح

سمات المطالبة

السمة ‏‏الوصف مطلوبة افتراضي
match تحدد السمة match في العنصر claimما إذا كانت كل قيمة مطالبة في النهج يجب أن تكون موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح. القيم المحتملة هي:

- all - يجب أن تكون كل قيمة مطالبة في النهج موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح.

- any - يجب أن تكون قيمة مطالبة واحدة فقط موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح.		 لا all
الفاصل السلسلة. تحديد فاصل (على سبيل المثال، "،") لاستخدامه لاستخراج مجموعة من القيم من مطالبة متعددة القيم. لا ‏‫غير متاح

الاستخدام

ملاحظات الاستخدام

  • يتطلب النهج validate-jwt تضمين المطالبة المسجلة exp في الرمز المميز JWT، ما لم يتم تحديد السمة require-expiration-time وتعيينها إلى false.
  • يدعم النهج خوارزميات التوقيع المتماثلة وغير المتماثلة:
    • متماثل - يتم دعم خوارزميات التشفير التالية: A128CBC-HS256، A192CBC-HS384، A256CBC-HS512.
      • إذا تم استخدامه في النهج، يجب توفير المفتاح مضمنا داخل النهج في نموذج ترميز Base64.
    • غير متماثل - يتم دعم algortithms التشفير التالية: PS256، RS256، RS512.
      • إذا تم استخدامه في النهج، يمكن توفير المفتاح إما عبر نقطة نهاية تكوين OpenID، أو عن طريق توفير معرف شهادة تم تحميلها (بتنسيق PFX) تحتوي على المفتاح العام، أو زوج المعامل الأسي للمفتاح العام.
  • لتكوين النهج مع نقطة نهاية تكوين OpenID واحدة أو أكثر للاستخدام مع بوابة مستضافة ذاتيا، يجب أن تكون عناوين URL الخاصة بتكوين OpenID قابلة للوصول أيضا بواسطة بوابة السحابة.
  • يمكنك استخدام نُهج تقييد الوصول في نطاقات مختلفة لأغراض مختلفة. على سبيل المثال، يمكنك تأمين واجهة برمجة التطبيقات بأكملها باستخدام مصادقة Microsoft Entra عن طريق تطبيق validate-jwt النهج على مستوى واجهة برمجة التطبيقات، أو يمكنك تطبيقه على مستوى عملية واجهة برمجة التطبيقات واستخدامه claims للحصول على تحكم أكثر دقة.
  • عند استخدام عنوان مخصص (header-name)، سيتم تجاهل النظام المطلوب المكون (require-scheme). لاستخدام نظام مطلوب، يجب توفير رموز JWT المميزة في Authorization العنوان.

الأمثلة

التحقق من صحة الرمز المميز البسيط.

<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.

<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

<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

<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>

التحقق من صحة الرمز المميز لمتاجرة عمل-مستهلك في Microsoft Azure Active Directory.

<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>

السماح بالوصول إلى العمليات استنادًا إلى مطالبات الرمز المميز.

يوضح هذا المثال كيفية استخدام النهج validate-jwt لتخويل الوصول إلى العمليات استنادا إلى قيمة مطالبات الرمز المميز.

<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>

المحتوى ذو الصلة

لمزيد من المعلومات حول العمل مع النُهج، راجع: