Administración de las directivas personalizadas de Azure AD B2C con Azure PowerShellManage Azure AD B2C custom policies with Azure PowerShell

Azure PowerShell proporciona varios cmdlets para la administración de directivas personalizadas basadas en scripts y de línea de comandos en el inquilino e Azure AD B2C.Azure PowerShell provides several cmdlets for command line- and script-based custom policy management in your Azure AD B2C tenant. Aprenda a usar el módulo de PowerShell de Azure AD para:Learn how to use the Azure AD PowerShell module to:

  • Enumerar las directivas personalizadas en un inquilino de Azure AD B2CList the custom policies in an Azure AD B2C tenant
  • Descargar una directiva de un inquilinoDownload a policy from a tenant
  • Sobrescribir el contenido de una directiva existente para actualizarlaUpdate an existing policy by overwriting its content
  • Cargar una nueva directiva en el inquilino de Azure AD B2CUpload a new policy to your Azure AD B2C tenant
  • Eliminar una directiva personalizada de un inquilinoDelete a custom policy from a tenant

PrerrequisitosPrerequisites

Conexión de la sesión de PowerShell con el inquilino de B2CConnect PowerShell session to B2C tenant

Para trabajar con directivas personalizadas en el inquilino de Azure AD B2C,primero debe conectar la sesión de PowerShell al inquilino con el comando Connect-AzureAD.To work with custom policies in your Azure AD B2C tenant, you first need to connect your PowerShell session to the tenant by using the Connect-AzureAD command.

Sustituya {b2c-tenant-name} por el nombre del inquilino de Azure AD B2C para ejecutar el siguiente comando.Execute the following command, substituting {b2c-tenant-name} with the name of your Azure AD B2C tenant. Inicie sesión con una cuenta asignada al rol Administrador de directivas de B2C IEF en el directorio.Sign in with an account that's assigned the B2C IEF Policy Administrator role in the directory.

Connect-AzureAD -Tenant "{b2c-tenant-name}.onmicrosoft.com"

El ejemplo de salida del comando muestra un inicio de sesión correcto:Example command output showing a successful sign-in:

PS C:\> Connect-AzureAD -Tenant "contosob2c.onmicrosoft.com"

Account               Environment TenantId                             TenantDomain                 AccountType
-------               ----------- --------                             ------------                 -----------
azureuser@contoso.com AzureCloud  00000000-0000-0000-0000-000000000000 contosob2c.onmicrosoft.com   User

Enumeración de todas las directivas personalizadas del inquilinoList all custom policies in the tenant

La detección de directivas personalizadas permite que un administrador de Azure AD B2C revise, administre y agregue lógica de negocios a las operaciones.Discovering custom policies allows an Azure AD B2C administrator to review, manage, and add business logic to their operations. Use el comando Get-AzureADMSTrustFrameworkPolicy para devolver una lista de los identificadores de las directivas personalizadas en un inquilino de Azure AD B2C.Use the Get-AzureADMSTrustFrameworkPolicy command to return a list of the IDs of the custom policies in an Azure AD B2C tenant.

Get-AzureADMSTrustFrameworkPolicy

Ejemplo de salida del comando:Example command output:

PS C:\> Get-AzureADMSTrustFrameworkPolicy

Id
--
B2C_1A_TrustFrameworkBase
B2C_1A_TrustFrameworkExtensions
B2C_1A_signup_signin
B2C_1A_ProfileEdit
B2C_1A_PasswordReset

Descarga de una directivaDownload a policy

Tras revisar la lista de id. de directivas, puede abordar una directiva específica con Get-AzureADMSTrustFrameworkPolicy para descargar su contenido.After reviewing the list of policy IDs, you can target a specific policy with Get-AzureADMSTrustFrameworkPolicy to download its content.

Get-AzureADMSTrustFrameworkPolicy [-Id <policyId>]

En este ejemplo, la directiva con id. B2C_1A_signup_signin está descargada:In this example, the policy with ID B2C_1A_signup_signin is downloaded:

PS C:\> Get-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin
<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="contosob2c.onmicrosoft.com" PolicyId="B2C_1A_signup_signin" PublicPolicyUri="http://contosob2c.onmicrosoft.com/B2C_1A_signup_signin" TenantObjectId="00000000-0000-0000-0000-000000000000">
  <BasePolicy>
    <TenantId>contosob2c.onmicrosoft.com</TenantId>
    <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
  </BasePolicy>
  <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}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
</TrustFrameworkPolicy>

Para editar el contenido de la directiva localmente, canalice la salida del comando en un archivo con el argumento -OutputFilePath y abra el archivo en el editor que prefiera.To edit the policy content locally, pipe the command output to a file with the -OutputFilePath argument, and then open the file in your favorite editor.

Ejemplo de comando enviando una salida a un archivo:Example command sending output to a file:

# Download and send policy output to a file
Get-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin -OutputFilePath C:\RPPolicy.xml

Actualización de una directiva existenteUpdate an existing policy

Tras editar un archivo de una directiva que ha creado o descargado, puede publicar la directiva actualizada en Azure AD B2C con el comando Set-AzureADMSTrustFrameworkPolicy.After editing a policy file you've created or downloaded, you can publish the updated policy to Azure AD B2C by using the Set-AzureADMSTrustFrameworkPolicy command.

