Gerir as políticas personalizadas Azure AD B2C com a Azure PowerShellManage Azure AD B2C custom policies with Azure PowerShell

A Azure PowerShell fornece vários cmdlets para a gestão de políticas personalizadas baseada em linha de comando e scripts no seu inquilino Azure AD B2C.Azure PowerShell provides several cmdlets for command line- and script-based custom policy management in your Azure AD B2C tenant. Saiba como utilizar o módulo Azure AD PowerShell para:Learn how to use the Azure AD PowerShell module to:

  • Listar as políticas personalizadas num inquilino Azure AD B2CList the custom policies in an Azure AD B2C tenant
  • Faça o download de uma apólice de um inquilinoDownload a policy from a tenant
  • Atualizar uma política existente, sobreescrevendo o seu conteúdoUpdate an existing policy by overwriting its content
  • Faça o upload de uma nova política para o seu inquilino Azure AD B2CUpload a new policy to your Azure AD B2C tenant
  • Excluir uma política personalizada de um inquilinoDelete a custom policy from a tenant

Pré-requisitosPrerequisites

Ligue a sessão PowerShell ao inquilino B2CConnect PowerShell session to B2C tenant

Para trabalhar com políticas personalizadas no seu inquilino Azure AD B2C, primeiro precisa ligar a sua sessão PowerShell ao inquilino utilizando o 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.

Execute o seguinte comando, {b2c-tenant-name} substituindo-o pelo nome do seu inquilino Azure AD B2C.Execute the following command, substituting {b2c-tenant-name} with the name of your Azure AD B2C tenant. Inscreva-se com uma conta que atribuiu o papel de Administrador de Política B2C IEF no diretório.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"

Saída de comando de exemplo mostrando um sucesso de in: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

Listar todas as políticas personalizadas no inquilinoList all custom policies in the tenant

A descoberta de políticas personalizadas permite a um administrador AD B2C rever, gerir e adicionar lógica de negócio às suas operações.Discovering custom policies allows an Azure AD B2C administrator to review, manage, and add business logic to their operations. Utilize o comando Get-AzureADMSTrustFrameworkPolicy para devolver uma lista dos IDs das políticas personalizadas num inquilino 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

Saída de comando de exemplo:Example command output:

PS C:\> Get-AzureADMSTrustFrameworkPolicy

Id
--
B2C_1A_TrustFrameworkBase
B2C_1A_TrustFrameworkExtensions
B2C_1A_signup_signin
B2C_1A_ProfileEdit
B2C_1A_PasswordReset

Faça o download de uma apóliceDownload a policy

Depois de rever a lista de IDs de política, pode direcionar uma política específica com a Get-AzureADMSTrustFrameworkPolicy para descarregar o seu conteúdo.After reviewing the list of policy IDs, you can target a specific policy with Get-AzureADMSTrustFrameworkPolicy to download its content.

Get-AzureADMSTrustFrameworkPolicy [-Id <policyId>]

Neste exemplo, a política com id B2C_1A_signup_signin é descarregada: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 o conteúdo da política localmente, encaneie a saída de comando num ficheiro com o -OutputFilePath argumento e, em seguida, abra o ficheiro no seu editor favorito.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.

Exemplo de envio de comando para um ficheiro: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

Atualizar uma política existenteUpdate an existing policy

Depois de editar um ficheiro de política que criou ou descarregou, pode publicar a política atualizada para Azure AD B2C utilizando o 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.

Se emitir o Set-AzureADMSTrustFrameworkPolicy comando com o ID de uma política que já existe no seu inquilino Azure AD B2C, o conteúdo dessa política está substituído.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 exemplo:Example command:

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

Para outros exemplos, consulte a referência de comando Set-AzureADMSTrustFrameworkPolicy.For additional examples, see the Set-AzureADMSTrustFrameworkPolicy command reference.

Faça upload de uma nova políticaUpload a new policy

Quando fizer uma alteração para uma política personalizada que está em execução em produção, talvez queira publicar várias versões da política para cenários de testes de recuo ou A/B.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. Ou, talvez queira fazer uma cópia de uma política existente, modificá-la com algumas pequenas alterações e, em seguida, carregá-la como uma nova política para uso por uma aplicação diferente.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.

Utilize o comando New-AzureADMSTrustFrameworkPolicy para carregar uma nova política:Use the New-AzureADMSTrustFrameworkPolicy command to upload a new policy:

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

Comando de exemplo:Example command:

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

Excluir uma política personalizadaDelete a custom policy

Para manter um ciclo de vida de operações limpas, recomendamos que remova periodicamente as políticas personalizadas não habituais.To maintain a clean operations life cycle, we recommend that you periodically remove unused custom policies. Por exemplo, é melhor remover as versões políticas antigas depois de realizar uma migração para um novo conjunto de políticas e verificar a funcionalidade das novas políticas.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. Além disso, se tentar publicar um conjunto de políticas personalizadas e receber um erro, poderá fazer sentido remover as políticas que foram criadas como parte da versão falhada.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.

Utilize o comando Remove-AzureADMSTrustFrameworkPolicy para eliminar uma apólice do seu inquilino.Use the Remove-AzureADMSTrustFrameworkPolicy command to delete a policy from your tenant.

Remove-AzureADMSTrustFrameworkPolicy -Id <policyId>

Comando de exemplo:Example command:

# Delete an existing policy
Remove-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin

Upload de política de resolução de problemasTroubleshoot policy upload

Quando tenta publicar uma nova política personalizada ou atualizar uma política existente, a formatação imprópria do XML e os erros na cadeia de herança de ficheiros de política podem causar falhas de validação.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 exemplo, aqui está uma tentativa de atualizar uma política com conteúdo que contém XML mal formado (a saída é truncada para a brevidade):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 obter informações sobre a resolução de problemas de políticas personalizadas, consulte as políticas personalizadas do Azure AD B2C e o Quadro de Experiência de Identidade.For information about troubleshooting custom policies, see Troubleshoot Azure AD B2C custom policies and Identity Experience Framework.

Passos seguintesNext steps

Para obter informações sobre a utilização do PowerShell para implementar políticas personalizadas como parte de um pipeline de integração contínua/entrega contínua (CI/CD), consulte implementar políticas personalizadas a partir de um oleoduto 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.