Bagikan melalui

Mengonfigurasi provisi menggunakan Microsoft Graph API

  • Artikel

Pusat admin Microsoft Entra adalah cara mudah untuk mengonfigurasi provisi untuk aplikasi individual satu per satu. Tetapi jika Anda membuat beberapa—atau bahkan ratusan—instans aplikasi, atau memigrasikan konfigurasi aplikasi dari satu lingkungan ke lingkungan lain, akan lebih mudah untuk mengotomatiskan pembuatan dan konfigurasi aplikasi dengan API Microsoft Graph. Artikel ini menguraikan cara mengotomatisasi konfigurasi penyediaan melalui API. Metode ini biasanya digunakan untuk aplikasi seperti Amazon Web Services.

Artikel ini mengilustrasikan proses dengan API di titik akhir beta Microsoft Graph dan Microsoft Graph Explorer; API serupa juga tersedia di titik akhir Microsoft Graph v1.0. Untuk contoh mengonfigurasi provisi dengan Graph v1.0 dan PowerShell, lihat langkah 6-13 mengonfigurasi sinkronisasi lintas penyewa menggunakan PowerShell atau Microsoft Graph API.

Gambaran umum langkah-langkah untuk menggunakan API Microsoft Graph untuk mengotomatiskan konfigurasi penyediaan

Langkah Detail
Langkah 1. Membuat aplikasi galeri Masuk ke klien API
Mengambil templat aplikasi galeri
Membuat aplikasi galeri
Langkah 2. Membuat pekerjaan penyediaan berdasarkan templat Mengambil templat untuk konektor provisi
Buat pekerjaan penyediaan
Langkah 3. Otorisasi akses Menguji koneksi ke aplikasi
Simpan kredensial
Langkah 4. Mulai provisi Mulai pekerjaan
Langkah 5. Pantau penyediaan Periksa status pekerjaan provisi
Ambil log penyediaan

Jika Anda memprovisikan ke aplikasi lokal, maka Anda juga perlu menginstal dan mengonfigurasi agen provisi, dan menetapkan agen provisi ke aplikasi.

  1. Mulai Microsoft Graph Explorer.
  2. Pilih tombol "Masuk dengan Microsoft" dan masuk dengan pengguna dengan peran Administrator Aplikasi.
  3. Setelah berhasil masuk, Anda akan melihat detail akun pengguna di panel sebelah kiri.

Aplikasi di galeri aplikasi Microsoft Entra masing-masing memiliki templat aplikasi yang menjelaskan metadata untuk aplikasi tersebut. Dengan menggunakan templat ini, Anda dapat membuat contoh aplikasi dan prinsip layanan di penyewa Anda untuk manajemen. Mengambil pengidentifikasi untuk templat aplikasi untuk Akses Akun Tunggal AWS dan dari respon, catat nilai dari properti id untuk digunakan nanti dalam tutorial ini.

Permintaan

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

Respons

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

}

Gunakan ID templat yang diambil untuk aplikasi Anda pada langkah terakhir untuk membuat instans aplikasi dan perwakilan layanan di penyewa Anda.

Permintaan

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

{
  "displayName": "AWS Contoso"
}

Respons

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

Langkah 2. Membuat pekerjaan penyediaan berdasarkan templat

Mengambil templat untuk konektor penyediaan

Aplikasi di galeri yang diaktifkan untuk penyediaan memiliki templat untuk mengalirkan konfigurasi. Gunakan permintaan di bawah ini untuk mengambil templat untuk konfigurasi penyediaan. Perhatikan bahwa Anda harus memberikan ID. ID adalah sumber daya servicePrincipal, yang dibuat pada langkah sebelumnya.

Permintaan

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

Respons

HTTP/1.1 200 OK

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

Buat pekerjaan penyediaan

Untuk mengaktifkan penyediaan, Anda harus terlebih dahulu membuat pekerjaan. Gunakan permintaan berikut untuk membuat pekerjaan penyediaan. Gunakan templateId dari langkah sebelumnya saat menentukan templat yang akan digunakan untuk pekerjaan tersebut.

Permintaan

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

{ 
    "templateId": "aws"
}

Respons

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

Langkah 3. Mengotorisasi akses

Uji koneksi ke aplikasi

Uji koneksi dengan aplikasi pihak ketiga. Contoh berikut adalah untuk aplikasi yang memerlukan rahasia klien dan token rahasia. Setiap aplikasi memiliki persyaratan tersendiri. Aplikasi sering menggunakan alamat dasar sebagai tempat rahasia klien. Untuk menentukan kredensial apa yang diperlukan aplikasi Anda, buka halaman konfigurasi penyediaan untuk aplikasi Anda, dan dalam mode pengembang, klik koneksi uji. Lalu lintas jaringan akan menunjukkan parameter yang digunakan untuk kredensial. Untuk daftar lengkap kredensial, lihat synchronizationJob: validateCredentials. Sebagian besar aplikasi, seperti Azure Databricks, mengandalkan BaseAddress dan SecretToken. BaseAddress disebut sebagai URL penyewa di pusat admin Microsoft Entra.

Permintaan

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

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

Respons

HTTP/1.1 204 No Content

Simpan kredensial Anda

Mengonfigurasi provisi mengharuskan membangun kepercayaan antara MICROSOFT Entra ID dan aplikasi untuk mengotorisasi Microsoft Entra agar memiliki kemampuan untuk memanggil aplikasi pihak ketiga. Contoh berikut khusus untuk aplikasi yang memerlukan rahasia klien dan token rahasia. Setiap aplikasi memiliki persyaratan tersendiri. Tinjau dokumentasi API untuk melihat opsi yang tersedia.

Permintaan

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

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

Respons

HTTP/1.1 204 No Content

Langkah 4: Mulai pekerjaan penyediaan

Sekarang setelah pekerjaan penyediaan dikonfigurasi, gunakan perintah berikut untuk memulai pekerjaan.

Permintaan

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

Respons

HTTP/1.1 204 No Content

Langkah 5. Pantau penyediaan

Memantau status pekerjaan penyediaan

Sekarang setelah pekerjaan provisi berjalan, gunakan perintah berikut untuk melacak kemajuan. Setiap pekerjaan sinkronisasi dalam respons mencakup status siklus provisi saat ini serta statistik hingga saat ini seperti jumlah pengguna dan grup yang telah dibuat dalam sistem target.

Permintaan

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

Respons

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

Memantau kejadian penyediaan menggunakan log penyediaan

Selain memantau status pekerjaan penyediaan, Anda dapat menggunakan log penyediaan untuk membuat kueri semua peristiwa yang terjadi. Misalnya, kueri untuk pengguna tertentu dan menentukan apakah pengguna berhasil disediakan.

Permintaan

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

Respons

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

Lihat juga