Si emite el comando Set-AzureADMSTrustFrameworkPolicy con el id. de una directiva que ya existe en el inquilino de Azure AD B2C, el contenido de dicha directiva se sobrescribe.If you issue the Set-AzureADMSTrustFrameworkPolicy command with the ID of a policy that already exists in your Azure AD B2C tenant, the content of that policy is overwritten.

Set-AzureADMSTrustFrameworkPolicy [-Id <policyId>] -InputFilePath <inputpolicyfilePath> [-OutputFilePath <outputFilePath>]

Comando de ejemplo:Example command:

# Update an existing policy from file
Set-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin -InputFilePath C:\B2C_1A_signup_signin.xml

Para ver más ejemplos, consulte la referencia del comando Set-AzureADMSTrustFrameworkPolicy.For additional examples, see the Set-AzureADMSTrustFrameworkPolicy command reference.

Carga de una nueva directivaUpload a new policy

Al realizar un cambio en una directiva personalizada que se ejecuta en producción, puede que quiera publicar varias versiones de esta para escenarios de prueba A/B o reserva.When you make a change to a custom policy that's running in production, you might want to publish multiple versions of the policy for fallback or A/B testing scenarios. Puede que también quiera realizar una copia de una directiva existente, modificarla con un ligero cambio y, luego, cargarla como una nueva directiva para usarla en otra aplicación.Or, you might want to make a copy of an existing policy, modify it with a few small changes, then upload it as a new policy for use by a different application.

Use el comando New-AzureADMSTrustFrameworkPolicy para cargar una nueva directiva:Use the New-AzureADMSTrustFrameworkPolicy command to upload a new policy:

New-AzureADMSTrustFrameworkPolicy -InputFilePath <inputpolicyfilePath> [-OutputFilePath <outputFilePath>]

Comando de ejemplo:Example command:

# Add new policy from file
New-AzureADMSTrustFrameworkPolicy -InputFilePath C:\SignUpOrSignInv2.xml

Eliminación de una directiva personalizadaDelete a custom policy

Para mantener un ciclo de vida de operaciones limpio, se recomienda quitar periódicamente las directivas personalizadas que no se usen.To maintain a clean operations life cycle, we recommend that you periodically remove unused custom policies. Por ejemplo, puede que quiera quitar las anteriores versiones de una directiva tras realizar una migración a un nuevo conjunto de directivas y verificar la funcionalidad de las nuevas directivas.For example, you might want to remove old policy versions after performing a migration to a new set of policies and verifying the new policies' functionality. Además, si intenta publicar un conjunto de directivas personalizadas y recibe un error, puede que sea conveniente quitar las directivas que se crearon como parte de la versión con errores.Additionally, if you attempt to publish a set of custom policies and receive an error, it might make sense to remove the policies that were created as part of the failed release.

Use el comando Remove-AzureADMSTrustFrameworkPolicy para eliminar una directiva del inquilino.Use the Remove-AzureADMSTrustFrameworkPolicy command to delete a policy from your tenant.

Remove-AzureADMSTrustFrameworkPolicy -Id <policyId>

Comando de ejemplo:Example command:

# Delete an existing policy
Remove-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin

Solución de problemas de carga de las directivasTroubleshoot policy upload

Al intentar publicar una nueva directiva personalizada o actualizar una directiva existente, errores y formatos XML inadecuados en la cadena de herencia de los archivos de directiva pueden provocar errores de validación.When you try to publish a new custom policy or update an existing policy, improper XML formatting and errors in the policy file inheritance chain can cause validation failures.

Por ejemplo, a continuación se indica un intento de actualizar una directiva con contenido que incluye XML con estructura incorrecta (la salida está truncada para que sea breve):For example, here's an attempt at updating a policy with content that contains malformed XML (output is truncated for brevity):

PS C:\> Set-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin -InputFilePath C:\B2C_1A_signup_signin.xml
Set-AzureADMSTrustFrameworkPolicy : Error occurred while executing PutTrustFrameworkPolicy
Code: AADB2C
Message: Validation failed: 1 validation error(s) found in policy "B2C_1A_SIGNUP_SIGNIN" of tenant "contosob2c.onmicrosoft.com".Schema validation error found at line
14 col 55 in policy "B2C_1A_SIGNUP_SIGNIN" of tenant "contosob2c.onmicrosoft.com": The element 'OutputClaims' in namespace
'http://schemas.microsoft.com/online/cpim/schemas/2013/06' cannot contain text. List of possible elements expected: 'OutputClaim' in namespace
'http://schemas.microsoft.com/online/cpim/schemas/2013/06'.
...

Para información sobre la solución de problemas de directivas personalizadas, consulte Solución de problemas de directivas personalizadas de Azure AD B2C e Identity Experience Framework.For information about troubleshooting custom policies, see Troubleshoot Azure AD B2C custom policies and Identity Experience Framework.

Pasos siguientesNext steps

Para información sobre el uso de PowerShell para implementar directivas personalizadas como parte de una canalización de integración o entrega continuas (CI/CD), consulte Implementación de directivas personalizadas desde una canalización de Azure DevOps.For information about using PowerShell to deploy custom policies as part of a continuous integration/continuous delivery (CI/CD) pipeline, see Deploy custom policies from an Azure DevOps pipeline.