Automatisieren der Git-Integration mit einem Dienstprinzipal in Azure DevOps

Fabric Git Integration ist die Grundlage für Organisationen, die vollautomatisierte CI/CD-Pipelines implementieren und die nahtlose Bewegung von Ressourcen über Entwicklungs-, Test- und Produktionsumgebungen hinweg ermöglichen.

Derzeit unterstützt Fabric Git Integration zwei wichtige Git-Anbieter:

• Azure DevOps
• GitHub

Dieser Artikel konzentriert sich auf die Dienstprinzipalfunktion für Azure DevOps. Diese Integration ermöglicht es dem Fabric-Benutzer, git-Vorgänge mithilfe eines Dienstprinzipals auszuführen.

Azure DevOps: Authentifizierung – automatisch und konfiguriert

Standardmäßig ist jeder Fabric-Arbeitsbereich nicht mit einem Git-Repository verbunden. Ein Fabric-Arbeitsbereich hat zwei verschiedene Möglichkeiten, wie er sich bei einem Git-Repository authentifizieren kann. Diese Prozesse werden genannt:

• Automatische Git-Anmeldeinformationen
• Konfigurierte Anmeldeinformationen

Automatische Git-Anmeldeinformationen

Wenn ein Administratorbenutzer einen Arbeitsbereich mit einem Azure DevOps (ADO)-Repository verbinden möchte, muss sich der Benutzer zuerst über die Arbeitsbereichseinstellungen anmelden, dann identifiziert das System, auf welche ADO-Organisationen der Benutzer innerhalb des aktuellen Fabric-Mandanten zugreifen kann, sodass der Benutzer mit der Konfiguration fortfahren kann.

Sobald die erste Verbindung hergestellt wurde, muss jeder zusätzliche Benutzer mit mindestens Mitwirkendenberechtigungen für denselben Arbeitsbereich den Verbindungsprozess nicht wiederholen. Stattdessen versucht das System, den zweiten Benutzer beim konfigurierten ADO-Repository zu authentifizieren. Wenn dem Benutzer die erforderlichen Berechtigungen fehlen, zeigt der Fabric Git Integration-Quellcodeverwaltungspanel einen roten Indikator an.

Dieser optimierte Authentifizierungsprozess wird als "Automatische Git-Berechtigung" bezeichnet.

Konfigurierte Anmeldeinformationen

Mit konfigurierten Anmeldeinformationen können Sie mithilfe eines Diensthaupts programmgesteuert eine Verbindung zur Azure DevOps-Cloud herstellen.

Die Azure DevOps-Verbindung unterstützt zwei Authentifizierungsmethoden:

• OAuth 2.0
• Dienstprinzipal

Beide Methoden umfassen Unterstützung für Szenarien mit mehreren Mandanten (mandantenübergreifende Szenarien) und bieten Organisationen Flexibilität über verschiedene Umgebungen hinweg.

Andere Benutzer mit mindestens Mitwirkendenberechtigungen für denselben Arbeitsbereich müssen den Verbindungsprozess nicht wiederholen. Vor der Dienstprinzipalunterstützung hat das System versucht, sekundäre Benutzer nur über die automatische Authentifizierung zu authentifizieren.

Wenn die automatische Authentifizierung fehlschlägt, versucht das System auch, eine Verbindung mit konfigurierten Anmeldeinformationen herzustellen, auf die der Benutzer zugreifen kann, um eine reibungslosere Benutzererfahrung sicherzustellen und redundante Einrichtungsschritte zu reduzieren.

Funktionsweise

Um einen Fabric-Arbeitsbereich mit einem externen Git-Anbieter mithilfe eines Dienstprinzipals zu verbinden, muss die Git-Integration eine Fabric-Cloudverbindung vom Typ Azure DevOps – Quellcodeverwaltung verwenden.

Diese Cloudverbindung kann über das Portal auf zwei Arten erstellt werden:

• Manuell über Verwalten von Verbindungseinstellungen
• Über die Arbeitsbereichseinstellungen mit der Option 'Konto hinzufügen'

In beiden Fällen wird die Verbindung unter der Identität des angemeldeten Benutzers erstellt.

Wenn ein Dienstprinzipal diese Verbindung verwenden muss, muss der Benutzer entweder

• Die Verbindung mit dem Dienstprinzipal freigeben
• erstellen Sie eine neue Verbindung mithilfe der Connections-REST-API, und übermitteln Sie die Dienstprinzipal-Anmeldeinformationen.

In den folgenden Schritten wird beschrieben, wie Sie die API zum Erstellen der Cloudverbindung mithilfe eines Dienstprinzipals verwenden.

Voraussetzungen

Um die beschriebenen Schritte auszuführen, benötigen Sie die folgenden Berechtigungen:

• Registrieren Sie eine Entra-ID-Anwendung und beachten Sie Folgendes:

  • Mieter-ID
  • Kunden-ID
  • Geheimer Clientschlüssel

• Gewähren Sie dem Dienstprinzipal:

  • Zugriff auf die relevante Azure DevOps-Organisation und das projekt.
  • Administratorberechtigungen für den Fabric-Arbeitsbereich.

Neuen Arbeitsbereich mithilfe eines Service Principals mit Azure DevOps verbinden

Zum programmgesteuerten Verbinden eines Fabric-Arbeitsbereichs mit Azure DevOps mithilfe des Dienstprinzipals müssen die folgenden Schritte ausgeführt werden:

