Tentang penyelesai klaim di kebijakan kustom Azure Active Directory B2C

Artikel
01/19/2024

Penyelesai klaim dalam Azure Active Directory B2C (Azure AD B2C) kebijakan kustom memberikan informasi konteks tentang permintaan otorisasi, seperti nama kebijakan, ID korelasi permintaan, bahasa antarmuka pengguna, dan lain-lain.

Untuk menggunakan penyelesai klaim dalam klaim input atau output, Anda menentukan ClaimType string, berdasarkan elemen ClaimsSchema, lalu Anda mengatur DefaultValue pada penyelesai klaim di elemen klaim input atau output. Azure AD B2C membaca nilai penyelesai klaim dan menggunakan nilai itu di profil teknis.

Dalam contoh berikut, tipe klaim correlationId bernama didefinisikan dengan DataType daristring.

<ClaimType Id="correlationId">
  <DisplayName>correlationId</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Request correlation Id</UserHelpText>
</ClaimType>

Di profil teknis, petakan penyelesai klaim ke tipe klaim. Azure AD B2C mengisi nilai penyelesai klaim {Context:CorrelationId} ke klaim dan mengirim klaim ke profil correlationId teknis.

<InputClaim ClaimTypeReferenceId="correlationId" DefaultValue="{Context:CorrelationId}" />

Kultur

Tabel berikut mencantumkan penyelesai klaim dengan informasi tentang bahasa yang digunakan dalam permintaan otorisasi:

Klaim	Deskripsi	Contoh
{Culture:LanguageName}	Kode ISO dua huruf untuk bahasa tersebut.	en
{Culture:LCID}	LCID kode bahasa.	1033
{Culture:RegionName}	Kode ISO dua huruf untuk wilayah tersebut.	US
{Culture:RFC5646}	Kode bahasa RFC5646.	id-ID

Lihat demo Langsung dari penyelesai klaim budaya.

Kebijakan

Tabel berikut mencantumkan penyelesai klaim dengan informasi tentang kebijakan yang digunakan dalam permintaan otorisasi:

Klaim	Deskripsi	Contoh
{Policy:PolicyId}	Nama kebijakan pihak pengandal.	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	ID penyewa dari kebijakan pihak pengandal.	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	ID objek penyewa dari kebijakan pihak pengandal.	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	ID penyewa kerangka kerja kepercayaan.	your-tenant.onmicrosoft.com

Lihat demo Langsung dari penyelesai klaim budaya.

Konteks

Tabel berikut mencantumkan penyelesai klaim kontekstual dari permintaan otorisasi:

Klaim	Deskripsi	Contoh
{Context:BuildNumber}	Versi Kerangka Kerja Pengalaman Identitas (nomor build).	1.0.507.0
{Context:CorrelationId}	ID korelasi.	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	Waktu tanggal dalam UTC.	10/10/2021, pukul 12:00:00
{Context:DeploymentMode}	Mode penyebaran kebijakan.	Produksi
{Context:HostName}	Nama host dari permintaan saat ini.	contoso.b2clogin.com
{Context:IPAddress}	Alamat IP pengguna.	11.111.111.11
{Context:KMSI}	Menunjukkan apakah kotak centang Biarkan saya tetap masuk dipilih.	benar

Lihat demo Langsung dari penyelesai klaim budaya.

Klaim

Bagian ini menjelaskan cara mendapatkan nilai klaim sebagai penyelesai klaim.

Klaim	Deskripsi	Contoh
{Claim:claim type}	Pengidentifikasi jenis klaim telah ditentukan di bagian Skema Klaim dalam file kebijakan atau file kebijakan induk. Misalnya: `{Claim:displayName}`, atau `{Claim:objectId}`.	Nilai tipe klaim.

OpenID Connect

Tabel berikut mencantumkan penyelesai klaim dengan informasi tentang permintaan otorisasi OpenID Connect:

Klaim	Deskripsi	Contoh
{OIDC:AuthenticationContextReferences}	Parameter `acr_values` string kueri.	T/A
{OIDC:ClientId}	Parameter `client_id` string kueri.	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	Parameter `domain_hint` string kueri.	facebook.com
{OIDC:DomainHint}	Parameter `login_hint` string kueri.	someone@contoso.com
{OIDC:MaxAge}	`max_age`.	T/A
{OIDC:Nonce}	Parameter `Nonce` string kueri.	defaultNonce
{OIDC:Kata Sandi}	Mandat kata sandi pemilik sumber daya mengalirkan kata sandi pengguna.	kata sandi1
{OIDC:Prompt}	Parameter `prompt` string kueri.	masuk
{OIDC:RedirectUri}	Parameter `redirect_uri` string kueri.	https://jwt.ms
{OIDC:Resource}	Parameter `resource` string kueri.	T/A
{OIDC:Scope}	Parameter `scope` string kueri.	openid
{OIDC:Username}	Mandat kata sandi pemilik sumber daya mengalirkan kata sandi pengguna.	emily@contoso.com
{OIDC:IdToken}	Parameter `id token` string kueri.	T/A

