Acerca de los solucionadores de notificaciones en las directivas personalizadas de Azure Active Directory B2C

Artículo
01/19/2024

Los solucionadores de notificaciones de directivas personalizadas de Azure Active Directory B2C (Azure AD B2C) proporcionan información de contexto sobre una solicitud de autorización, como el nombre de la directiva, el identificador de correlación de la solicitud, el idioma de la interfaz de usuario, etc.

Para utilizar un solucionador de notificaciones en una notificación de entrada o salida, se define una cadena ClaimType en el elemento ClaimsSchema y, a continuación, se establece DefaultValue en el solucionador de notificaciones del elemento de notificación de entrada o salida. Azure AD B2C lee el valor del solucionador de notificaciones y usa el valor en el perfil técnico.

En el ejemplo siguiente, un tipo de notificación llamada correlationId se define con un DataType de string.

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

En el perfil técnico, asigne el solucionador de notificaciones al tipo de notificación. Azure AD B2C rellena el valor del solucionador de notificaciones {Context:CorrelationId} en la notificación correlationId y envía la notificación al perfil técnico.

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

culture

En la tabla siguiente se enumeran los solucionadores de notificaciones con información sobre el idioma usado en la solicitud de autorización:

Notificación	Descripción	Ejemplo
{Culture:LanguageName}	Código ISO de dos letras para el idioma.	en
{Culture:LCID}	El identificador de configuración regional del código de idioma.	3082
{Culture:RegionName}	Código ISO de dos letras para la región.	US
{Culture:RFC5646}	Código de idioma RFC5646.	es-ES

Consulte la demo en vivo de los solucionadores de notificaciones de referencia cultural.

Directiva

En la tabla siguiente se enumeran los solucionadores de notificaciones con información sobre la directiva usada en la solicitud de autorización:

Notificación	Descripción	Ejemplo
{Policy:PolicyId}	Nombre de la directiva del usuario de confianza.	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	El identificador de inquilino de la directiva del usuario de confianza.	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	El identificador de objeto de inquilino de la directiva del usuario de confianza.	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	El identificador de inquilino del marco de confianza.	your-tenant.onmicrosoft.com

Consulte la demo en vivo de los solucionadores de notificaciones de directivas.

Context

En la tabla siguiente se enumeran los solucionadores de notificaciones contextuales de la solicitud de autorización:

Notificación	Descripción	Ejemplo
{Context:BuildNumber}	Versión del marco de experiencia de identidad (número de compilación).	1.0.507.0
{Context:CorrelationId}	Identificador de correlación.	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	Hora y fecha en UTC.	10/10/2021 12:00:00 PM
{Context:DeploymentMode}	Modo de implementación de la directiva.	Producción
{Context:HostName}	El nombre de host de la solicitud actual.	contoso.b2clogin.com
{Context:IPAddress}	Dirección IP del usuario.	11.111.111.11
{Context:KMSI}	Indica si se ha seleccionado la casilla Mantener la sesión iniciada.	true

Consulte la demo en vivo de los solucionadores de notificaciones de contexto.

Notificaciones

En esta sección se describe cómo obtienen los valores de notificaciones los solucionador de notificaciones.

Notificación	Descripción	Ejemplo
{Claim:claim type}	Identificador de un tipo de notificación que ya se ha definido en la sección ClaimsSchema del archivo de directiva o del archivo de directiva principal. Por ejemplo: `{Claim:displayName}` o `{Claim:objectId}`.	Valor de tipo de notificación.

OpenID Connect

En la tabla siguiente se enumeran los solucionadores de notificaciones con información sobre la solicitud de autorización de OpenID Connect:

