Informazioni sui resolver di attestazioni nei criteri personalizzati in Azure Active Directory B2C

Articolo
01/19/2024

I resolver di attestazioni nei criteri personalizzati di Azure Active Directory B2C (Azure AD B2C) forniscono informazioni di contesto su una richiesta di autorizzazione, ad esempio il nome dei criteri, l'ID di correlazione della richiesta, la lingua dell'interfaccia utente e altro ancora.

Per usare un resolver di attestazioni in un'attestazione di input o output, si definisce un ClaimType di tipo stringa, nell'elemento ClaimsSchema, quindi si imposta DefaultValue sul resolver di attestazioni nell'elemento attestazione di input o output. Azure AD B2C legge il valore del resolver di attestazioni e usa il valore nel profilo tecnico.

Nell'esempio seguente viene definito un tipo di attestazione denominato correlationId con DataTypestring.

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

Nel profilo tecnico, mappare il resolver di attestazioni al tipo di attestazione. Azure AD B2C popola il valore del resolver di attestazioni {Context:CorrelationId} nell'attestazione correlationId e invia l'attestazione al profilo tecnico.

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

Cultura

La tabella seguente elenca i resolver di attestazioni con informazioni sulla lingua usata nella richiesta di autorizzazione:

Attestazione	Descrizione	Esempio
{Culture:LanguageName}	Codice ISO di due lettere per la lingua.	en
{Culture:LCID}	Identificatore LCID del codice della lingua.	1033
{Culture:RegionName}	Codice ISO di due lettere per la regione.	Stati Uniti
{Culture:RFC5646}	Codice RFC5646 della lingua.	en-US

Vedere la demo live dei resolver di attestazioni delle impostazioni cultura.

Criteri

La tabella seguente elenca i resolver di attestazioni con informazioni sui criteri usati nella richiesta di autorizzazione:

Attestazione	Descrizione	Esempio
{Policy:PolicyId}	Nome dei criteri della relying party.	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	ID del tenant dei criteri della relying party.	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	ID oggetto del tenant dei criteri della relying party.	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	ID del tenant del framework attendibilità.	your-tenant.onmicrosoft.com

Vedere la demo live dei resolver di attestazioni dei criteri.

Contesto

La tabella seguente elenca i resolver di attestazioni contestuali della richiesta di autorizzazione:

Attestazione	Descrizione	Esempio
{Context:BuildNumber}	Versione del framework dell'esperienza di gestione delle identità (numero di build).	1.0.507.0
{Context:CorrelationId}	L'ID di correlazione.	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	Data e ora in formato UTC.	10/10/2021 12:00:00 PM
{Context:DeploymentMode}	Modalità di distribuzione dei criteri.	Produzione
{Context:HostName}	Nome host della richiesta corrente.	contoso.b2clogin.com
{Context:IPAddress}	Indirizzo IP utente.	11.111.111.11
{Context:Servizio di gestione delle chiavi I}	Indica se è selezionata la casella di controllo Mantieni l'accesso .	true

Vedere la demo live dei resolver di attestazioni di contesto.

Richieste di rimborso

Questa sezione descrive come ottenere un valore di attestazione come resolver di attestazioni.

Attestazione	Descrizione	Esempio
{Claim:claim type}	Identificatore di un tipo di attestazione già definito nella sezione ClaimsSchema nel file di criteri o nel file di criteri padre. Ad esempio: `{Claim:displayName}`o `{Claim:objectId}`.	Valore del tipo di attestazione.

OpenID Connect

La tabella seguente elenca i resolver di attestazioni con informazioni sulla richiesta di autorizzazione openID Connessione:

