نقطة نهاية UserInfo

مقالة
01/11/2024

قبل البدء، استخدم محدد اختيار نوع نهج في أعلى هذه الصفحة لاختيار نوع النهج الذي تقوم بإعداده. يوفر Azure Active Directory B2C طريقتين لتحديد كيفية تفاعل المستخدمين مع تطبيقاتك: من خلال تدفقات محددة مسبقا للمستخدمين أو من خلال سياسات مخصصة قابلة للتكوين بشكل كامل. تختلف الخطوات المطلوبة في هذه المقالة لكل أسلوب.

تُعد نقطة نهاية معلومات المستخدم جزءًا من مواصفات معيار OpenID Connect (OIDC) وهي مصممة لإرجاع المطالبات المتعلقة بالمستخدم المصادق عليه. يتم تعريف نقطة نهاية معلومات المستخدم في نهج طرف الترحيل باستخدام عنصر نقطة النهاية.

هذه الميزة متاحة فقط للسياسات المخصصة. لخطوات الإعداد، حدد نهج مخصص في المحدد السابق.

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

أكمل الخطوات في ابدأ العمل مع النهج المخصص في Active Directory B2C. يرشدك هذا البرنامج التعليمي إلى كيفية تحديث ملفات النهج المخصصة لاستخدام تكوين مستأجر Azure AD B2C.
إذا لم تكن قد سجلت تطبيق ويب، فسجل واحدا باستخدام الخطوات الواردة في تسجيل تطبيق ويب.

نظرة عامة حول نقطة نهاية معلومات المستخدم

تحدد معلومات المستخدم UserJourney:

التخويل: يتم حماية نقطة نهاية معلومات المستخدم بالرمز المميز للحامل. يتم تقديم رمز وصول تم إصداره في رأس التخويل لنقطة نهاية معلومات المستخدم. يحدد النهج ملف التعريف الفني الذي يتحقق من صحة الرمز المميز الوارد ويستخرج المطالبات، مثل معرف الكائن للمستخدم. يتم استخدام معرف الكائن الخاص بالمستخدم لاسترداد المطالبات التي سيتم إرجاعها استجابة لرحلة نقطة نهاية معلومات المستخدم.
خطوة التزامن:
- يتم استخدام خطوة التنسيق لجمع معلومات حول المستخدم. استنادا إلى المطالبات داخل الرمز المميز للوصول الوارد، تستدعي رحلة المستخدم ملف تعريف تقني لمعرف Microsoft Entra لاسترداد البيانات حول المستخدم، على سبيل المثال، قراءة المستخدم بواسطة objectId.
- خطوات تنسيق اختيارية - يمكنك إضافة المزيد من خطوات التنسيق، مثل ملف تعريف واجهة برمجة تطبيقات REST الفني لاسترداد مزيد من المعلومات حول المستخدم.
- مُصدر معلومات المستخدم - يحدد قائمة المطالبات التي ترجعها نقطة نهاية معلومات المستخدم.

إنشاء نقطة نهاية معلومات المستخدم

1. أضف ملف التعريف الفني لمُصدر الرمز المميز

افتح الملف TrustFrameworkExtensions.xml.
إذا لم يكن موجودًا بالفعل، أضف العنصر ClaimsProvider وعناصره التابعة كعنصر أول ضمن العنصر BuildingBlocks.

أضف موفر المطالبات التالي:

<!-- 
<ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Token Issuer</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="UserInfoIssuer">
        <DisplayName>JSON Issuer</DisplayName>
        <Protocol Name="None" />
        <OutputTokenFormat>JSON</OutputTokenFormat>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <!-- The Below claims are what will be returned on the UserInfo Endpoint if in the Claims Bag-->
        <InputClaims>
          <InputClaim ClaimTypeReferenceId="objectId"/>
          <InputClaim ClaimTypeReferenceId="givenName"/>
          <InputClaim ClaimTypeReferenceId="surname"/>
          <InputClaim ClaimTypeReferenceId="displayName"/>
          <InputClaim ClaimTypeReferenceId="signInNames.emailAddress"/>
        </InputClaims>
      </TechnicalProfile>
      <TechnicalProfile Id="UserInfoAuthorization">
        <DisplayName>UserInfo authorization</DisplayName>
        <Protocol Name="None" />
        <InputTokenFormat>JWT</InputTokenFormat>
        <Metadata>
          <!-- Update the Issuer and Audience below -->
          <!-- Audience is optional, Issuer is required-->
          <Item Key="issuer">https://yourtenant.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/</Item>
          <Item Key="audience">[ "00001111-aaaa-2222-bbbb-3333cccc4444", "11112222-bbbb-3333-cccc-4444dddd5555" ]</Item>
          <Item Key="client_assertion_type">urn:ietf:params:oauth:client-assertion-type:jwt-bearer</Item>
        </Metadata>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
          <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email"/>
          <!-- Optional claims to read from the access token. -->
          <!-- <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="given_name"/>
             <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="family_name"/>
             <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name"/> -->
        </OutputClaims>
      </TechnicalProfile>
    </TechnicalProfiles>
  </ClaimsProvider>
