التحقق من صحة الرمز المميز ل Microsoft Entra
ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات
validate-azure-ad-token يفرض النهج وجود وصلاحية رمز ويب JSON المميز (JWT) الذي تم توفيره بواسطة خدمة Microsoft Entra (المعروف سابقا باسم Azure Active Directory) لمجموعة محددة من الأساسيات في الدليل. يمكن استخراج JWT من رأس HTTP أو معلمة استعلام أو قيمة محددة يتم توفيرها باستخدام تعبير نهج أو متغير سياق.
إشعار
للتحقق من صحة JWT الذي تم توفيره من قبل موفر هوية آخر، توفر APIM أيضا النهج العام validate-jwt .
إشعار
تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. تعلم كيفية إعداد نُهج APIM أو تعديلها.
نهج السياسة
<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>
سمات
| السمة | الوصف | مطلوبة | افتراضي |
|---|---|---|---|
| معرِف المستأجر | معرف المستأجر أو عنوان URL لخدمة Microsoft Entra. يتم السماح بتعبيرات النهج. | نعم | غير متوفر |
| header-name | اسم عنوان HTTP الذي يتضمن الرمز المميز. يتم السماح بتعبيرات النهج. | يجب تحديد واحد من header-name، أو query-parameter-name، أو token-value. |
Authorization |
| 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 غير موجود". |
| إخراج اسم الرمز المميز المتغير | السلسلة. اسم متغير السياق الذي سيتلقى قيمة الرمز المميز كعنصر من النوع Jwt عند التحقق من صحة الرمز المميز بنجاح. تعبيرات النهج غير مسموح بها. |
لا | غير متاح |
عناصر
| العنصر | الوصف | مطلوب |
|---|---|---|
| audiences | يحتوي على قائمة بمطالبات الجمهور المقبولة التي يمكن أن تكون موجودة ضمن الرمز المميز. إذا كانت قيم متعددة audience موجودة، فسيتم تجربة كل قيمة حتى يتم استنفاد الكل (في هذه الحالة فشل التحقق من الصحة) أو حتى تنجح واحدة. يتم السماح بتعبيرات النهج. |
لا |
| معرفات التطبيقات الخلفية | يحتوي على قائمة بمعرفات التطبيقات الخلفية المقبولة. هذا مطلوب فقط في الحالات المتقدمة لتكوين الخيارات ويمكن إزالته بشكل عام. تعبيرات النهج غير مسموح بها. | لا |
| معرفات تطبيق العميل | يحتوي على قائمة بمعرفات تطبيق العميل المقبولة. إذا كانت عناصر متعددة application-id موجودة، فسيتم تجربة كل قيمة حتى يتم استنفاد الكل (في هذه الحالة فشل التحقق من الصحة) أو حتى تنجح واحدة. إذا لم يتم توفير معرف تطبيق عميل، يجب تحديد مطالبة واحدة أو أكثر audience . تعبيرات النهج غير مسموح بها. |
لا |
| required-claims | يحتوي على قائمة عناصر claim لقيم المطالبة المتوقع أن تكون موجودة على الرمز المميز ليتم اعتبارها صالحة. عند تعيين السمة match إلى all، يجب أن تكون كل قيمة مطالبة في النهج موجودة في الرمز المميز للتحقق من الصحة للنجاح. عند تعيين السمة match إلى any، يجب أن تكون مطالبة واحدة على الأقل موجودة في الرمز المميز للتحقق من الصحة للنجاح. يتم السماح بتعبيرات النهج. |
لا |
سمات المطالبة
| السمة | الوصف | مطلوبة | افتراضي |
|---|---|---|---|
| الاسم | اسم المطالبة كما هو متوقع أن تظهر في الرمز المميز. يتم السماح بتعبيرات النهج. | نعم | غير متوفر |
| match | تحدد السمة match في العنصر claimما إذا كانت كل قيمة مطالبة في النهج يجب أن تكون موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح. القيم المحتملة هي:- all - يجب أن تكون كل قيمة مطالبة في النهج موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح.- any - يجب أن تكون قيمة مطالبة واحدة فقط موجودة في الرمز المميز للتحقق من الصحة بغرض تحقيق النجاح.يتم السماح بتعبيرات النهج. |
لا | all |
| الفاصل | السلسلة. تحديد فاصل (على سبيل المثال، "،") لاستخدامه لاستخراج مجموعة من القيم من مطالبة متعددة القيم. يتم السماح بتعبيرات النهج. | لا | غير متاح |
الاستخدام
- أقسام النهج:الواردة.
- نطاقات النهج: العمومية، ومساحة العمل، والمنتج، وواجهة برمجة التطبيقات، والتشغيل
- البوابات: الكلاسيكية، الإصدار 2، الاستهلاك، المستضافة ذاتيا
ملاحظات الاستخدام
- يمكنك استخدام نُهج تقييد الوصول في نطاقات مختلفة لأغراض مختلفة. على سبيل المثال، يمكنك تأمين واجهة برمجة التطبيقات بأكملها باستخدام مصادقة Microsoft Entra عن طريق تطبيق
validate-azure-ad-tokenالنهج على مستوى واجهة برمجة التطبيقات، أو يمكنك تطبيقه على مستوى عملية واجهة برمجة التطبيقات واستخدامهclaimsللحصول على تحكم أكثر دقة. - معرف Microsoft Entra للعملاء (معاينة) غير مدعوم.
الأمثلة
التحقق من صحة الرمز المميز البسيط.
النهج التالي هو الحد الأدنى من شكل النهج validate-azure-ad-token . يتوقع أن يتم توفير JWT في العنوان الافتراضي Authorization باستخدام Bearer النظام. في هذا المثال، يتم توفير معرف مستأجر Microsoft Entra ومعرف تطبيق العميل باستخدام القيم المسماة.
<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>
التحقق من صحة الجمهور والمطالبة
يتحقق النهج التالي من أن الجمهور هو اسم المضيف لمثيل APIM وأن المطالبة ctry هي US. يتم توفير اسم المضيف باستخدام تعبير نهج، ويتم توفير معرف مستأجر Microsoft Entra ومعرف تطبيق العميل باستخدام القيم المسماة. يتم توفير JWT الذي تم فك ترميزه في jwt المتغير بعد التحقق من الصحة.
لمزيد من التفاصيل حول المطالبات الاختيارية، اقرأ توفير مطالبات اختيارية لتطبيقك.
<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>
النهج ذات الصلة
المحتوى ذو الصلة
لمزيد من المعلومات حول العمل مع النُهج، راجع: