Konfigurowanie aprowizacji przy użyciu interfejsów API programu Microsoft Graph

Artykuł
04/06/2024

Centrum administracyjne firmy Microsoft Entra to wygodny sposób konfigurowania aprowizacji dla poszczególnych aplikacji jednocześnie. Jeśli jednak tworzysz kilka lub nawet setek wystąpień aplikacji lub migrujesz konfigurację aplikacji z jednego środowiska do innego, łatwiej jest zautomatyzować tworzenie i konfigurację aplikacji za pomocą interfejsów API programu Microsoft Graph. W tym artykule opisano sposób automatyzowania konfiguracji aprowizacji za pomocą interfejsów API. Ta metoda jest często używana w przypadku aplikacji, takich jak Amazon Web Services.

W tym artykule przedstawiono proces z interfejsami API w punkcie końcowym programu Microsoft Graph w wersji beta i eksploratorze programu Microsoft Graph. Podobne interfejsy API są również dostępne w punkcie końcowym programu Microsoft Graph w wersji 1.0. Aby zapoznać się z przykładem konfigurowania aprowizacji przy użyciu programu Graph w wersji 1.0 i programu PowerShell, zobacz kroki 6–13 procedury Konfigurowania synchronizacji między dzierżawami przy użyciu programu PowerShell lub interfejsu API programu Microsoft Graph.

Omówienie kroków używania interfejsów API programu Microsoft Graph do automatyzowania konfiguracji aprowizacji

Krok	Szczegóły
Krok 1. Tworzenie aplikacji galerii	Logowanie do klienta interfejsu API Pobieranie szablonu aplikacji galerii Tworzenie aplikacji galerii
Krok 2. Tworzenie zadania aprowizacji na podstawie szablonu	Pobieranie szablonu łącznika aprowizacji Tworzenie zadania aprowizacji
Krok 3. Autoryzowanie dostępu	Testowanie połączenia z aplikacją Zapisywanie poświadczeń
Krok 4. Rozpoczynanie zadania inicjowania obsługi administracyjnej	Uruchamianie zadania
Krok 5. Monitorowanie aprowizacji	Sprawdzanie stanu zadania aprowizacji Pobieranie dzienników aprowizacji

Jeśli aprowizujesz aplikację lokalną, konieczne będzie również zainstalowanie i skonfigurowanie agenta aprowizacji oraz przypisanie agenta aprowizacji do aplikacji.

Krok 1. Tworzenie aplikacji galerii

Uruchom Eksploratora programu Microsoft Graph.
Wybierz przycisk "Zaloguj się przy użyciu firmy Microsoft" i zaloguj się przy użyciu Administracja istratora globalnego firmy Microsoft lub poświadczeń usługi App Administracja.
Po pomyślnym zalogowaniu szczegóły konta użytkownika zostaną wyświetlone w okienku po lewej stronie.

Pobieranie identyfikatora szablonu aplikacji galerii

Aplikacje w galerii aplikacji Microsoft Entra mają szablon aplikacji opisujący metadane dla tej aplikacji. Za pomocą tego szablonu możesz utworzyć wystąpienie aplikacji i jednostki usługi w dzierżawie na potrzeby zarządzania. Pobierz identyfikator szablonu aplikacji dla usługi AWS Single-Account Access i z odpowiedzi zapisz wartość właściwości id do użycia w dalszej części tego samouczka.

Zażądaj

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

}

Tworzenie aplikacji galerii

Użyj identyfikatora szablonu pobranego dla aplikacji w ostatnim kroku, aby utworzyć wystąpienie aplikacji i jednostki usługi w dzierżawie.

Zażądaj

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. Tworzenie zadania aprowizacji na podstawie szablonu

Pobieranie szablonu łącznika aprowizacji

Aplikacje w galerii, które są włączone do aprowizacji, mają szablony, aby usprawnić konfigurację. Użyj poniższego żądania, aby pobrać szablon konfiguracji aprowizacji. Należy pamiętać, że musisz podać identyfikator. Identyfikator to zasób servicePrincipal utworzony w poprzednim kroku.

Zażądaj

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

Response

HTTP/1.1 200 OK

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

Tworzenie zadania aprowizacji

Aby włączyć aprowizację, najpierw musisz utworzyć zadanie. Użyj następującego żądania, aby utworzyć zadanie aprowizacji. Użyj identyfikatora templateId z poprzedniego kroku podczas określania szablonu, który ma być używany dla zadania.

Zażądaj

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. Autoryzowanie dostępu

Testowanie połączenia z aplikacją

