Konfigurace zřizování pomocí rozhraní Microsoft Graph API

Článek
04/06/2024

Centrum pro správu Microsoft Entra představuje pohodlný způsob konfigurace zřizování pro jednotlivé aplikace po jednom. Pokud ale vytváříte několik instancí aplikace nebo dokonce stovky instancí aplikace nebo migrujete konfiguraci aplikace z jednoho prostředí do jiného, může být snazší automatizovat vytváření a konfiguraci aplikací pomocí rozhraní Microsoft Graph API. Tento článek popisuje, jak automatizovat konfiguraci zřizování prostřednictvím rozhraní API. Tato metoda se běžně používá pro aplikace, jako je Amazon Web Services.

Tento článek ukazuje proces s rozhraními API v koncovém bodu beta verze Microsoft Graphu a v Microsoft Graph Exploreru. Podobná rozhraní API jsou k dispozici také v koncovém bodu Microsoft Graph v1.0. Příklad konfigurace zřizování pomocí Graphu v1.0 a PowerShellu najdete v krocích 6 až 13 konfigurace synchronizace mezi tenanty pomocí PowerShellu nebo rozhraní Microsoft Graph API.

Přehled kroků pro použití rozhraní Microsoft Graph API k automatizaci konfigurace zřizování

Krok	Detaily
Krok 1. Vytvoření aplikace galerie	Přihlášení k klientovi rozhraní API Načtení šablony aplikace galerie Vytvoření aplikace galerie
Krok 2. Vytvoření úlohy zřizování na základě šablony	Načtení šablony pro konektor zřizování Vytvoření úlohy zřizování
Krok 3. Autorizace přístupu	Otestování připojení k aplikaci Uložení přihlašovacích údajů
Krok 4. Zahájení úlohy zřizování	Spuštění úlohy
Krok 5. Monitorování zřizování	Kontrola stavu úlohy zřizování Načtení protokolů zřizování

Pokud zřizujete pro místní aplikaci, budete také muset nainstalovat a nakonfigurovat agenta zřizování a přiřadit agenta zřizování k aplikaci.

Krok 1: Vytvoření aplikace galerie

Spusťte Microsoft Graph Explorer.
Vyberte tlačítko Přihlásit se microsoftem a přihlaste se pomocí globálního Správa istratoru Microsoftu nebo aplikace Správa přihlašovacích údajů.
Po úspěšném přihlášení se v levém podokně zobrazí podrobnosti uživatelského účtu.

Načtení identifikátoru šablony aplikace galerie

Aplikace v galerii aplikací Microsoft Entra mají šablonu aplikace, která popisuje metadata pro danou aplikaci. Pomocí této šablony můžete vytvořit instanci aplikace a instančního objektu ve vašem tenantovi pro správu. Načtěte identifikátor šablony aplikace pro přístup k jednoúčelovým účtům AWS a z odpovědi si poznamenejte hodnotu vlastnosti ID , kterou chcete použít později v tomto kurzu.

Požádat

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

Response

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

}

Vytvoření aplikace galerie

Id šablony načtené pro vaši aplikaci v posledním kroku použijte k vytvoření instance aplikace a instančního objektu ve vašem tenantovi.

Požádat

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

{
  "displayName": "AWS Contoso"
}

Response

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"
        ],
    }
}

Krok 2: Vytvoření úlohy zřizování na základě šablony

Načtení šablony pro konektor zřizování

Aplikace v galerii, které jsou povolené pro zřizování, mají šablony pro zjednodušení konfigurace. Pomocí následujícího požadavku načtěte šablonu pro konfiguraci zřizování. Nezapomeňte, že budete muset zadat ID. ID je prostředek servicePrincipal vytvořený v předchozím kroku.

Požádat

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

Response

HTTP/1.1 200 OK

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

Vytvoření úlohy zřizování

Pokud chcete povolit zřizování, musíte nejprve vytvořit úlohu. Pomocí následujícího požadavku vytvořte úlohu zřizování. Při zadávání šablony, která se má pro úlohu použít, použijte id šablony z předchozího kroku.

Požádat

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

{ 
    "templateId": "aws"
}

Response

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
    }
}

Krok 3: Autorizace přístupu

Otestování připojení k aplikaci

