Gestire Azure AD B2C criteri personalizzati con Azure PowerShell

Azure PowerShell offre diversi cmdlet per la gestione dei criteri personalizzata basata su script e riga di comando nel tenant di Azure AD B2C. Informazioni su come usare il modulo Azure AD PowerShell per:

  • Elencare i criteri personalizzati in un tenant di Azure AD B2C
  • Scaricare un criterio da un tenant
  • Aggiornare un criterio esistente sovrascrivendo il relativo contenuto
  • Caricare un nuovo criterio nel tenant di Azure AD B2C
  • Eliminare un criterio personalizzato da un tenant

Prerequisiti

Connettere la sessione di PowerShell al tenant B2C

Per usare i criteri personalizzati nel tenant di Azure AD B2C, è prima di tutto necessario connettere la sessione di PowerShell al tenant usando il comando Connect-AzureAD .

Eseguire il comando seguente, sostituendo {b2c-tenant-name} con il nome del tenant del Azure ad B2C. Accedere con un account a cui è assegnato il ruolo di amministratore dei criteri B2C Framework dell'esperienza nella directory.

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

Esempio di output del comando che mostra un accesso riuscito:

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

Elencare tutti i criteri personalizzati nel tenant

L'individuazione di criteri personalizzati consente a un amministratore Azure AD B2C di esaminare, gestire e aggiungere la logica di business alle relative operazioni. Usare il comando Get-AzureADMSTrustFrameworkPolicy per restituire un elenco degli ID dei criteri personalizzati in un tenant di Azure ad B2C.

Get-AzureADMSTrustFrameworkPolicy

Esempio di output del comando:

PS C:\> Get-AzureADMSTrustFrameworkPolicy

Id
--
B2C_1A_TrustFrameworkBase
B2C_1A_TrustFrameworkExtensions
B2C_1A_signup_signin
B2C_1A_ProfileEdit
B2C_1A_PasswordReset

Scaricare un criterio

Dopo aver esaminato l'elenco degli ID dei criteri, è possibile indirizzare un criterio specifico con Get-AzureADMSTrustFrameworkPolicy per scaricarne il contenuto.

Get-AzureADMSTrustFrameworkPolicy [-Id <policyId>]

In questo esempio vengono scaricati i criteri con ID B2C_1A_signup_signin :

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>

Per modificare localmente il contenuto dei criteri, inviare tramite pipe l'output del comando a un file con l' -OutputFilePath argomento e quindi aprire il file nell'editor preferito.

Esempio di comando che invia l'output a un file:

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

Aggiornare un criterio esistente

Dopo aver modificato un file di criteri creato o scaricato, è possibile pubblicare il criterio aggiornato in modo da Azure AD B2C usando il comando set-AzureADMSTrustFrameworkPolicy .

Se si esegue il Set-AzureADMSTrustFrameworkPolicy comando con l'ID di un criterio già esistente nel tenant di Azure ad B2C, il contenuto di tale criterio verrà sovrascritto.

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

Comando di esempio:

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

Per altri esempi, vedere la Guida di riferimento al comando set-AzureADMSTrustFrameworkPolicy .

Carica un nuovo criterio

Quando si modifica un criterio personalizzato in esecuzione nell'ambiente di produzione, potrebbe essere necessario pubblicare più versioni del criterio per gli scenari di test di fallback o A/B. In alternativa, è possibile creare una copia di un criterio esistente, modificarla con alcune piccole modifiche, quindi caricarla come nuovo criterio per l'uso da un'altra applicazione.

Usare il comando New-AzureADMSTrustFrameworkPolicy per caricare un nuovo criterio:

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

Comando di esempio:

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

Eliminare un criterio personalizzato

Per mantenere un ciclo di vita operativo pulito, è consigliabile rimuovere periodicamente i criteri personalizzati non usati. Ad esempio, potrebbe essere necessario rimuovere le versioni precedenti dei criteri dopo aver eseguito una migrazione a un nuovo set di criteri e aver verificato la funzionalità dei nuovi criteri. Inoltre, se si tenta di pubblicare un set di criteri personalizzati e si riceve un errore, potrebbe essere utile rimuovere i criteri creati come parte della versione non riuscita.

Usare il comando Remove-AzureADMSTrustFrameworkPolicy per eliminare un criterio dal tenant.

Remove-AzureADMSTrustFrameworkPolicy -Id <policyId>

Comando di esempio:

# Delete an existing policy
Remove-AzureADMSTrustFrameworkPolicy -Id B2C_1A_signup_signin

Risolvere i problemi di caricamento dei criteri

Quando si tenta di pubblicare un nuovo criterio personalizzato o di aggiornare un criterio esistente, la formattazione XML non corretta e gli errori nella catena di ereditarietà dei file di criteri possono causare errori di convalida.

Ad esempio, di seguito è riportato un tentativo di aggiornamento di un criterio con contenuto che contiene codice XML non valido (l'output viene troncato per brevità):

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

Per informazioni sulla risoluzione dei problemi relativi ai criteri personalizzati, vedere risoluzione dei problemi Azure ad B2C criteri personalizzati e Framework dell'esperienza di identità.

Passaggi successivi

Per informazioni sull'uso di PowerShell per distribuire criteri personalizzati come parte di una pipeline di integrazione continua/recapito continuo (CI/CD), vedere distribuire criteri personalizzati da una pipeline di Azure DevOps.