Przetestuj połączenie z aplikacją innej firmy. Poniższy przykład dotyczy aplikacji wymagającej klucza tajnego klienta i tokenu tajnego. Każda aplikacja ma własne wymagania. Aplikacje często używają adresu podstawowego zamiast klucza tajnego klienta. Aby określić, jakich poświadczeń wymaga aplikacja, przejdź do strony konfiguracji aprowizacji dla aplikacji i w trybie dewelopera kliknij pozycję Testuj połączenie. Ruch sieciowy pokaże parametry używane dla poświadczeń. Aby uzyskać pełną listę poświadczeń, zobacz synchronizationJob: validateCredentials. Większość aplikacji, takich jak Azure Databricks, opiera się na elementach BaseAddress i SecretToken. Element BaseAddress jest określany jako adres URL dzierżawy w centrum administracyjnym firmy Microsoft Entra.

Zażądaj

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

Zapisywanie poświadczeń

Skonfigurowanie aprowizacji wymaga ustanowienia zaufania między identyfikatorem Entra firmy Microsoft i aplikacją w celu autoryzowania firmy Microsoft Entra w celu wywołania aplikacji innej firmy. Poniższy przykład jest specyficzny dla aplikacji, która wymaga wpisu tajnego klienta i tokenu tajnego. Każda aplikacja ma własne wymagania. Zapoznaj się z dokumentacją interfejsu API, aby wyświetlić dostępne opcje.

Zażądaj

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. Uruchamianie zadania aprowizacji

Po skonfigurowaniu zadania aprowizacji użyj następującego polecenia, aby uruchomić zadanie.

Zażądaj

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

Response

HTTP/1.1 204 No Content

Krok 5. Monitorowanie aprowizacji

Monitorowanie stanu zadania aprowizacji

Teraz, gdy zadanie aprowizacji jest uruchomione, użyj następującego polecenia, aby śledzić postęp. Każde zadanie synchronizacji w odpowiedzi zawiera stan bieżącego cyklu aprowizacji, a także statystyki do tej pory, takie jak liczba użytkowników i grup utworzonych w systemie docelowym.

Zażądaj

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

Monitorowanie zdarzeń aprowizacji przy użyciu dzienników aprowizacji

Oprócz monitorowania stanu zadania aprowizacji można użyć dzienników aprowizacji do wykonywania zapytań dotyczących wszystkich występujących zdarzeń. Na przykład wykonaj zapytanie dotyczące określonego użytkownika i ustal, czy zostały one pomyślnie aprowidowane.

Zażądaj

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

Konfigurowanie aprowizacji przy użyciu interfejsów API programu Microsoft Graph

Krok 1. Tworzenie aplikacji galerii

Pobieranie identyfikatora szablonu aplikacji galerii

Zażądaj

Response

Tworzenie aplikacji galerii

Zażądaj

Response

Krok 2. Tworzenie zadania aprowizacji na podstawie szablonu

Pobieranie szablonu łącznika aprowizacji

Zażądaj

Response

Tworzenie zadania aprowizacji

Zażądaj

Response

Krok 3. Autoryzowanie dostępu

Testowanie połączenia z aplikacją

Zażądaj

Response

Zapisywanie poświadczeń

Zażądaj

Response

Krok 4. Uruchamianie zadania aprowizacji

Zażądaj

Response

Krok 5. Monitorowanie aprowizacji

Monitorowanie stanu zadania aprowizacji

Zażądaj

Response

Monitorowanie zdarzeń aprowizacji przy użyciu dzienników aprowizacji

Zażądaj

Response

Zobacz też

Dodatkowe zasoby

Konfigurowanie aprowizacji przy użyciu interfejsów API programu Microsoft Graph

Krok 1. Tworzenie aplikacji galerii

Zaloguj się do eksploratora programu Microsoft Graph (zalecane), narzędzia Postman lub innego używanego klienta interfejsu API

Pobieranie identyfikatora szablonu aplikacji galerii

Zażądaj

Response

Tworzenie aplikacji galerii

Zażądaj

Response

Krok 2. Tworzenie zadania aprowizacji na podstawie szablonu

Pobieranie szablonu łącznika aprowizacji

Zażądaj

Response

Tworzenie zadania aprowizacji

Zażądaj

Response

Krok 3. Autoryzowanie dostępu

Testowanie połączenia z aplikacją

Zażądaj

Response

Zapisywanie poświadczeń

Zażądaj

Response

Krok 4. Uruchamianie zadania aprowizacji

Zażądaj

Response

Krok 5. Monitorowanie aprowizacji

Monitorowanie stanu zadania aprowizacji

Zażądaj

Response

Monitorowanie zdarzeń aprowizacji przy użyciu dzienników aprowizacji

Zażądaj

Response

Zobacz też

Dodatkowe zasoby