<!-- 
</ClaimsProviders> -->

يحدد قسم InputClaims داخل ملف التعريف الفني UserInfoIssuer السمات التي تريد إرجاعها. يتم استدعاء ملف التعريف الفني UserInfoIssuer في نهاية رحلة المستخدم.
يتحقق ملف التعريف الفني UserInfoAuthorization من صحة التوقيع واسم المُصدر وجمهور الرمز المميز ويستخرج المطالبة من الرمز المميز الوارد. قم بتغيير بيانات التعريف التالية لتعكس بيئتك:
1. المُصدر - يجب أن تكون هذه القيمة مطابقة لمطالبة iss ضمن مطالبة الرمز المميز للوصول. وتستخدم الرموز المميزة التي تم إصدارها بواسطة Microsoft Azure Active Directory B2C مُصدرًا بالتنسيق https://yourtenant.b2clogin.com/your-tenant-id/v2.0/. تعرف على المزيد حول تخصيص الرمز المميز.
2. IdTokenAudience - يجب أن يكون مطابقًا لمطالبة aud داخل مطالبة الرمز المميز للوصول. في Microsoft Azure Active Directory B2C، تكون المطالبة aud هي معرف تطبيق طرف الترحيل. هذه القيمة هي مجموعة وتدعم قيمًا متعددة باستخدام محدد فاصلة.
  
  في الرمز المميز للوصول التالي، تكون قيمة المطالبة iss هي https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/. قيمة المطالبة aud هي 00001111-aaaa-2222-bbbb-3333cccc4444.
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/",
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1605545868,
  "auth_time": 1605545868,
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
يحدد العنصر OutputClaims لملف التعريف الفني UserInfoAuthorization السمات التي تريد قراءتها من الرمز المميز للوصول. ويمثل ClaimTypeReferenceId مرجعًا لنوع المطالبة. ويكون PartnerClaimType الاختياري هو اسم المطالبة المحدد في الرمز المميز للوصول.

2. إضافة عنصر UserJourney

يعرف عُنصر UserJourney المسار الذي يسلكه المستخدم عند التفاعل مع تطبيقك. أضف عنصر UserJourneys إذا لم يكن موجوداً مع المعرف UserJourney على النحو التالي UserInfoJourney:

<!-- 
<UserJourneys> -->
  <UserJourney Id="UserInfoJourney" DefaultCpimIssuerTechnicalProfileReferenceId="UserInfoIssuer">
    <Authorization>
      <AuthorizationTechnicalProfiles>
        <AuthorizationTechnicalProfile ReferenceId="UserInfoAuthorization" />
      </AuthorizationTechnicalProfiles>
    </Authorization>
    <OrchestrationSteps >
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <Preconditions>
          <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
            <Value>objectId</Value>
            <Action>SkipThisOrchestrationStep</Action>
          </Precondition>
        </Preconditions>
        <ClaimsExchanges UserIdentity="false">
          <ClaimsExchange Id="AADUserReadWithObjectId" TechnicalProfileReferenceId="AAD-UserReadUsingObjectId" />
        </ClaimsExchanges>
      </OrchestrationStep>
      <OrchestrationStep Order="2" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="UserInfoIssuer" />
    </OrchestrationSteps>
  </UserJourney>
<!-- 
</UserJourneys> -->

3. تضمين نقطة النهاية لنهج طرف الترحيل

لتضمين نقطة نهاية معلومات المستخدم في تطبيق طرف الترحيل، أضف عنصر نقطة النهاية إلى الملف SocialAndLocalAccounts/SignUpOrSignIn.xml.

<!--
<RelyingParty> -->
  <Endpoints>
    <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
  </Endpoints>
<!-- 
</RelyingParty> -->

سيكون عنصر طرف الترحيل المكتمل كما يلي:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TrustFrameworkPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06" PolicySchemaVersion="0.3.0.0" TenantId="yourtenant.onmicrosoft.com" PolicyId="B2C_1A_signup_signin" PublicPolicyUri="http://yourtenant.onmicrosoft.com/B2C_1A_signup_signin">
  <BasePolicy>
    <TenantId>yourtenant.onmicrosoft.com</TenantId>
    <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
  </BasePolicy>
  <RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <Endpoints>
      <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
    </Endpoints>
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
</TrustFrameworkPolicy>

4. تحميل الملفات

قم بتسجيل الدخول إلى بوابة Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد أيقونة الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة الدلائل + الاشتراكات .
اختر كل الخدمات في الزاوية العلويةِ اليسرى من مدخل Microsoft Azure، ثم ابحث عن Azure AD B2Cوحدده.
حدد إطار عمل تجربة الهوية.
في صفحة Custom policies، حدد Upload custom policy.
حدد Overwrite the custom policy if it already exists، ثم ابحث عن الملف TrustframeworkExtensions.xml وحدده.
انقر فوق تحميل.
كرر الخطوات من 5 إلى 7 لملف جهة الاعتماد، مثل SignUpOrSignIn.xml.

استدعاء نقطة نهاية معلومات المستخدم

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

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/openid/v2.0/userinfo

تسرد نقطة نهاية التكوين المعروفة جيدًا / (وثيقة اكتشاف OpenID Connect) الحقل userinfo_endpoint. يمكنك اكتشاف نقطة نهاية معلومات المستخدم برمجيًا باستخدام نقطة نهاية التكوين المعروفة / في:

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/v2.0/.well-known/openid-configuration

اختبار النهج

ضمن Custom policies، حدد النهج الذي قمت بدمج نقطة نهاية معلومات المستخدم الخاصة بك معه. على سبيل المثال، B2C_1A_SignUpOrSignIn.
حدد تشغيل الآن.
ضمن Select application، حدد التطبيق الذي قمت بتسجيله مسبقًا. لتحديد عنوان URL للرد، اختر https://jwt.ms. لمزيد من المعلومات، راجع تسجيل تطبيق ويب في Microsoft Azure Active Directory B2C.
قم بالتسجيل أو تسجيل الدخول باستخدام عنوان بريد إلكتروني أو حساب تواصل اجتماعي.
انسخ id_token بتنسيقه المشفر من موقع الويب https://jwt.ms. يمكنك استخدام ذلك لإرسال طلب GET إلى نقطة نهاية معلومات المستخدم واسترداد معلومات المستخدم.
إرسال طلب GET إلى نقطة نهاية معلومات المستخدم واسترداد معلومات المستخدم.

GET /yourtenant.onmicrosoft.com/b2c_1a_signup_signin/openid/v2.0/userinfo
Host: b2cninja.b2clogin.com
Authorization: Bearer <your access token>

قد تبدو الاستجابة الناجحة كما يلي:

{
    "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "givenName": "John",
    "surname": "Smith",
    "displayName": "John Smith",
    "signInNames.emailAddress": "john.s@contoso.com"
}

تقديم مطالبات اختيارية

لتوفير المزيد من المطالبات لتطبيقك، اتبع الخطوات التالية:

أضف سمات المستخدم وخصص مدخلات المستخدم.
تعديل العنصر OutputClaims ملف التعريف الفني نهج طرف الترحيل مع المطالبات التي تريد توفيرها. استخدم السمة DefaultValue لتعيين قيمة افتراضية. يمكنك أيضًا تعيين القيمة الافتراضية إلى محلل مطالبة، مثل {Context:CorrelationId}. لفرض استخدام القيمة الافتراضية، قم بتعيين السمة AlwaysUseDefaultValue إلى true. يضيف المثال التالي مطالبة المدينة بقيمة افتراضية.
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```

يمكنك تعديل العنصر OutputClaims لملف التعريف الفني UserInfoIssuer مع المطالبات التي تريد توفيرها. استخدم السمة PartnerClaimType لتغيير اسم المطالبة التي ترجع إلى تطبيقك. يضيف المثال التالي مطالبة المدينة ويغير اسم بعض المطالبات.

<TechnicalProfile Id="UserInfoIssuer">
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" />
    <InputClaim ClaimTypeReferenceId="city" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="familyName" />
    <InputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
    <InputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
  </InputClaims>
  ...
</TechnicalProfile>

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

يمكنك العثور على مثال على نهج نقطة نهاية معلومات المستخدم على GitHub.

مشاركة عبر