Notificación	Descripción	Ejemplo
{OIDC:AuthenticationContextReferences}	El parámetro de cadena de consulta `acr_values`.	N/D
{OIDC:ClientId}	El parámetro de cadena de consulta `client_id`.	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	El parámetro de cadena de consulta `domain_hint`.	facebook.com
{OIDC:LoginHint}	El parámetro de cadena de consulta `login_hint`.	someone@contoso.com
{OIDC:MaxAge}	El parámetro de cadena de consulta `max_age`.	N/D
{OIDC:Nonce}	El parámetro de cadena de consulta `Nonce`.	defaultNonce
{OIDC:Password}	Contraseña de usuario del flujo de credenciales de contraseña del propietario del recurso.	password1
{OIDC:Prompt}	El parámetro de cadena de consulta `prompt`.	login
{OIDC:RedirectUri}	El parámetro de cadena de consulta `redirect_uri`.	https://jwt.ms
{OIDC:Resource}	El parámetro de cadena de consulta `resource`.	N/D
{OIDC:Scope}	El parámetro de cadena de consulta `scope`.	openid
{OIDC:Username}	Nombre de usuario del usuario del flujo de credenciales de contraseña de propietario del recurso.	emily@contoso.com
{OIDC:IdToken}	El parámetro de cadena de consulta `id token`.	N/D

Consulte la demo en vivo de los solucionadores de notificaciones de OpenID Connect.

Parámetros clave-valor de OAuth2

Cualquier nombre de parámetro incluido como parte de una solicitud OIDC u OAuth2 se puede asignar a una notificación en el recorrido del usuario. Por ejemplo, la solicitud de la aplicación puede incluir un parámetro de cadena de consulta con el nombre de app_session, loyalty_number o cualquier cadena de consulta personalizada.

Notificación	Descripción	Ejemplo
{OAUTH-KV:campaignId}	Parámetro de cadena de consulta.	Hawái
{OAUTH-KV:app_session}	Parámetro de cadena de consulta.	A3C5R
{OAUTH-KV:loyalty_number}	Parámetro de cadena de consulta.	1234
{OAUTH-KV:any custom query string}	Parámetro de cadena de consulta.	N/D

Parámetros clave-valor de SAML

En una solicitud de autenticación SAML, cualquier nombre de parámetro incluido en la solicitud, pero no es específico del protocolo (como SAMLRequest) se puede asignar a una notificación en el recorrido del usuario. Por ejemplo, la solicitud puede incluir un parámetro personalizado como username. Esto se aplica tanto a las solicitudes SAML iniciadas por SP como a las iniciadas por IDP.

Reclamar	Descripción	Ejemplo
{SAML-KV:username}	Cadena de consulta o parámetro de cuerpo POST.	username@domain.com
{SAML-KV:loyalty_number}	Cadena de consulta o parámetro de cuerpo POST.	1234
{SAML-KV:any custom query string}	Cadena de consulta o parámetro de cuerpo POST.	N/D

SAML

En la tabla siguiente se enumeran los solucionadores de notificaciones con información sobre la solicitud de autorización de SAML:

Notificación	Descripción	Ejemplo
{SAML:AuthnContextClassReferences}	Valor del elemento `AuthnContextClassRef` de la solicitud SAML.	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	Atributo `Format` del elemento `NameIDPolicy` de la solicitud SAML.	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	Valor del elemento `Issuer` SAML de la solicitud SAML.	`https://contoso.com`
{SAML: AllowCreate}	Valor del atributo `AllowCreate` del elemento `NameIDPolicy` de la solicitud SAML.	True
{SAML:ForceAuthn}	Valor del atributo `ForceAuthN` del elemento `AuthnRequest` de la solicitud SAML.	True
{SAML:ProviderName}	Valor del atributo `ProviderName` del elemento `AuthnRequest` de la solicitud SAML.	Contoso.com
{SAML:RelayState}	El parámetro de cadena de consulta `RelayState`.
{SAML:Subject}	El valor de `Subject` del elemento NameId de la solicitud de autenticación de SAML.
{SAML:Binding}	Valor del atributo `ProtocolBinding` del elemento `AuthnRequest` de la solicitud SAML.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Consulte la demo en vivo de los solucionadores de notificaciones de SAML.

Proveedor de identidades de OAuth2

En la tabla siguiente, se enumeran los solucionadores de notificaciones del proveedor de identidades de OAuth2.

Notificación	Descripción	Ejemplo
{oauth2:access_token}	Token de acceso del proveedor de identidades de OAuth2. El atributo `access_token`.	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	Tipo del token de acceso. El atributo `token_type`.	Portador
{oauth2:expires_in}	Período de validez del token de acceso (en segundos). El atributo `expires_in`. La notificación de salida DataType debe ser `int` o `long`.	960000
{oauth2:refresh_token}	Token de actualización del proveedor de identidades de OAuth2. El atributo `refresh_token`.	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

