Titik akhir UserInfo

Artikel
10/30/2024

Sebelum memulai, gunakan pemilih Pilih jenis kebijakan di bagian atas halaman ini untuk memilih jenis kebijakan yang Anda siapkan. Azure Active Directory B2C menawarkan dua metode untuk menentukan cara pengguna berinteraksi dengan aplikasi Anda: melalui alur pengguna yang telah ditentukan sebelumnya atau melalui kebijakan kustom yang sepenuhnya dapat dikonfigurasi. Langkah yang diperlukan dalam artikel ini berbeda untuk setiap metode.

Titik akhir UserInfo adalah bagian dari spesifikasi standar OpenID Connect (OIDC) dan dirancang untuk mengembalikan klaim tentang pengguna yang diautentikasi. Titik akhir UserInfo ditentukan dalam kebijakan pihak yang mengandalkan menggunakan elemen EndPoint.

Fitur ini tersedia hanya untuk kebijakan kustom. Untuk langkah-langkah penyiapan, pilih Kebijakan kustom dalam pemilih sebelumnya.

Prasyarat

Selesaikan langkah-langkah dalam Memulai dengan kebijakan kustom di Azure Active Directory B2C. Tutorial ini memandu Anda cara memperbarui file kebijakan kustom untuk menggunakan konfigurasi penyewa Azure AD B2C Anda.
Jika Anda belum mendaftarkan aplikasi web, daftarkan dengan menggunakan langkah-langkah dalam mendaftarkan aplikasi web.

Ringkasan titik akhir UserInfo

Info pengguna UserJourney menentukan:

Otorisasi: Titik akhir UserInfo dilindungi dengan token pembawa. Token akses yang dikeluarkan diberikan di header otorisasi ke titik akhir UserInfo. Kebijakan tersebut menentukan profil teknis yang memvalidasi token masuk dan mengekstrak klaim, seperti objectId pengguna. ObjectId pengguna digunakan untuk mengambil klaim yang akan dikembalikan sebagai respons perjalanan titik akhir UserInfo.
Langkah orkestrasi:
- Langkah orkestrasi digunakan untuk mengumpulkan informasi tentang pengguna. Berdasarkan klaim dalam token akses masuk, perjalanan pengguna memanggil profil teknis ID Microsoft Entra untuk mengambil data tentang pengguna, misalnya, membaca pengguna dengan objectId.
- Langkah-langkah orkestrasi opsional - Anda dapat menambahkan lebih banyak langkah orkestrasi, seperti profil teknis REST API untuk mengambil informasi lebih lanjut tentang pengguna.
- Pengeluar Sertifikat UserInfo - Menentukan daftar klaim yang dikembalikan titik akhir UserInfo.

Membuat titik akhir UserInfo

1. Menambahkan profil teknis Pengeluar Sertifikat Token

Buka file TrustFrameworkExtensions.xml.
Jika belum ada, tambahkan elemen ClaimsProvider dan elemen anaknya sebagai elemen pertama di bawah elemen BuildingBlocks.

Tambahkan penyedia klaim berikut:

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

