Konfigurieren der Bereitstellung mithilfe von Microsoft Graph-APIs

  • Artikel

Das Microsoft Entra Admin Center bietet eine bequeme Möglichkeit, die Bereitstellung für einzelne Apps einzeln zu konfigurieren. Wenn Sie jedoch mehrere – oder sogar Hunderte – Instanzen einer Anwendung erstellen oder eine Anwendungskonfiguration zwischen Umgebungen migrieren, kann es einfacher sein, die App-Erstellung und -Konfiguration mithilfe der Microsoft Graph-APIs zu automatisieren. In diesem Artikel wird beschrieben, wie Sie die Bereitstellungskonfiguration über APIs automatisieren. Dieses Verfahren wird häufig für Anwendungen wie Amazon Web Services verwendet.

In diesem Artikel wird der Prozess mit APIs am Microsoft Graph-Betaendpunkt und dem Microsoft Graph-Tester veranschaulicht. Ähnliche APIs sind auch am Microsoft Graph v1.0-Endpunkt verfügbar. Ein Beispiel für die Konfiguration der Bereitstellung mit Graph v1.0 und PowerShell finden Sie in den Schritten 6–13 zur Konfiguration der mandantenübergreifenden Synchronisierung mithilfe von PowerShell oder der Microsoft Graph-API.

Übersicht über die Schritte zum Automatisieren der Bereitstellungskonfiguration mithilfe von Microsoft Graph-APIs

Schritt Details
Schritt 1: Erstellen der Kataloganwendung Anmelden beim API-Client
Abrufen der Kataloganwendungsvorlage
Erstellen der Kataloganwendung
Schritt 2: Erstellen eines Bereitstellungsauftrags basierend auf der Vorlage Abrufen der Vorlage für den Bereitstellungsconnector
Erstellen des Bereitstellungsauftrags
Schritt 3: Autorisieren des Zugriffs Testen der Verbindung mit der Anwendung
Speichern der Anmeldeinformationen
Schritt 4. Starten des Bereitstellungsauftrags Starten des Auftrags
Schritt 5: Überwachen der Bereitstellung Überprüfen des Status des Bereitstellungsauftrags
Abrufen der Bereitstellungsprotokolle

Wenn Sie eine lokale Anwendung bereitstellen, müssen Sie auch den Bereitstellungs-Agent installieren und konfigurieren und ihn der Anwendung zuweisen.

  1. Öffnen Sie den Microsoft Graph-Tester.
  2. Wählen Sie die Schaltfläche „Mit Microsoft anmelden“ aus, und melden Sie sich mit den Anmeldeinformationen für den globalen Microsoft Entra-Administrator oder mit den Anmeldeinformationen für den App-Administrator an.
  3. Nach der erfolgreichen Anmeldung werden im linken Bereich die Details des Benutzerkontos angezeigt.

Anwendungen im Microsoft Entra-Anwendungskatalog verfügen jeweils über eine Anwendungsvorlage, in der die Metadaten für die Anwendung beschrieben werden. Mithilfe dieser Vorlage können Sie im Mandanten für die Verwaltung eine Instanz der Anwendung und des Dienstprinzipals erstellen. Rufen Sie den Bezeichner der Anwendungsvorlage für AWS Single-Account Access ab, und notieren Sie sich den Wert der Eigenschaft id aus der Antwort zur späteren Verwendung in diesem Tutorial.

Anforderung

GET https://graph.microsoft.com/beta/applicationTemplates?$filter=displayName eq 'AWS Single-Account Access'

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
  {
    "id": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Single-Account Access",
        "homePageUrl": "http://aws.amazon.com/",
        "supportedSingleSignOnModes": [
             "password",
             "saml",
             "external"
         ],
         "supportedProvisioningTypes": [
             "sync"
         ],
         "logoUrl": "https://az495088.vo.msecnd.net/app-logo/aws_215.png",
         "categories": [
             "developerServices"
         ],
         "publisher": "Amazon",
         "description": "Federate to a single AWS account and use SAML claims to authorize access to AWS IAM roles. If you have many AWS accounts, consider using the AWS Single Sign-On gallery application instead."    

}

Verwenden Sie die Vorlagen-ID, die Sie im letzten Schritt für die Anwendung abgerufen haben, um im Mandanten eine Instanz der Anwendung und des Dienstprinzipals zu erstellen.

Anforderung

POST https://graph.microsoft.com/beta/applicationTemplates/{applicationTemplateId}/instantiate
Content-type: application/json

{
  "displayName": "AWS Contoso"
}

Antwort

HTTP/1.1 201 OK
Content-type: application/json

{
    "application": {
        "objectId": "cbc071a6-0fa5-4859-8g55-e983ef63df63",
        "appId": "92653dd4-aa3a-3323-80cf-e8cfefcc8d5d",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "displayName": "AWS Contoso",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "logoutUrl": null,
        "samlMetadataUrl": null,
    },
    "servicePrincipal": {
        "objectId": "f47a6776-bca7-4f2e-bc6c-eec59d058e3e",
        "appDisplayName": "AWS Contoso",
        "applicationTemplateId": "8b1025e4-1dd2-430b-a150-2ef79cd700f5",
        "appRoleAssignmentRequired": true,
        "displayName": "My custom name",
        "homepage": "https://signin.aws.amazon.com/saml?metadata=aws|ISV9.1|primary|z",
        "replyUrls": [
            "https://signin.aws.amazon.com/saml"
        ],
        "servicePrincipalNames": [
            "93653dd4-aa3a-4323-80cf-e8cfefcc8d7d"
        ],
        "tags": [
            "WindowsAzureActiveDirectoryIntegratedApp"
        ],
    }
}

Schritt 2: Erstellen des Bereitstellungsauftrags basierend auf der Vorlage

Abrufen der Vorlage für den Bereitstellungsconnector

Anwendungen im Katalog, die für die Bereitstellung aktiviert sind, verfügen über Vorlagen zum Optimieren der Konfiguration. Verwenden Sie die nachstehende Anforderung, um die Vorlage für die Bereitstellungskonfiguration abzurufen. Beachten Sie, dass Sie die ID angeben müssen. Die ID ist die der servicePrincipal-Ressource, die im vorherigen Schritt erstellt wurde.

Anfordern

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/templates

Antwort

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "aws",
            "factoryTag": "aws",
            "schema": {
                    "directories": [],
                    "synchronizationRules": []
                    }
        }
    ]
}

Erstellen des Bereitstellungsauftrags

Um die Bereitstellung zu ermöglichen, müssen Sie zunächst einen Auftrag erstellen. Verwenden Sie die nachstehende Anforderung, um einen Bereitstellungsauftrag zu erstellen. Verwenden Sie die „templateId“ aus dem vorherigen Schritt, wenn Sie die Vorlage angeben, die für den Auftrag verwendet werden soll.

Anforderung

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
Content-type: application/json

{ 
    "templateId": "aws"
}

Antwort

HTTP/1.1 201 OK
Content-type: application/json

{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "NotConfigured",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    }
}

Schritt 3: Autorisieren des Zugriffs

Testen der Verbindung mit der Anwendung

Testen Sie die Verbindung mit der Drittanbieteranwendung. Das folgende Beispiel gilt für eine Anwendung, die einen geheimen Clientschlüssel und ein geheimes Token erfordert. Jede Anwendung verfügt über eigene Anforderungen. Anwendungen verwenden häufig eine Basisadresse anstelle eines geheimen Clientschlüssels. Um festzustellen, welche Anmeldeinformationen für Ihre App erforderlich sind, navigieren Sie zur Seite der Bereitstellungskonfiguration für Ihre Anwendung, und klicken Sie im Entwicklermodus auf Verbindung testen. Unter „Netzwerkdatenverkehr“ werden die Parameter gezeigt, die als Anmeldeinformationen verwendet werden. Eine vollständige Liste der Anmeldeinformationen finden Sie unter synchronizationJob: validateCredentials. Die meisten Anwendungen, z. B. Azure Databricks, verwenden eine BaseAddress und ein SecretToken. Der BaseAddress-Wert wird im Microsoft Entra Admin Center als Mandanten-URL bezeichnet.