Attestazione	Descrizione	Esempio
{OIDC:AuthenticationContextReferences}	Parametro di stringa di query `acr_values`.	N/D
{OIDC:ClientId}	Parametro di stringa di query `client_id`.	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	Parametro di stringa di query `domain_hint`.	facebook.com
{OIDC:LoginHint}	Parametro di stringa di query `login_hint`.	someone@contoso.com
{OIDC:MaxAge}	Il `max_age`.	N/D
{OIDC:Nonce}	Parametro di stringa di query `Nonce`.	defaultNonce
{OIDC:Password}	Password del proprietario della risorsa con la password dell'utente.	password1
{OIDC:Prompt}	Parametro di stringa di query `prompt`.	login
{OIDC:RedirectUri}	Parametro di stringa di query `redirect_uri`.	https://jwt.ms
{OIDC:Resource}	Parametro di stringa di query `resource`.	N/D
{OIDC:Scope}	Parametro di stringa di query `scope`.	openid
{OIDC:Username}	Il nome utente dell'utente del flusso delle credenziali della password del proprietario della risorsa.	emily@contoso.com
{OIDC:IdToken}	Parametro di stringa di query `id token`.	N/D

Vedere la demo live dei resolver di attestazioni OpenID Connessione.

Parametri chiave-valore OAuth2

I nomi di parametro inclusi in una richiesta OIDC o OAuth2 possono essere mappati a un'attestazione nel percorso utente Ad esempio, la richiesta generata dall'applicazione può includere un parametro di stringa di query denominato app_session, loyalty_number o qualsiasi stringa di query personalizzata.

Attestazione	Descrizione	Esempio
{OAUTH-KV:campaignId}	Parametro di stringa di query.	Hawaii
{OAUTH-KV:app_session}	Parametro di stringa di query.	A3C5R
{OAUTH-KV:loyalty_number}	Parametro di stringa di query.	1234
{OAUTH-KV:qualsiasi stringa di query personalizzata}	Parametro di stringa di query.	N/D

Parametri chiave-valore SAML

In una richiesta di autenticazione SAML è possibile eseguire il mapping di qualsiasi nome di parametro incluso nella richiesta, ma non specifico del protocollo ( ad esempio SAMLRequest) a un'attestazione nel percorso utente. Ad esempio, la richiesta può includere un parametro personalizzato, usernamead esempio . Questo vale sia per le richieste SAML avviate da SP che da IDP.

Attestazione	Descrizione	Esempio
{SAML-KV:username}	Stringa di query o parametro del corpo POST.	username@domain.com
{SAML-KV:loyalty_number}	Stringa di query o parametro del corpo POST.	1234
{SAML-KV:any custom query string}	Stringa di query o parametro del corpo POST.	N/D

SAML

La tabella seguente elenca i resolver di attestazioni con informazioni sulla richiesta di autorizzazione SAML:

Attestazione	Descrizione	Esempio
{SAML:AuthnContextClassReferences}	Valore dell'elemento `AuthnContextClassRef` , dalla richiesta SAML.	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	Attributo `Format` , dall'elemento `NameIDPolicy` della richiesta SAML.	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	Valore dell'elemento SAML `Issuer` della richiesta SAML.	`https://contoso.com`
{SAML:AllowCreate}	Valore `AllowCreate` dell'attributo, dall'elemento `NameIDPolicy` della richiesta SAML.	Vero
{SAML:ForceAuthn}	Valore `ForceAuthN` dell'attributo, dall'elemento `AuthnRequest` della richiesta SAML.	Vero
{SAML:ProviderName}	Valore `ProviderName` dell'attributo, dall'elemento `AuthnRequest` della richiesta SAML.	Contoso.com
{SAML:RelayState}	Parametro di stringa di query `RelayState`.
{SAML:Subject}	Oggetto `Subject` dell'elemento NameId della richiesta SAML AuthN.
{SAML:Binding}	Valore `ProtocolBinding` dell'attributo, dall'elemento `AuthnRequest` della richiesta SAML.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Vedere la demo live dei resolver di attestazioni SAML.

Provider di identità OAuth2

La tabella seguente elenca i resolver di attestazioni del provider di identità OAuth2:

Attestazione	Descrizione	Esempio
{oauth2:access_token}	Token di accesso del provider di identità OAuth2. Attributo `access_token`.	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	Tipo del token di accesso. Attributo `token_type`.	Bearer
{oauth2:expires_in}	Periodo di validità del token di accesso in secondi. Attributo `expires_in`. L'attestazione di output DataType deve essere `int` o `long`.	960000
{oauth2:refresh_token}	Token di aggiornamento del provider di identità OAuth2. Attributo `refresh_token`.	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