Bagian InputClaims dalam profil teknis UserInfoIssuer menentukan atribut yang ingin Anda kembalikan. Profil teknis UserInfoIssuer dipanggil di akhir pengguna.
Profil teknis UserInfoAuthorization memvalidasi tanda tangan, nama pengeluar sertifikat, dan audiens token, dan mengekstrak klaim dari token inbound. Ubah metadata berikut untuk mencerminkan lingkungan Anda:
1. pengeluar sertifikat - Nilai ini harus identik dengan klaim iss dalam klaim token akses. Token yang dikeluarkan oleh Azure AD B2C menggunakan pengeluar sertifikat dalam format https://yourtenant.b2clogin.com/your-tenant-id/v2.0/. Pelajari selengkapnya tentang kustomisasi token.
2. IdTokenAudience - Nilai ini harus identik dengan klaim aud dalam klaim token akses. Di Azure AD B2C, klaim aud adalah ID dari aplikasi pihak yang mengandalkan. Nilai ini adalah kumpulan dan mendukung beberapa nilai menggunakan pemisah koma.
  
  Dalam token akses berikut, nilai klaim iss adalah https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/. Jika nilai klaim aud adalah 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"
}
```
Elemen OutputClaims dari profil teknis UserInfoAuthorization menentukan atribut yang ingin Anda baca dari token akses. ClaimTypeReferenceId adalah referensi ke jenis klaim. PartnerClaimType opsional adalah nama klaim yang ditentukan dalam token akses.

2. Menambahkan elemen UserJourney

Elemen UserJourney menentukan jalur yang dibutuhkan pengguna saat berinteraksi dengan aplikasi Anda. Tambahkan elemen UserJourneys jika tidak ada dengan UserJourney yang diidentifikasi sebagai 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. Menyertakan titik akhir kebijakan pihak yang mengandalkan

Untuk menyertakan titik akhir UserInfo di aplikasi pihak yang mengandalkan, tambahkan elemen Titik akhir ke file SocialAndLocalAccounts/SignUpOrSignIn.xml.

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

Elemen pihak yang mengandalkan yang sudah selesai adalah sebagai berikut:

<?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. Menggunggah file

Masuk ke portal Azure.
Jika Anda memiliki akses ke beberapa penyewa, pilih ikon Pengaturan di menu atas untuk beralih ke penyewa Azure AD B2C Anda dari menu Direktori + langganan .
Pilih Semua layanan di pojok kiri atas portal Microsoft Azure, lalu cari dan pilih AAD B2C.
Pilih IEF.
Pada halaman Kebijakan kustom, pilih Unggah kebijakan kustom.
Pilih Timpa kebijakan kustom jika sudah ada, lalu cari dan pilih file TrustframeworkExtensions.xml.
Klik Unggah.
Ulangi langkah 5 sampai 7 untuk file pihak yang mengandalkan, seperti SignUpOrSignIn.xml.

Memanggil titik akhir UserInfo

Titik akhir UserInfo menggunakan API token pembawa OAuth2 standar, yang dipanggil menggunakan token akses yang diterima saat mendapatkan token untuk aplikasi Anda. Ini mengembalikan respons JSON yang berisi klaim tentang pengguna. Titik akhir UserInfo dihosting di Azure AD B2C di:

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

Titik akhir konfigurasi /.well-known (dokumen penemuan OpenID Connect) mencantumkan bidang userinfo_endpoint. Anda dapat secara terprogram menemukan titik akhir UserInfo menggunakan titik akhir konfigurasi /.well-known di:

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

Menguji kebijakan

Di bawah Kebijakan kustom, pilih kebijakan yang telah Anda integrasikan dengan titik akhir UserInfo. Misalnya, B2C_1A_SignUpOrSignIn.
Pilih Jalankan sekarang.
Di bawah Pilih aplikasi, pilih aplikasi Anda yang sebelumnya Anda daftarkan. Untuk Pilih url balasan, pilih https://jwt.ms. Untuk informasi selengkapnya, lihat Mendaftarkan aplikasi web di Azure Active Directory B2C.
Mendaftar atau masuk dengan alamat email atau akun sosial.
Salin id_token dalam format yang dikodekan dari situs web https://jwt.ms. Anda dapat menggunakan ini untuk mengirimkan permintaan GET ke titik akhir UserInfo dan mengambil informasi pengguna.
Kirimkan permintaan GET ke titik akhir UserInfo dan ambil informasi pengguna.

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

Respon yang berhasil akan terlihat seperti:

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

Memberikan klaim opsional

Untuk memberikan lebih banyak klaim ke aplikasi Anda, ikuti langkah-langkah berikut:

Tambahkan atribut pengguna dan sesuaikan input pengguna.
Ubah elemen OutputClaims Profil teknis kebijakan pihak yang mengandalkan dengan klaim yang ingin Anda berikan. Gunakan atribut DefaultValue untuk mengatur nilai default. Anda juga dapat mengatur nilai default ke pemecah masalah klaim, seperti {Context:CorrelationId}. Untuk memaksa penggunaan nilai default, atur atribut AlwaysUseDefaultValue ke true. Contoh berikut menambahkan klaim situasi dengan nilai default.
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```

Ubah elemen InputClaims profil teknis UserInfoIssuer dengan klaim yang ingin Anda berikan. Gunakan atribut PartnerClaimType untuk mengubah nama klaim kembali ke aplikasi Anda. Contoh berikut menambahkan klaim situasi dan mengubah nama beberapa klaim.

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

Langkah berikutnya

Anda dapat menemukan contoh kebijakan titik akhir UserInfo di GitHub.

Bagikan melalui