Bereitstellen benutzerdefinierter Richtlinien mit Azure PipelinesDeploy custom policies with Azure Pipelines

Mithilfe einer CI/CD-Pipeline (Continuous Integration/Continuous Delivery), die Sie in Azure Pipelines einrichten, können Sie benutzerdefinierte Azure AD B2C-Richtlinien in Ihre Softwarebereitstellung und die Codesteuerungsautomatisierung einbeziehen.By using a continuous integration and delivery (CI/CD) pipeline that you set up in Azure Pipelines, you can include your Azure AD B2C custom policies in your software delivery and code control automation. Bei der Bereitstellung in unterschiedlichen Azure AD B2C-Umgebungen (z. B. Entwicklung, Test und Produktion) empfiehlt es sich, manuelle Prozesse zu entfernen und automatisierte Tests mithilfe von Azure Pipelines auszuführen.As you deploy to different Azure AD B2C environments, for example dev, test, and production, we recommend that you remove manual processes and perform automated testing by using Azure Pipelines.

Drei Hauptschritte sind erforderlich, um Azure Pipelines zum Verwalten benutzerdefinierter Richtlinien in Azure AD B2C zu aktivieren:There are three primary steps required for enabling Azure Pipelines to manage custom policies within Azure AD B2C:

  1. Erstellen einer Webanwendungsregistrierung in Ihrem Azure AD B2C-MandantenCreate a web application registration in your Azure AD B2C tenant
  2. Konfigurieren eines Azure-RepositoryConfigure an Azure Repo
  3. Konfigurieren einer Azure-PipelineConfigure an Azure Pipeline

Wichtig

Bei der Verwaltung von benutzerdefinierten Richtlinien in Azure AD B2C mit Azure Pipelines werden derzeit Vorschau-Vorgänge verwendet, die im /beta-Endpunkt der Microsoft Graph-API zur Verfügung stehen.Managing Azure AD B2C custom policies with an Azure Pipeline currently uses preview operations available on the Microsoft Graph API /beta endpoint. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported. Weitere Informationen finden Sie in der Microsoft Graph-REST-API-Beta-Endpunkt-Referenz.For more information, see the Microsoft Graph REST API beta endpoint reference.

VoraussetzungenPrerequisites

Gewährungsflow für ClientanmeldeinformationenClient credentials grant flow

In dem hier beschriebenen Szenario wrden Dienst-zu-Dienst-Aufrufe zwischen Azure Pipelines und Azure AD B2C mithilfe des Gewährungsflows für OAuth 2.0-Clientanmeldeinformationen verwendet.The scenario described here makes use of service-to-service calls between Azure Pipelines and Azure AD B2C by using the OAuth 2.0 client credentials grant flow. Dieser Gewährungsflow erlaubt einem Webdienst wie Azure Pipelines (vertraulicher Client), beim Aufrufen eines anderen Webdiensts (in diesem Fall die Microsoft Graph-API) seine eigenen Anmeldeinformationen zum Authentifizieren zu verwenden, anstatt die Identität eines Benutzers anzunehmen.This grant flow permits a web service like Azure Pipelines (the confidential client) to use its own credentials instead of impersonating a user to authenticate when calling another web service (the Microsoft Graph API, in this case). Azure Pipelines ruft ohne Benutzereingriff ein Token ab und sendet dann Anforderungen an die Microsoft Graph-API.Azure Pipelines obtains a token non-interactively, then makes requests to the Microsoft Graph API.

Registrieren einer Anwendung für VerwaltungstasksRegister an application for management tasks

Wie unter Voraussetzungen erwähnt, benötigen Sie eine Anwendungsregistrierung, die Ihre PowerShell-Skripts (die von Azure Pipelines ausgeführt werden) für den Zugriff auf die Ressourcen in Ihrem Mandanten verwenden können.As mentioned in Prerequisites, you need an application registration that your PowerShell scripts--executed by Azure Pipelines--can use for accessing the resources in your tenant.