Otestujte připojení k aplikaci třetí strany. Následující příklad je určený pro aplikaci, která vyžaduje tajný klíč klienta a token tajného klíče. Každá aplikace má vlastní požadavky. Aplikace často používají základní adresu místo tajného klíče klienta. Pokud chcete zjistit, jaké přihlašovací údaje vaše aplikace vyžaduje, přejděte na stránku konfigurace zřizování aplikace a v režimu vývojáře klikněte na testovací připojení. Síťový provoz zobrazí parametry použité pro přihlašovací údaje. Úplný seznam přihlašovacích údajů najdete v tématu synchronizationJob: validateCredentials. Většina aplikací, jako je Azure Databricks, spoléhá na BaseAddress a SecretToken. BaseAddress se v Centru pro správu Microsoft Entra označuje jako adresa URL tenanta.

Požádat

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

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

Response

HTTP/1.1 204 No Content

Uložení přihlašovacích údajů

Konfigurace zřizování vyžaduje navázání vztahu důvěryhodnosti mezi ID Microsoft Entra a aplikací k autorizaci Microsoft Entra, aby měla možnost volat aplikaci třetí strany. Následující příklad je specifický pro aplikaci, která vyžaduje tajný klíč klienta a token tajného kódu. Každá aplikace má vlastní požadavky. Projděte si dokumentaci k rozhraní API a podívejte se na dostupné možnosti.

Požádat

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

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

Response

HTTP/1.1 204 No Content

Krok 4: Spuštění úlohy zřizování

Teď, když je úloha zřizování nakonfigurovaná, spusťte úlohu pomocí následujícího příkazu.

Požádat

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

Response

HTTP/1.1 204 No Content

Krok 5: Monitorování zřizování

Monitorování stavu úlohy zřizování

Teď, když je úloha zřizování spuštěná, sledujte průběh pomocí následujícího příkazu. Každá úloha synchronizace v odpovědi zahrnuje stav aktuálního cyklu zřizování a statistiky k datu, například počet uživatelů a skupin vytvořených v cílovém systému.

Požádat

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

Response

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"
      }
    ]
}
]
}

Monitorování událostí zřizování pomocí protokolů zřizování

Kromě monitorování stavu úlohy zřizování můžete protokoly zřizování použít k dotazování na všechny události, ke kterým dochází. Zadejte například dotaz na konkrétního uživatele a určete, jestli se úspěšně zřídil.

Požádat

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

Response

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"
            }
            ]
       }
    ]
}

Konfigurace zřizování pomocí rozhraní Microsoft Graph API

Krok 1: Vytvoření aplikace galerie

Načtení identifikátoru šablony aplikace galerie

Požádat

Response

Vytvoření aplikace galerie

Požádat

Response

Krok 2: Vytvoření úlohy zřizování na základě šablony

Načtení šablony pro konektor zřizování

Požádat

Response

Vytvoření úlohy zřizování

Požádat

Response

Krok 3: Autorizace přístupu

Otestování připojení k aplikaci

Požádat

Response

Uložení přihlašovacích údajů

Požádat

Response

Krok 4: Spuštění úlohy zřizování

Požádat

Response

Krok 5: Monitorování zřizování

Monitorování stavu úlohy zřizování

Požádat

Response

Monitorování událostí zřizování pomocí protokolů zřizování

Požádat

Response

Viz také

Další materiály

Konfigurace zřizování pomocí rozhraní Microsoft Graph API

Krok 1: Vytvoření aplikace galerie

Přihlaste se k Microsoft Graph Exploreru (doporučeno), Postmanu nebo jinému klientovi rozhraní API, kterého používáte

Načtení identifikátoru šablony aplikace galerie

Požádat

Response

Vytvoření aplikace galerie

Požádat

Response

Krok 2: Vytvoření úlohy zřizování na základě šablony

Načtení šablony pro konektor zřizování

Požádat

Response

Vytvoření úlohy zřizování

Požádat

Response

Krok 3: Autorizace přístupu

Otestování připojení k aplikaci

Požádat

Response

Uložení přihlašovacích údajů

Požádat

Response

Krok 4: Spuštění úlohy zřizování

Požádat

Response

Krok 5: Monitorování zřizování

Monitorování stavu úlohy zřizování

Požádat

Response

Monitorování událostí zřizování pomocí protokolů zřizování

Požádat

Response

Viz také

Další materiály