Para usar los solucionadores de notificaciones del proveedor de identidades de OAuth2, establezca el atributo PartnerClaimType de la notificación de salida en el solucionador de notificaciones. En el ejemplo siguiente, se muestra cómo obtener las notificaciones del proveedor de identidades externo:

<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 de solucionadores de notificaciones

Puede usar solucionadores de notificaciones con los siguientes elementos:

Elemento	Elemento	Configuración
Perfil técnico de Application Insights	`InputClaim`
Perfil técnico de Microsoft Entra	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico de OAuth2	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico de OpenID Connect	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico de transformación de notificaciones	`InputClaim`, `OutputClaim`	1, 2
Perfil técnico de un proveedor RESTful	`InputClaim`	1, 2
Perfil técnico de un proveedor de identidades SAML	`OutputClaim`	1, 2
Perfil técnico autoafirmado	`InputClaim`, `OutputClaim`	1, 2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
Perfil técnico de RelyingParty	`OutputClaim`	2

Configuración:

Los metadatos de IncludeClaimResolvingInClaimsHandling se deben establecer en true.
El atributo de notificaciones de entrada o salida AlwaysUseDefaultValue se debe establecer en true.

Ejemplos de solucionadores de notificaciones

Perfil técnico de RESTful

En un perfil técnico de RESTful, es posible que desee enviar el idioma del usuario, el nombre de la directiva, el ámbito y el identificador de cliente. Según las notificaciones, la API de REST puede ejecutar la lógica de negocios personalizada y, si es necesario, generar un mensaje de error localizado.

En el ejemplo siguiente se muestra un perfil técnico de RESTful con este escenario:

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

Al usar solucionadores de notificaciones, puede rellenar previamente el nombre de inicio de sesión o puede iniciar sesión directamente en un proveedor de identidades sociales específico, como Facebook, LinkedIn o una cuenta de Microsoft. Para más información, consulte Configuración de inicio de sesión directo con Azure Active Directory B2C.

Personalización de la interfaz de usuario dinámica

Azure AD B2C le permite pasar parámetros de cadena de consulta a los puntos de conexión de la definición de contenido HTML para representar dinámicamente el contenido de la página. Por ejemplo, esta característica permite cambiar la imagen de fondo en la página de inicio de sesión o de registro de Azure AD B2C en función de un parámetro personalizado que se pasa desde la aplicación web o dispositivo móvil. Para más información, consulte Azure Active Directory B2C: configuración de la interfaz de usuario con contenido dinámico utilizando directivas personalizadas. También puede localizar la página HTML basándose en un parámetro de idioma, o bien puede cambiar el contenido basándose en el identificador de cliente.

El ejemplo siguiente pasa en la cadena de consulta un parámetro denominado campaignId con un valor de Hawaii, un código de idioma de en-US y una aplicación que representa el identificador de cliente:

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

Como resultado, Azure AD B2C envía los parámetros anteriores a la página de contenido HTML:

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

Definición de contenido

En ContentDefinitionLoadUri, puede enviar resoluciones de notificaciones para extraer contenido de distintos lugares, en función de los parámetros utilizados.

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

Perfil técnico de Application Insights

Con Azure Application Insights y los solucionadores de notificaciones, puede obtener información sobre el comportamiento del usuario. En el perfil técnico de Application Insights, envía notificaciones de entrada que se conservan en Azure Application Insights. Para más información, consulte Seguimiento del comportamiento del usuario dentro de los recorridos de Azure AD B2C mediante Application Insights. El ejemplo siguiente envía el identificador de directiva, el identificador de correlación, el idioma y el identificador de cliente a 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>

Directiva del usuario de confianza

En un perfil técnico de directiva de Usuario de confianza, es posible que quiera enviar el identificador de inquilino o el identificador de correlación a la aplicación de usuario de confianza en el 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>

Pasos siguientes

Encuentre más muestras de solucionadores de notificaciones en el repositorio de GitHub comunitario de Azure AD B2C.