Anforderung

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/validateCredentials

{ 
    "credentials": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx" 
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Antwort

HTTP/1.1 204 No Content

Speichern Ihrer Anmeldeinformationen

Für die Konfiguration der Bereitstellung muss eine Vertrauensstellung zwischen Microsoft Entra ID und der Anwendung eingerichtet werden, um Microsoft Entra zu autorisieren, eine Anwendung von Drittanbietern aufzurufen. Das folgende Beispiel gilt speziell für eine Anwendung, die einen geheimen Clientschlüssel und ein geheimes Token erfordert. Jede Anwendung verfügt über eigene Anforderungen. Die verfügbaren Optionen finden Sie in der API-Dokumentation.

Anforderung

PUT https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

{ 
    "value": [ 
        { 
            "key": "ClientSecret", "value": "xxxxxxxxxxxxxxxxxxxxx"
        },
        {
            "key": "SecretToken", "value": "xxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

Antwort

HTTP/1.1 204 No Content

Schritt 4: Starten des Bereitstellungsauftrags

Nachdem der Bereitstellungsauftrag konfiguriert wurde, verwenden Sie den folgenden Befehl, um den Auftrag zu starten.

Anforderung

POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/start

Antwort

HTTP/1.1 204 No Content

Schritt 5: Überwachen der Bereitstellung

Überwachen des Status des Bereitstellungsauftrags

Nachdem der Bereitstellungsauftrag nun ausgeführt wird, verwenden Sie den folgenden Befehl, um den Fortschritt nachzuverfolgen. Jeder Synchronisierungsauftrag in der Antwort schließt den Status des aktuellen Bereitstellungszyklus sowie die bisherigen Statistiken ein, z. B. die Anzahl der Benutzer*innen und Gruppen, die im Zielsystem erstellt wurden.

Anfordern

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{ "value": [
{
    "id": "{jobId}",
    "templateId": "aws",
    "schedule": {
        "expiration": null,
        "interval": "P10675199DT2H48M5.4775807S",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "synchronizedEntryCountByType": [],
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "progress": [],
        "lastSuccessfulExecutionWithExports": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "quarantine": null,
        "troubleshootingUrl": null
    },
    "synchronizationJobSettings": [
      {
          "name": "QuarantineTooManyDeletesThreshold",
          "value": "500"
      }
    ]
}
]
}

Überwachen von Bereitstellungsereignissen mithilfe der Bereitstellungsprotokolle

Zusätzlich zur Überwachung des Status des Bereitstellungsauftrags können Sie über die Bereitstellungsprotokolle alle auftretenden Ereignisse abfragen. Sie können beispielsweise einen bestimmten Benutzer abfragen, um zu ermitteln, ob dieser erfolgreich bereitgestellt wurde.

Anforderung

GET https://graph.microsoft.com/beta/auditLogs/provisioning

Antwort

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#auditLogs/provisioning",
    "value": [
        {
            "id": "gc532ff9-r265-ec76-861e-42e2970a8218",
            "activityDateTime": "2019-06-24T20:53:08Z",
            "tenantId": "7928d5b5-7442-4a97-ne2d-66f9j9972ecn",
            "cycleId": "44576n58-v14b-70fj-8404-3d22tt46ed93",
            "changeId": "eaad2f8b-e6e3-409b-83bd-e4e2e57177d5",
            "action": "Create",
            "durationInMilliseconds": 2785,
            "sourceSystem": {
                "id": "0404601d-a9c0-4ec7-bbcd-02660120d8c9",
                "displayName": "Azure Active Directory",
                "details": {}
            },
            "targetSystem": {
                "id": "cd22f60b-5f2d-1adg-adb4-76ef31db996b",
                "displayName": "AWS Contoso",
                "details": {
                    "ApplicationId": "f2764360-e0ec-5676-711e-cd6fc0d4dd61",
                    "ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
                    "ServicePrincipalDisplayName": "AWS Contoso"
                }
            },
            "initiatedBy": {
                "id": "",
                "displayName": "Azure AD Provisioning Service",
                "initiatorType": "system"
            }
            ]
       }
    ]
}

Siehe auch