Konfigurieren der Bereitstellung mithilfe von Microsoft Graph-APIs
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.
Schritt 1: Erstellen der Kataloganwendung
Melden Sie sich bei Microsoft Graph Explorer (empfohlen) oder einem anderen von Ihnen verwendeten API-Client an
- Öffnen Sie den Microsoft Graph-Tester.
- Wählen Sie die Schaltfläche „Mit Microsoft anmelden“ aus, und melden Sie sich mit einem Benutzerkonto an, das über die Rolle Anwendungsadministrator verfügt.
- Nach der erfolgreichen Anmeldung werden im linken Bereich die Details des Benutzerkontos angezeigt.
Abrufen des Bezeichners für die Kataloganwendungsvorlage
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."
}
Erstellen der Kataloganwendung
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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"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": "bbbbbbbb-1111-2222-3333-cccccccccccc",
"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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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": "00001111-aaaa-2222-bbbb-3333cccc4444",
"ServicePrincipalId": "chc46a42-966b-47d7-9774-576b1c8bd0b8",
"ServicePrincipalDisplayName": "AWS Contoso"
}
},
"initiatedBy": {
"id": "",
"displayName": "Azure AD Provisioning Service",
"initiatorType": "system"
}
]
}
]
}