Wenn Sie bereits über eine Anwendungsregistrierung verfügen, die Sie für Automatisierungsaufgaben verwenden, stellen Sie sicher, dass ihr in den API-Berechtigungen der App-Registrierung unter Microsoft Graph > Richtlinie > die Berechtigung Policy.ReadWrite.TrustFramework erteilt wurde.If you already have an application registration that you use for automation tasks, ensure it's been granted the Microsoft Graph > Policy > Policy.ReadWrite.TrustFramework permission within the API Permissions of the app registration.

Anweisungen zum Registrieren einer Verwaltungsanwendung finden Sie unter Verwalten von Azure AD B2C mit Microsoft Graph.For instructions on registering a management application, see Manage Azure AD B2C with Microsoft Graph.

Konfigurieren eines Azure-RepositoryConfigure an Azure Repo

Nach dem Registrieren der Verwaltungsanwendung können Sie ein Repository für Ihre Richtliniendateien konfigurieren.With a management application registered, you're ready to configure a repository for your policy files.

  1. Melden Sie sich bei Ihrer Azure DevOps Services-Organisation an.Sign in to your Azure DevOps Services organization.

  2. Erstellen Sie ein neues Projekt, oder wählen Sie ein vorhandenes Projekt aus.Create a new project or select an existing project.

  3. Navigieren Sie in Ihrem Projekt zu Repos, und wählen Sie die Seite Dateien aus.In your project, navigate to Repos and select the Files page. Wählen Sie für diese Übung ein vorhandenes Repository aus, oder erstellen Sie ein neues Repository.Select an existing repository or create one for this exercise.

  4. Erstellen Sie einen Ordner namens B2CAssets.Create a folder named B2CAssets. Geben Sie der erforderlichen Platzhalterdatei den Namen README.md, und führen Sie einen Commit für die Datei aus.Name the required placeholder file README.md and Commit the file. Sie können diese Datei später bei Bedarf entfernen.You can remove this file later, if you like.

  5. Fügen Sie Ihre Azure AD B2C-Richtliniendateien dem Ordner B2CAssets hinzu.Add your Azure AD B2C policy files to the B2CAssets folder. Dazu zählen TrustFrameworkBase.xml, TrustFrameWorkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml, PasswordReset.xml und alle weiteren Richtlinien, die Sie erstellt haben.This includes the TrustFrameworkBase.xml, TrustFrameWorkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml, PasswordReset.xml, and any other policies you've created. Notieren Sie sich die Dateinamen der einzelnen Azure AD B2C-Richtliniendateien, um sie in einem späteren Schritt (als PowerShell-Skriptargumente) zu verwenden.Record the filename of each Azure AD B2C policy file for use in a later step (they're used as PowerShell script arguments).

  6. Erstellen Sie im Stammverzeichnis des Repository einen Ordner namens Skripts, und geben Sie der Platzhalterdatei den Namen DeployToB2c.ps1.Create a folder named Scripts in the root directory of the repository, name the placeholder file DeployToB2c.ps1. Führen Sie an diesem Punkt noch keinen Commit für die Datei aus. Dies geschieht in einem späteren Schritt.Don't commit the file at this point, you'll do so in a later step.

  7. Fügen Sie das folgende PowerShell-Skript in die Datei DeployToB2c.ps1 ein, und führen Sie dann einen Commit für die Datei aus.Paste the following PowerShell script into DeployToB2c.ps1, then Commit the file. Mit dem Skript wird ein Token von Azure AD abgerufen und die Microsoft Graph-API aufgerufen, um die Richtlinien in den Ordner B2CAssets in Ihrem Azure AD B2C-Mandanten hochzuladen.The script acquires a token from Azure AD and calls the Microsoft Graph API to upload the policies within the B2CAssets folder to your Azure AD B2C tenant.

    [Cmdletbinding()]
    Param(
        [Parameter(Mandatory = $true)][string]$ClientID,
        [Parameter(Mandatory = $true)][string]$ClientSecret,
        [Parameter(Mandatory = $true)][string]$TenantId,
        [Parameter(Mandatory = $true)][string]$PolicyId,
        [Parameter(Mandatory = $true)][string]$PathToFile
    )
    
    try {
        $body = @{grant_type = "client_credentials"; scope = "https://graph.microsoft.com/.default"; client_id = $ClientID; client_secret = $ClientSecret }
    
        $response = Invoke-RestMethod -Uri https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token -Method Post -Body $body
        $token = $response.access_token
    
        $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
        $headers.Add("Content-Type", 'application/xml')
        $headers.Add("Authorization", 'Bearer ' + $token)
    
        $graphuri = 'https://graph.microsoft.com/beta/trustframework/policies/' + $PolicyId + '/$value'
        $policycontent = Get-Content $PathToFile
        $response = Invoke-RestMethod -Uri $graphuri -Method Put -Body $policycontent -Headers $headers
    
        Write-Host "Policy" $PolicyId "uploaded successfully."
    }
    catch {
        Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
    
        $_
    
        $streamReader = [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream())
        $streamReader.BaseStream.Position = 0
        $streamReader.DiscardBufferedData()
        $errResp = $streamReader.ReadToEnd()
        $streamReader.Close()
    
        $ErrResp
    
        exit 1
    }
    
    exit 0
    

