تحديد ملف تعريف تقني لتلميح رمز معرف مميز في نهج Microsoft Azure Active Directory B2C المخصص

مقالة
01/11/2024

يسمح Microsoft Azure Active Directory B2C بالاعتماد على تطبيقات الأطراف لإرسال JWT وارد كجزء من طلب مصادقة OAuth2. يمكن إصدار رمز JWT بواسطة تطبيق جهة معتمدة أو موفر هوية، ويمكنه تمرير تلميح حول المستخدم أو طلب التفويض. يتحقق Microsoft Azure Active Directory B2C من صحة التوقيع واسم المُصدر وجمهور الرمز المميز ويستخرج المطالبة من الرمز المميز الوارد.

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

يمكنك استخدام هذا الحل لإرسال البيانات إلى Microsoft Azure Active Directory B2C مغلف في رمز JWT واحد. الحل Signup with email invitation، حيث يمكن لمسؤول النظام لديك إرسال دعوة موقعة إلى المستخدمين، على id_token_hint. يمكن فقط للمستخدمين الذين لديهم حق الوصول إلى دعوة البريد الإلكتروني إنشاء الحساب في الدليل.

نهج توقيع الرمز

باستخدام id_token_hint، يؤلف مُصدر الرمز المميز (تطبيق جهة معتمدة أو موفر هوية) الرمز المميز، ثم يوقعه باستخدام مفتاح توقيع لإثبات أن الرمز المميز يأتي من مصدر موثوق. يمكن أن يكون مفتاح التوقيع متماثلاً أو غير متماثل. يستخدم التشفير المتماثل أو تشفير المفتاح الخاص سراً مشتركاً للتوقيع والتحقق من صحة التوقيع. التشفير غير المتماثل، أو تشفير المفتاح العام، هو نظام تشفير يستخدم مفتاحاً خاصاً ومفتاحاً عاماً. المفتاح الخاص معروف فقط لمُصدر الرمز المميز ويتم استخدامه لتوقيع الرمز المميز. تتم مشاركة المفتاح العام مع نهج Microsoft Azure Active Directory B2C للتحقق من صحة توقيع الرمز المميز.

تنسيق الرمز

يجب أن يكون id_token_hint رمز JWT صالحاً. يسرد الجدول التالي المطالبات الإلزامية. المطالبات الإضافية اختيارية.

الاسم	المطلب	قيمة المثال	‏‏الوصف
الجمهور	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	تحديد المستلم المقصود للرمز المميز. الجمهور عبارة عن سلسلة عشوائية يتم تحديدها بواسطة مُصدر الرمز المميز. يتحقق Microsoft Azure Active Directory B2C من صحة هذه القيمة، ويرفض الرمز المميز إذا لم يكن متطابقاً.
مصدر الشهادة	`iss`	`https://localhost`	يحدد خدمة رمز الأمان (مُصدر الرمز المميز). المُصدر هو URI تعسفي محدد بواسطة مُصدر الرمز المميز. يتحقق Microsoft Azure Active Directory B2C من صحة هذه القيمة، ويرفض الرمز المميز إذا لم يكن متطابقاً.
تاريخ انتهاء الصلاحية	`exp`	`1600087315`	الوقت الذي يصبح فيه الرمز المميز غير صالح، ويتم تمثيله في وقت الحقبة. يتحقق Microsoft Azure Active Directory B2C من صحة هذه القيمة، ويرفض الرمز المميز إذا انتهت صلاحية الرمز المميز.
ليس قبل	`nbf`	`1599482515`	الوقت الذي يصبح فيه الرمز المميز صالحاً، ويتم تمثيله في وقت الحقبة. عادةً ما يكون هذا الوقت هو نفس وقت إصدار الرمز المميز. يتحقق Microsoft Azure Active Directory B2C من صحة هذه القيمة، ويرفض الرمز المميز إذا كان عمر الرمز المميز غير صالح.

الرمز المميز التالي هو مثال على رمز مميز صالح للمعرف:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

بروتوكول

يجب تعيين سمة اسم عنصر البروتوكول على None. على سبيل المثال، بروتوكول ملف التعريف الفني IdTokenHint_ExtractClaims هو None:

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

يتم استدعاء ملف التعريف الفني من خطوة تزامن بنوع GetClaims.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

مطالبات الإخراج

يحتوي عنصر OutputClaims على قائمة بالمطالبات التي سيتم استخراجها من رمز JWT المميز. قد تحتاج إلى تعيين اسم المطالبة المحددة في سياستك إلى الاسم المحدد في رمز JWT المميز. يمكنك أيضاً تضمين المطالبات التي لم يتم إرجاعها بواسطة رمز JWT المميز، طالما قمت بتعيين السمة DefaultValue.

بيانات التعريف

بيانات التعريف التالية ذات صلة عند استخدام المفتاح المتماثل.

السمة	المطلوب	‏‏الوصف
المُصدر	‏‏نعم‬	يحدد خدمة رمز الأمان (مُصدر الرمز المميز). يجب أن تكون هذه القيمة مطابقة للمطالبة `iss` داخل مطالبة رمز JWT المميز.
IdTokenAudience	‏‏نعم‬	تحديد المستلم المقصود للرمز المميز. يجب أن تكون مطابقة لمطالبة `aud` ضمن مطالبة رمز JWT المميز.

بيانات التعريف التالية ذات صلة عند استخدام مفتاح غير متماثل.

السمة	المطلوب	‏‏الوصف
METADATA	‏‏نعم‬	عنوان URL يشير إلى مستند تكوين مُصدر الرمز المميز، والذي يُعرف أيضاً باسم نقطة نهاية تكوين OpenID المعروفة.
المُصدر	لا	يحدد خدمة رمز الأمان (مُصدر الرمز المميز). يمكن استخدام هذه القيمة للكتابة فوق القيمة المكونة في بيانات التعريف، ويجب أن تكون مطابقة لمطالبة `iss` داخل مطالبة رمز JWT المميز.
IdTokenAudience	لا	تحديد المستلم المقصود للرمز المميز. يجب أن تكون مطابقة لمطالبة `aud` ضمن مطالبة رمز JWT المميز.

هام

يجب أن تتوافق نقاط النهاية الخاصة بك مع متطلبات أمان Microsoft Azure AD B2C. أُوقِف العمل بإصدارات وأصفار TLS الأقدم. لمزيد من المعلومات، راجع متطلبات مجموعة TLS والتشفير.

مفاتيح تشفير

عند استخدام مفتاح متماثل، فإن عنصر CryptographicKeys يحتوي على السمة التالية:

السمة	المطلوب	‏‏الوصف
client_secret	‏‏نعم‬	مفتاح التشفير المستخدم للتحقق من صحة توقيع رمز JWT.

الدلائل الإرشادية

إصدار رمز مميز بمفاتيح متماثلة

الخطوة 1: إنشاء مفتاح مشترك

قم بإنشاء مفتاح يمكن استخدامه لتوقيع الرمز المميز. على سبيل المثال، استخدم رمز PowerShell التالي لإنشاء مفتاح.

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

ينشئ هذا الرمز سلسلة سرية مثل VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

الخطوة 2: إضافة مفتاح التوقيع إلى Azure AD B2C

يجب إنشاء نفس المفتاح الذي يستخدمه مُصدر الرمز المميز في مفاتيح نهج Microsoft Azure Active Directory B2C.

سجل الدخول إلى مدخل Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد رمز الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة Directories + subscriptions.
في مدخل Microsoft Azure، ابحث عن Azure AD B2C وحددها.
في صفحة النظرة العامة، ضمن السياسات، حدد إطار عمل تجربة الهوية.
حدد Policy Keys
حدد Manual.
بالنسبة إلى Name، استخدم IdTokenHintKey.
قد تتم إضافة البادئة B2C_1A_ تلقائيًّا.
في مربع Secret، أدخل مفتاح تسجيل الدخول الذي أنشأته سابقاً.
بالنسبة إلى Key usage، استخدم Encryption.
حدد إنشاء.
تأكد من إنشاء المفتاح B2C_1A_IdTokenHintKey.

الخطوة 3: إضافة ملف التعريف الفني لتلميح الرمز المميز للمعرف

يقوم ملف التعريف الفني التالي بالتحقق من صحة الرمز واستخراج المطالبات.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">a489fc44-3cc0-4a78-92f6-e413cd853eae</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

الخطوة 4: إعداد نهجك

أكمل خطوة Configure your policy.

الخطوة 5: إعداد التعليمات البرمجية

نموذج GitHub هو تطبيق ويب ASP.NET وتطبيق وحدة تحكم يقوم بإنشاء رمز مميز للمعرف يتم توقيعه باستخدام مفتاح متماثل.

إصدار رمز مميز بمفاتيح غير متماثلة

باستخدام مفتاح غير متماثل، يتم توقيع الرمز المميز باستخدام شهادات RSA. يستضيف هذا التطبيق نقطة نهاية بيانات تعريف OpenID الاتصال ونقطة نهاية مفاتيح ويب JSON (JWKs) التي يستخدمها Azure AD B2C للتحقق من صحة توقيع الرمز المميز للمعرف.

يجب أن يوفر مُصدر الرمز المميز نقاط النهاية التالية:

/.well-known/openid-configuration - نقطة نهاية تكوين معروفة تحتوي على معلومات ذات صلة حول الرمز المميز، مثل اسم مُصدر الرمز المميز والارتباط بنقطة نهاية JWK.
/.well-known/keys - نقطة نهاية JSON Web Key (JWK) مع المفتاح العام المستخدم لتوقيع المفتاح (مع جزء المفتاح الخاص من الشهادة).

راجع نموذج وحدة تحكم .NET MVC TokenMetadataController.cs .

الخطوة 1: إعداد شهادة موقعة ذاتيا

إذا لم يكن لديك بالفعل شهادة، فيمكنك استخدام شهادة موقعة ذاتياً لهذا الدليل الإرشادي. في نظام التشغيل Windows، يمكنك استخدام الأمر New-SelfSignedCertificate الخاص بـ PowerShell لإنشاء شهادة.

قم بتشغيل أمر PowerShell هذا لإنشاء شهادة موقعة ذاتياً. قم بتعديل الوسيطة -Subject بالشكل المناسب للتطبيق الخاص بك واسم مستأجر Microsoft Azure Active Directory B2C. يمكنك أيضاً ضبط تاريخ -NotAfter لتحديد تاريخ انتهاء صلاحية مختلف للشهادة.

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

الخطوة 2: إضافة ملف التعريف الفني لتلميح رمز المعرف المميز

يقوم ملف التعريف الفني التالي بالتحقق من صحة الرمز واستخراج المطالبات. قم بتغيير عنوان URI لبيانات التعريف إلى نقطة نهاية التكوين المعروفة لجهة إصدار الرمز المميز.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

الخطوة 3: إعداد نهجك

أكمل خطوة Configure your policy.

الخطوة 4: إعداد التعليمات البرمجية

يُنشئ تطبيق ويب ASP.NET نموذج GitHub رموزاً مميزة للمعرف ويستضيف نقاط نهاية بيانات التعريف المطلوبة لاستخدام معلمة "id_token_hint" في Microsoft Azure Active Directory B2C.

تكوين النهج الخاصة بك

بالنسبة لكل من النهجين المتماثل وغير المتماثل، يتم استدعاء ملف التعريف التقني id_token_hint من خطوة تناغم بنوع GetClaims ويحتاج إلى تحديد مطالبات الإدخال لنهج الجهة المعتمدة.

أضف ملف التعريف الفني لـ IdTokenHint_ExtractClaims إلى نهج الامتداد الخاصة بك.

أضف خطوة التنسيق التالية إلى رحلة المستخدم الخاصة بك كعنصر أول.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

في نهج الطرف المعتمد، كرر نفس مطالبات الإدخال التي قمت بتكوينها في ملف التعريف الفني لـ IdTokenHint_ExtractClaims. على سبيل المثال:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

اعتماداً على متطلبات عملك، قد تحتاج إلى إضافة عمليات التحقق من صحة الرمز، على سبيل المثال التحقق من تنسيق عنوان البريد الإلكتروني. للقيام بذلك، أضف خطوات التنسيق التي تستدعي مطالبات ملف التعريف التقني للتحويل. أضف أيضاً ملف التقني المؤكد ذاتياً لتقديم رسالة خطأ.

إنشاء وتوقيع رمز مميز

توضح نماذج GitHub كيفية إنشاء مثل هذا الرمز المميز JWT الذي تم إرساله لاحقاً كمعامل id_token_hint لسلسلة الاستعلام. فيما يلي مثال على طلب ترخيص مع معلمة id_token_hint

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

الخطوات التالية

تحقق من حل التسجيل باستخدام بريد إلكتروني في دعوة في مستودع GitHub في مجتمع Microsoft Azure Active Directory B2C.