Per usare i resolver di attestazioni del provider di identità OAuth2, impostare l'attributo dell'attestazione di PartnerClaimType output sul resolver di attestazioni. L'esempio seguente illustra come ottenere le attestazioni del provider di identità esterno:

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

Uso dei resolver di attestazioni

È possibile usare i resolver di attestazioni con gli elementi seguenti:

Articolo	Elemento	Impostazione
Profilo tecnico di Application Insights	`InputClaim`
Profilo tecnico Di Microsoft Entra	`InputClaim`, `OutputClaim`	1, 2
Profilo tecnico OAuth2	`InputClaim`, `OutputClaim`	1, 2
OpenID Connessione profilo tecnico	`InputClaim`, `OutputClaim`	1, 2
Profilo tecnico della trasformazione delle attestazioni	`InputClaim`, `OutputClaim`	1, 2
Profilo tecnico del provider RESTful	`InputClaim`	1, 2
Profilo tecnico del provider di identità SAML	`OutputClaim`	1, 2
Profilo tecnico autocertificato	`InputClaim`, `OutputClaim`	1, 2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
Profilo tecnico RelyingParty	`OutputClaim`	2

Impostazioni:

I IncludeClaimResolvingInClaimsHandling metadati devono essere impostati su true.
L'attributo AlwaysUseDefaultValue delle attestazioni di input o output deve essere impostato su true.

Esempi di resolver di attestazioni

Profilo tecnico RESTful

In un profilo tecnico RESTful può essere utile inviare la lingua dell'utente, il nome dei criteri, l'ambito e l'ID client. In base alle attestazioni che l'API REST può eseguire logica di business personalizzata e, se necessario, generare un messaggio di errore localizzato.

L'esempio seguente mostra un profilo tecnico RESTful con questo scenario:

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

Con i resolver di attestazioni è possibile precompilare il nome di accesso o l'accesso diretto a un provider di identità di social networking specifico, ad esempio Facebook, LinkedIn o un account Microsoft. Per altre informazioni, vedere Configurare l'accesso diretto tramite Active Directory B2C.

Personalizzazione dell'interfaccia utente dinamica

Azure AD B2C consente di passare parametri di stringa di query agli endpoint di definizione del contenuto HTML per eseguire il rendering dinamico del contenuto della pagina. Ad esempio, questa funzionalità consente di modificare l'immagine di sfondo nella pagina di iscrizione o accesso di Azure AD B2C in base a un parametro personalizzato passato dall'applicazione Web o per dispositivi mobili. Per altre informazioni, vedere Azure Active Directory B2C: Configurare l'interfaccia utente con contenuto dinamico usando criteri personalizzati. È anche possibile localizzare la pagina HTML in base a un parametro di lingua oppure è possibile modificare il contenuto in base all'ID client.

L'esempio seguente passa il parametro della stringa di query denominato campaignId con un valore , Hawaiiun codice di lingua di en-USe un'app che rappresenta l'ID client:

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

Di conseguenza, Azure AD B2C invia i parametri precedenti alla pagina del contenuto HTML:

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

Definizione del contenuto

In contentDefinition LoadUriè possibile inviare resolver di attestazioni per eseguire il pull del contenuto da posizioni diverse, in base ai parametri usati.

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

Profilo tecnico di Application Insights

Con Azure Application Insights e i resolver di attestazioni è possibile ottenere informazioni dettagliate sul comportamento degli utenti. Nel profilo tecnico di Application Insights, si inviano le attestazioni di input che vengono salvate in Azure Application Insights. Per altre informazioni, vedere Tenere traccia del comportamento degli utenti nei percorsi di Azure AD B2C usando Application Insights. L'esempio seguente invia l'ID dei criteri, l'ID di correlazione, la lingua e l'ID client ad 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>

Criteri relying party

In un profilo tecnico dei criteri relying party può essere necessario inviare l'ID tenant o l'ID di correlazione all'applicazione relying party all'interno del token 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>

Passaggi successivi

Trovare altri esempi di resolver di attestazioni nel repository GitHub della community di Azure AD B2C