Konfigurieren Ihrer Azure-PipelineConfigure your Azure pipeline

Nachdem Sie Ihr Repository initialisiert und mit Ihren benutzerdefinierten Richtliniendateien aufgefüllt haben, können Sie die Freigabepipeline einrichten.With your repository initialized and populated with your custom policy files, you're ready to set up the release pipeline.

Erstellen der PipelineCreate pipeline

  1. Melden Sie sich bei Ihrer Azure DevOps Services-Organisation an, und navigieren Sie zu Ihrem Projekt.Sign in to your Azure DevOps Services organization and navigate to your project.
  2. Wählen Sie in Ihrem Projekt Pipelines > Freigaben > Neue Pipeline aus.In your project, select Pipelines > Releases > New pipeline.
  3. Wählen Sie unter Vorlage auswählen die Option Leerer Auftrag aus.Under Select a template, select Empty job.
  4. Geben Sie einen Phasennamen (z. B. DeployCustomPolicies) ein, und schließen Sie dann den Bereich.Enter a Stage name, for example DeployCustomPolicies, then close the pane.
  5. Wählen Sie Artefakt hinzufügen aus, und wählen Sie unter Quelltyp die Option Azure-Repository aus.Select Add an artifact, and under Source type, select Azure Repository.
    1. Wählen Sie das Quellrepository mit dem Ordner Skripts und dem gespeicherten PowerShell-Skript aus.Choose the source repository containing the Scripts folder that you populated with the PowerShell script.
    2. Wählen Sie einen Standardbranch aus.Choose a Default branch. Wenn Sie im vorherigen Abschnitt ein neues Repository erstellt haben, ist master der Standardbranch.If you created a new repository in the previous section, the default branch is master.
    3. Übernehmen Sie unter Standardversion die Einstellung Neuestes Element aus dem Standardbranch.Leave the Default version setting of Latest from the default branch.
    4. Geben Sie für das Repository einen Quellalias ein,Enter a Source alias for the repository. zum Beispiel policyRepo.For example, policyRepo. Der Aliasname darf keine Leerzeichen enthalten.Do not include any spaces in the alias name.
  6. Wählen Sie Hinzufügen aus.Select Add
  7. Benennen Sie die Pipeline um, und geben Sie ihr einen aussagekräftigen Namen,Rename the pipeline to reflect its intent. zum Beispiel Deploy Custom Policy Pipeline.For example, Deploy Custom Policy Pipeline.
  8. Wählen Sie zum Speichern der Pipelinekonfiguration Speichern aus.Select Save to save the pipeline configuration.

Konfigurieren von PipelinevariablenConfigure pipeline variables

  1. Wählen Sie die Registerkarte Variablen aus.Select the Variables tab.

  2. Fügen Sie unter Pipelinevariablen die folgenden Variablen hinzu, und legen Sie die Werte wie angegeben fest:Add the following variables under Pipeline variables and set their values as specified:

    NameName WertValue
    clientId Anwendungs-ID (Client) der zuvor von Ihnen registrierten Anwendung.Application (client) ID of the application you registered earlier.
    clientSecret Wert des geheimen Clientschlüssels, den Sie zuvor erstellt haben.The value of the client secret that you created earlier.
    Ändern Sie den Variablentyp in Geheimnis (wählen Sie das Schlosssymbol aus).Change the variable type to secret (select the lock icon).
    tenantId your-b2c-tenant.onmicrosoft.com, wobei your-b2c-tenant dem Namen Ihres Azure AD B2C-Mandanten entspricht.your-b2c-tenant.onmicrosoft.com, where your-b2c-tenant is the name of your Azure AD B2C tenant.
  3. Wählen Sie Speichern aus, um die Variablen zu speichern.Select Save to save the variables.

Hinzufügen von PipelinetasksAdd pipeline tasks

Fügen Sie als Nächstes einen Task zum Bereitstellen einer Richtliniendatei hinzu.Next, add a task to deploy a policy file.

  1. Wählen Sie die Registerkarte Tasks aus.Select the Tasks tab.

  2. Wählen Sie Agent-Auftrag und dann das Pluszeichen ( + ) aus, um dem Agent-Auftrag einen Task hinzuzufügen.Select Agent job, and then select the plus sign (+) to add a task to the Agent job.

  3. Suchen Sie nach dem Eintrag PowerShell, und wählen Sie ihn aus.Search for and select PowerShell. Wählen Sie nicht „Azure PowerShell“, „PowerShell auf Zielcomputern“ oder einen anderen Eintrag im Zusammenhang mit PowerShell aus.Do not select "Azure PowerShell," "PowerShell on target machines," or another PowerShell entry.

  4. Wählen Sie den neu hinzugefügten Task PowerShell-Skript aus.Select newly added PowerShell Script task.

  5. Geben Sie für den Task „PowerShell-Skript“ die folgenden Werte ein:Enter following values for the PowerShell Script task:

    • Taskversion: 2.*Task version: 2.*

    • Anzeigename: Der Name der Richtlinie, die dieser Task hochladen soll,Display name: The name of the policy that this task should upload. zum Beispiel B2C_1A_TrustFrameworkBase.For example, B2C_1A_TrustFrameworkBase.

    • Typ: DateipfadType: File Path

    • Skriptpfad: Wählen Sie die Auslassungspunkte (...* _) aus, navigieren Sie zum Ordner _Skripts*, und wählen Sie dann die Datei DeployToB2C.ps1 aus.Script Path: Select the ellipsis (...* _), navigate to the _Scripts* folder, and then select the DeployToB2C.ps1 file.

    • Argumente:Arguments:

      Geben Sie als Argumente die folgenden Werte ein.Enter the following values for Arguments. Ersetzen Sie {alias-name} durch den Alias, den Sie im vorherigen Abschnitt definiert haben.Replace {alias-name} with the alias you specified in the previous section.

      # Before
      -ClientID $(clientId) -ClientSecret $(clientSecret) -TenantId $(tenantId) -PolicyId B2C_1A_TrustFrameworkBase -PathToFile $(System.DefaultWorkingDirectory)/{alias-name}/B2CAssets/TrustFrameworkBase.xml
      

      Wenn der von Ihnen definierte Alias beispielsweise policyRepo lautet, sollte die Argumentzeile wie folgt aussehen:For example, if the alias you specified is policyRepo, the argument line should be:

      # After
      -ClientID $(clientId) -ClientSecret $(clientSecret) -TenantId $(tenantId) -PolicyId B2C_1A_TrustFrameworkBase -PathToFile $(System.DefaultWorkingDirectory)/policyRepo/B2CAssets/TrustFrameworkBase.xml
      
  6. Wählen Sie Speichern aus, um den Agent-Auftrag zu speichern.Select Save to save the Agent job.

Mit dem gerade hinzugefügten Task wird eine Richtliniendatei in Azure AD B2C hochgeladen.The task you just added uploads one policy file to Azure AD B2C. Bevor Sie den Vorgang fortsetzen und weitere Tasks erstellen, sollten Sie manuell den Task auslösen (Freigabe erstellen), um sicherzustellen, dass er erfolgreich abgeschlossen wird.Before proceeding, manually trigger the job (Create release) to ensure that it completes successfully before creating additional tasks.

Wenn der Task erfolgreich abgeschlossen wird, können Sie weitere Bereitstellungstasks hinzufügen. Führen Sie dazu für jede Datei mit einer benutzerdefinierten Richtlinie die oben beschriebenen Schritte aus.If the task completes successfully, add deployment tasks by performing the preceding steps for each of the custom policy files. Ändern Sie für jede Richtlinie die Argumentwerte -PolicyId und -PathToFile.Modify the -PolicyId and -PathToFile argument values for each policy.

PolicyId ist ein Wert, der sich am Anfang jeder XML-Richtliniendatei im TrustFrameworkPolicy-Knoten befindet.The PolicyId is a value found at the start of an XML policy file within the TrustFrameworkPolicy node. Beispiel: PolicyId in der folgenden XML-Richtliniendatei lautet B2C_1A_TrustFrameworkBase:For example, the PolicyId in the following policy XML is B2C_1A_TrustFrameworkBase:

<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="contoso.onmicrosoft.com"
PolicyId= "B2C_1A_TrustFrameworkBase"
PublicPolicyUri="http://contoso.onmicrosoft.com/B2C_1A_TrustFrameworkBase">

Stellen Sie beim Ausführen der Agents und beim Hochladen der Richtliniendatei unbedingt die folgende Reihenfolge sicher:When running the agents and uploading the policy files, ensure they're uploaded in this order:

  1. TrustFrameworkBase.xmlTrustFrameworkBase.xml
  2. TrustFrameworkExtensions.xmlTrustFrameworkExtensions.xml
  3. SignUpOrSignin.xmlSignUpOrSignin.xml
  4. ProfileEdit.xmlProfileEdit.xml
  5. PasswordReset.xmlPasswordReset.xml

Das Identity Experience Framework erzwingt diese Reihenfolge, da die Dateistruktur auf einer hierarchischen Kette beruht.The Identity Experience Framework enforces this order as the file structure is built on a hierarchical chain.

Testen Ihrer PipelineTest your pipeline

So testen Sie Ihre PipelineTo test your release pipeline:

  1. Wählen Sie Pipelines und anschließend Freigaben aus.Select Pipelines and then Releases.
  2. Wählen Sie die zuvor erstellte Pipeline (z. B. DeployCustomPolicies) aus.Select the pipeline you created earlier, for example DeployCustomPolicies.
  3. Wählen Sie Freigabe erstellen und dann Erstellen aus, um die Freigabe in die Warteschlange einzureihen.Select Create release, then select Create to queue the release.

Es sollte ein Benachrichtigungsbanner mit dem Hinweis angezeigt werden, dass eine Freigabe in die Warteschlange gestellt wurde.You should see a notification banner that says that a release has been queued. Um deren Status anzuzeigen, wählen Sie den Link im Benachrichtigungsbanner oder die Freigabe in der Liste auf der Registerkarte Freigaben aus.To view its status, select the link in the notification banner, or select it in the list on the Releases tab.

Nächste SchritteNext steps

Weitere Informationen:Learn more about: