Gerir políticas personalizadas Azure AD B2C com Azure PowerShell

  • Artigo

Azure PowerShell fornece vários cmdlets para a gestão de políticas personalizadas baseadas em linhas de comandos e scripts no inquilino do Azure AD B2C. Saiba como utilizar o módulo Azure AD PowerShell para:

  • Listar as políticas personalizadas num inquilino Azure AD B2C
  • Transferir uma política a partir de um inquilino
  • Atualizar uma política existente ao substituir o respetivo conteúdo
  • Carregar uma nova política para o inquilino do Azure AD B2C
  • Eliminar uma política personalizada de um inquilino

Pré-requisitos

Ligar a sessão do PowerShell ao inquilino B2C

Para trabalhar com políticas personalizadas no seu inquilino Azure AD B2C, primeiro tem de ligar a sessão do PowerShell ao inquilino com o comando Connect-AzureAD.

Execute o seguinte comando, substituindo {b2c-tenant-name} pelo nome do seu inquilino Azure AD B2C. Inicie sessão com uma conta que tenha atribuído a função de Administrador de Política do IEF B2C no diretório.

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

Saída de comando de exemplo a mostrar um início de sessão bem-sucedido:

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 inquilino

A deteção de políticas personalizadas permite que um administrador do B2C Azure AD reveja, faça a gestão e adicione lógica de negócio às suas operações. Utilize o comando Get-AzureADMSTrustFrameworkPolicy para devolver uma lista dos IDs das políticas personalizadas num inquilino Azure AD B2C.

Get-AzureADMSTrustFrameworkPolicy

Saída do comando de exemplo:

PS C:\> Get-AzureADMSTrustFrameworkPolicy

Id
--
B2C_1A_TrustFrameworkBase
B2C_1A_TrustFrameworkExtensions
B2C_1A_signup_signin
B2C_1A_ProfileEdit
B2C_1A_PasswordReset

Transferir uma política

Depois de rever a lista de IDs de política, pode direcionar uma política específica com Get-AzureADMSTrustFrameworkPolicy para transferir o respetivo conteúdo.

Get-AzureADMSTrustFrameworkPolicy [-Id <policyId>]

Neste exemplo, a política com o ID B2C_1A_signup_signin é transferida:

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, encaminhe a saída do comando para um ficheiro com o -OutputFilePath argumento e, em seguida, abra o ficheiro no seu editor favorito.

Comando de exemplo a enviar saída para um ficheiro:

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

Atualizar uma política existente

Depois de editar um ficheiro de política que criou ou transferiu, pode publicar a política atualizada para Azure AD B2C com o comando Set-AzureADMSTrustFrameworkPolicy.

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 será substituído.

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

Comando de exemplo:

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

Para obter exemplos adicionais, veja a referência do comando Set-AzureADMSTrustFrameworkPolicy .

Carregar uma nova política

Quando efetua uma alteração a uma política personalizada em execução em produção, poderá querer publicar várias versões da política para cenários de contingência ou de teste A/B. Em alternativa, pode querer 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 utilização por uma aplicação diferente.

Utilize o comando New-AzureADMSTrustFrameworkPolicy para carregar uma nova política:

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

Comando de exemplo:

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

Eliminar uma política personalizada

Para manter um ciclo de vida de operações limpas, recomendamos que remova periodicamente as políticas personalizadas não utilizadas. Por exemplo, poderá querer remover versões de política antigas depois de efetuar uma migração para um novo conjunto de políticas e verificar a funcionalidade das novas políticas. 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.

Utilize o comando Remove-AzureADMSTrustFrameworkPolicy para eliminar uma política do seu inquilino.

Remove-AzureADMSTrustFrameworkPolicy -Id <policyId>

Comando de exemplo:

# Delete an existing policy
Remove-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin

Resolver problemas de carregamento de políticas

Quando tenta publicar uma nova política personalizada ou atualizar uma política existente, a formatação XML incorreta e os erros na cadeia de herança de ficheiros de política podem causar falhas de validação.

Por exemplo, eis uma tentativa de atualizar uma política com conteúdo que contém XML mal formado (a saída está truncada para brevidade):

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, veja Resolver problemas Azure AD políticas personalizadas B2C e o Identity Experience Framework.

Passos seguintes

Para obter informações sobre como utilizar o PowerShell para implementar políticas personalizadas como parte de um pipeline de integração/entrega contínua (CI/CD), veja Implementar políticas personalizadas a partir de um pipeline do Azure DevOps.