1. Dienstprinzipalzugriffstoken generieren: Authentifiziert sich mit Microsoft Fabric mithilfe eines Dienstprinzipals.
2. Erstellen Sie die Azure DevOps-Cloudverbindung: Erstellt eine neue Verbindungsressource in Microsoft Fabric, die die Anmeldeinformationen und die Konfiguration des Azure DevOps-Repositorys speichert.
3. Arbeitsbereich mit Git verbinden: Verknüpft einen bestimmten Fabric-Arbeitsbereich mit dem Azure DevOps-Repository mithilfe der in Schritt 2 erstellten Verbindung.
4. Verbindung initialisieren: Initialisiert die Git-Verbindung.

1. Generieren des Dienstprinzipalzugriffstokens

Die folgenden Beispiele zeigen, wie das Dienstprinzipalzugriffstoken generiert wird.

curl --request GET \ 
--url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \ 
--header 'content-type: multipart/form-data' \ 
--form grant_type=client_credentials \ 
--form client_id=<client-id> \ 
--form 'client_secret=<client-secret>' \ 
--form scope=https://api.fabric.microsoft.com/.default 

2. Erstellen einer Azure DevOps-Cloudverbindung

Erstellt eine neue Verbindungsressource in Microsoft Fabric, die die Anmeldeinformationen und Die Konfiguration des Azure DevOps-Repositorys speichert.

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 

"displayName": "<name of the connection>", 
"connectivityType": "ShareableCloud", 
"connectionDetails": { 
"creationMethod": "AzureDevOpsSourceControl.Contents", 
"type": "AzureDevOpsSourceControl", 
"parameters": [ 

{ 
"dataType": "Text", 
"name": "url", 
"value": "https://dev.azure.com/<ado org name>/<project name>/_git/<repo name>/"}]}, 
"credentialDetails": { 
"credentials": { 
"credentialType": "ServicePrincipal", 
"tenantId": "<tenant-id>", 
"servicePrincipalClientId": "<client-id>", 
"servicePrincipalSecret": "<client-secret>"}}}' 

3. Verbinden des Arbeitsbereichs mit Git

Verknüpft einen bestimmten Fabric-Arbeitsbereich mit dem Azure DevOps-Repository mithilfe der in Schritt 2 erstellten Verbindung.

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/connect \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"gitProviderDetails": { 
"organizationName": "<ado org name>", 
"projectName": "<project name>", 
"gitProviderType": "AzureDevOps", 
"repositoryName": "<repo name>", 
"branchName": "<branch name>", 
"directoryName": "<folder name – must exist before OR empty>" 
}, 
"myGitCredentials": { 
"source": "ConfiguredConnection", 
"connectionId": "<step 2 – the new connection id>"}}' 

4. Initialisieren der Verbindung

Initialisieren Sie die Verbindung, lesen Sie hier mehr.

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/initializeConnection \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{"initializationStrategy": "PreferRemote"}' 

Wenn das Repository /workspace nicht leer ist, nutzen Sie den requiredAction-Parameter (der auf Ihrer InitializationStrategy basiert), um update-from-git ODER commit-to-git entsprechend mit workspaceHead und remoteCommitHash aus der Antwort zu verwenden, um den Prozess abzuschließen.

Vorhandenen Arbeitsbereich verbinden, um Dienstprinzipal zu verwenden

Wenn Ihr Arbeitsbereich bereits mit Azure DevOps über eine Benutzeridentität verbunden ist, Sie jedoch Fabric Git REST-API-Vorgänge mit einem Dienstprinzipal ausführen möchten, führen Sie die folgenden Schritte aus:

1. Dienstprinzipal als Arbeitsbereichsadministrator hinzufügen.
2. Gewähren Sie dem Dienstprinzipal Zugriff auf die Azure DevOps Cloud-Verbindung. Sie haben zwei Möglichkeiten:

• Freigeben einer vorhandenen Verbindung: Melden Sie sich mit einem Benutzer an, der Zugriff auf die relevante ADO-Cloudverbindung hat, und teilen Sie diese anschließend über „Benutzer verwalten“ mit dem Dienstprinzipal.
• Erstellen sie eine neue Verbindung: Wiederholen Sie die Schritte 1 und 2 aus dem vorherigen Abschnitt, um eine neue Cloudverbindung mithilfe von Dienstprinzipalanmeldeinformationen zu erstellen.

3. Überprüfen Sie den Zugriff – Rufen Sie die GET Connections-API auf, um zu bestätigen, dass der Dienstprinzipal hier auf die erforderliche Cloudverbindung zugreifen kann:

curl --request GET \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step 2: access-token>' 

Rufen Sie den ID-Wert der relevanten Verbindung aus der Antwort ab.

4. Aktualisieren Sie Git-Anmeldeinformationen: Generieren Sie ein Zugriffstoken (Schritt 1 aus dem vorherigen Abschnitt), und rufen Sie die API "Meine Git-Anmeldeinformationen aktualisieren" auf, lesen Sie hier mehr (Ersetzen sie <> durch Ihre Werte):

curl --request PATCH \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/myGitCredentials \ 
--header 'authorization: Bearer <step 2: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"source": "ConfiguredConnection", 
"connectionId": "<step 3: connection id>"}' 

Nach diesen Schritten ist der Dienstprinzipal vollständig konfiguriert und kann Fabric Git REST-API-Vorgänge ausführen.

Verwandte Inhalte

• Automatisieren der Git-Integration mithilfe von APIs
• Manuelle Git-Integration mit einem Dienstprinzipal in Azure DevOps
• Grundlegendes zum Git-Integrationsprozess
• Verwalten von Git-Branches
• Bewährte Methoden für die Git-Integration