Lihat demo Langsung dari penyelesai klaim budaya.

Parameter nilai kunci OAuth2

Nama parameter apa pun yang disertakan sebagai bagian dari permintaan OIDC atau OAuth2 dapat dipetakan ke klaim di perjalanan pengguna. Misalnya, permintaan dari aplikasi mungkin menyertakan parameter string kueri dengan nama app_session, loyalty_number, atau string kueri kustom apa pun.

Klaim	Deskripsi	Contoh
[OAUTH-KV:campaignId]	Parameter string kueri.	Hawaii
[OAUTH-KV:app_session]	Parameter string kueri.	A3C5R
[OAUTH-KV:loyalty_number]	Parameter string kueri.	1234
{OAUTH-KV:any custom query string}	Parameter string kueri.	T/A

Parameter nilai kunci SAML

Dalam permintaan autentikasi SAML, nama parameter apa pun yang disertakan dalam permintaan, tetapi tidak spesifik untuk protokol (seperti SAMLRequest) dapat dipetakan ke klaim dalam perjalanan pengguna. Misalnya, permintaan dapat menyertakan parameter kustom seperti username. Ini berlaku untuk permintaan SAML yang Dimulai SP dan IDP.

Klaim	Deskripsi	Contoh
{SAML-KV:username}	String kueri atau parameter isi POST.	username@domain.com
{SAML-KV:loyalty_number}	String kueri atau parameter isi POST.	1234
{SAML-KV:string kueri kustom apa pun}	String kueri atau parameter isi POST.	T/A

Klik SAML

Tabel berikut mencantumkan penyelesai klaim dengan informasi tentang permintaan otorisasi SAML:

Klaim	Deskripsi	Contoh
{SAML:AuthnContextClassReferences}	Nilai `AuthnContextClassRef` elemen, dari permintaan SAML.	guci:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	Atribut `Format`, dari `NameIDPolicy` elemen permintaan SAML.	guci:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	Nilai elemen `Issuer` SAML dari permintaan SAML.	`https://contoso.com`
[SAML:AllowCreate]	Nilai atribut `AllowCreate`, dari `NameIDPolicy` elemen permintaan SAML.	Benar
{SAML:ForceAuthn}	Nilai atribut `ForceAuthN`, dari `AuthnRequest` elemen permintaan SAML.	Benar
{SAML:ProviderName}	Nilai atribut `ProviderName`, dari `AuthnRequest` elemen permintaan SAML.	Contoso.com
[SAML:RelayState]	Parameter `RelayState` string kueri.
{SAML:Subject}	`Subject` dari elemen NameId dari permintaan SAML AuthN.
{SAML:Binding}	Nilai atribut `ProtocolBinding`, dari `AuthnRequest` elemen permintaan SAML.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Lihat demo Langsung dari penyelesai klaim budaya.

IdP OAuth2

Tabel berikut mencantumkan penyelesai klaim penyedia identitas OAuth2:

Klaim	Deskripsi	Contoh
{oauth2:access_token}	Token akses penyedia identitas OAuth2. Atribut `access_token`.	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	Jenis token akses. Atribut `token_type`.	Pembawa
{oauth2:expires_in}	Masa berlaku token akses valid dalam detik. Atribut `expires_in`. Klaim output DataType harus `int` atau `long`.	960000
{oauth2:access_token}	Token refresh penyedia identitas OAuth2. Atribut `refresh_token`.	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

Untuk menggunakan penyelesai klaim penyedia identitas OAuth2, atur atribut PartnerClaimType klaim output ke penyelesai klaim. Contoh berikut menunjukkan cara mendapatkan klaim penyedia identitas eksternal:

<ClaimsProvider>
  <DisplayName>Contoso</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Contoso-OAUTH">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessToken" PartnerClaimType="{oauth2:access_token}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenType" PartnerClaimType="{oauth2:token_type}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenExpiresIn" PartnerClaimType="{oauth2:expires_in}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />
      </OutputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Menggunakan penyelesai klaim

Anda dapat menggunakan penyelesai klaim dengan elemen berikut:

Item	Elemen	Pengaturan
Profil teknis Application Insights	`InputClaim`
Profil teknis Microsoft Entra	`InputClaim`, `OutputClaim`	1, 2
Profil teknis OAuth2	`InputClaim`, `OutputClaim`	1, 2
Profil teknis OpenID Connect	`InputClaim`, `OutputClaim`	1, 2
Profil teknis transformasi klaim	`InputClaim`, `OutputClaim`	1, 2
Profil teknis penyedia RESTful	`InputClaim`	1, 2
Profil teknis penyedia identitas SAML	`OutputClaim`	1, 2
Profil teknis yang Ditegaskan Sendiri	`InputClaim`, `OutputClaim`	1, 2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
Profil teknis RelyingParty	`OutputClaim`	2

Pengaturan:

IncludeClaimResolvingInClaimsHandlingMetadata harus diatur ke true.
Atribut klaim input atau output AlwaysUseDefaultValue harus diatur ke true.

Sampel penyelesai klaim

Profil teknis RESTful

Dalam profil teknis RESTful, Anda mungkin ingin mengirim bahasa pengguna, nama kebijakan, ruang lingkup, dan ID klien. Berdasarkan klaim, REST API dapat menjalankan logika bisnis kustom, dan jika perlu menyampaikan pesan kesalahan yang dilokalkan.

Contoh berikut menunjukkan profil teknis RESTful dengan skenario ini:

<TechnicalProfile Id="REST">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="policyName" DefaultValue="{Policy:PolicyId}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="{OIDC:Scope}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="clientId" DefaultValue="{OIDC:ClientId}" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Dengan menggunakan penyelesai klaim, Anda dapat melakukan pra-populasi nama masuk atau masuk langsung ke penyedia identitas sosial tertentu, seperti Facebook, LinkedIn, atau akun Microsoft. Untuk informasi selengkapnya, lihat Menyiapkan masuk langsung menggunakan Azure Active Directory B2C.

Kustomisasi UI Dinamis

Azure AD B2C memungkinkan Anda meneruskan parameter string kueri ke titik akhir definisi konten HTML Anda untuk menyajikan konten halaman secara dinamis. Misalnya, fitur ini menyediakan kemampuan untuk memodifikasi gambar latar belakang pada halaman pendaftaran atau masuk Azure AD B2C berdasarkan parameter kustom yang Anda lewati dari aplikasi web atau seluler Anda. Untuk informasi selengkapnya, lihat Mengonfigurasi UI secara dinamis dengan menggunakan kebijakan kustom di Azure Active Directory B2C. Anda juga dapat melokalisasi halaman HTML Anda berdasarkan parameter bahasa, atau Anda dapat mengubah konten berdasarkan ID klien.

Contoh berikut meneruskan parameter string kueri yang bernamacampaignId dengan nilai Hawaii, kode bahasa , dan en-USaplikasi yang mewakili ID klien:

<UserJourneyBehaviors>
  <ContentDefinitionParameters>
    <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
    <Parameter Name="language">{Culture:RFC5646}</Parameter>
    <Parameter Name="app">{OIDC:ClientId}</Parameter>
  </ContentDefinitionParameters>
</UserJourneyBehaviors>

Akibatnya, Azure AD B2C mengirimkan parameter di atas ke halaman konten HTML:

/selfAsserted.aspx?campaignId=hawaii&language=en-US&app=0239a9cc-309c-4d41-87f1-31288feb2e82

Definisi konten

Dalam ContentDefinitionLoadUri, Anda dapat mengirim pemecah klaim untuk menarik konten dari tempat yang berbeda, berdasarkan parameter yang digunakan.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Profil teknis Application Insights

Dengan Azure Application Insights dan pemecah klaim, Anda dapat memperoleh wawasan tentang perilaku pengguna. Di profil teknis Application Insights, Anda mengirim klaim input yang tetap ada di Azure Application Insights. Untuk informasi selengkapnya, lihat Melacak perilaku pengguna dalam perjalanan Azure AD B2C dengan menggunakan Application Insights. Contoh berikut mengirimkan ID kebijakan, ID korelasi, bahasa, dan ID klien ke Azure Application Insights.

<TechnicalProfile Id="AzureInsights-Common">
  <DisplayName>Alternate Email</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.Insights.AzureApplicationInsightsProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="PolicyId" PartnerClaimType="{property:Policy}" DefaultValue="{Policy:PolicyId}" />
    <InputClaim ClaimTypeReferenceId="CorrelationId" PartnerClaimType="{property:CorrelationId}" DefaultValue="{Context:CorrelationId}" />
    <InputClaim ClaimTypeReferenceId="language" PartnerClaimType="{property:language}" DefaultValue="{Culture:RFC5646}" />
    <InputClaim ClaimTypeReferenceId="AppId" PartnerClaimType="{property:App}" DefaultValue="{OIDC:ClientId}" />
  </InputClaims>
</TechnicalProfile>

Kebijakan pihak pengandal

Dalam profil teknis kebijakanPihak pengandal, Anda mungkin ingin mengirim ID penyewa, atau ID korelasi ke aplikasi pihak pengandal dalam JWT.

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <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="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
        <OutputClaim ClaimTypeReferenceId="correlationId" AlwaysUseDefaultValue="true" DefaultValue="{Context:CorrelationId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>

Langkah berikutnya

Temukan lebih lanjut sampel penyelesai klaim di repositori GitHub komunitas Azure AD B2C

Tentang penyelesai klaim di kebijakan kustom Azure Active Directory B2C

Kultur

Kebijakan

Konteks

Klaim

OpenID Connect

Parameter nilai kunci OAuth2

Parameter nilai kunci SAML

Klik SAML

IdP OAuth2

Menggunakan penyelesai klaim

Sampel penyelesai klaim

Profil teknis RESTful

Masuk langsung

Kustomisasi UI Dinamis

Definisi konten

Profil teknis Application Insights

Kebijakan pihak pengandal

Langkah berikutnya

Sumber Daya Tambahan: