Tutorial: Mengembangkan dan merencanakan penyediaan untuk titik akhir SCIM di Azure Active Directory

Sebagai pengembang aplikasi, Anda dapat menggunakan API manajemen pengguna System for Cross-Domain Identity Management (SCIM) untuk mengaktifkan penyediaan otomatis pengguna dan grup antara aplikasi Anda dan Azure Active Directory (Azure AD). Artikel ini menjelaskan tentang cara membuat titik akhir SCIM dan berintegrasi dengan layanan penyediaan Azure AD. Spesifikasi SCIM menyediakan skema pengguna umum untuk penyediaan. Saat digunakan bersama dengan standar federasi seperti SAML atau OpenID Connect, SCIM memberi administrator solusi berbasis standar yang menyeluruh untuk manajemen akses.

Penyediaan dari Azure AD ke aplikasi dengan SCIM

SCIM 2.0 adalah definisi standar dari dua titik akhir: titik akhir /Users dan titik akhir /Groups. Ia menggunakan titik akhir REST API umum untuk membuat, memperbarui, dan menghapus objek. SCIM terdiri dari skema yang telah ditentukan sebelumnya untuk atribut umum seperti nama grup, nama pengguna, nama depan, nama belakang, dan email.

Aplikasi yang menawarkan SCIM 2.0 REST API dapat mengurangi atau menghilangkan rasa tidak nyaman bekerja dengan API manajemen pengguna yang eksklusif. Misalnya, klien SCIM yang patuh tahu cara membuat POSTING HTTP objek JSON ke /Users titik akhir untuk membuat entri pengguna baru. Alih-alih membutuhkan API yang sedikit berbeda untuk tindakan dasar yang sama, aplikasi yang sesuai dengan standar SCIM dapat langsung memanfaatkan klien, alat, dan kode yang sudah ada sebelumnya.

Skema objek pengguna standar dan rest API untuk manajemen yang ditentukan dalam SCIM 2.0 (RFC 7642, 7643, 7644) memungkinkan penyedia identitas dan aplikasi untuk lebih mudah berintegrasi satu sama lain. Pengembang aplikasi yang membangun titik akhir SCIM dapat berintegrasi dengan klien yang mematuhi SCIM tanpa harus melakukan pekerjaan kustom.

Untuk mengotomatiskan provisi ke aplikasi, ia perlu membangun dan mengintegrasikan titik akhir SCIM yang diakses oleh Layanan Provisi Azure AD. Gunakan langkah-langkah berikut untuk mulai menyediakan pengguna dan grup ke dalam aplikasi Anda.

  1. Desain skema grup dan pengguna Anda - Lakukan identifikasi terhadap objek dan atribut aplikasi untuk menentukan cara mereka memetakan ke skema grup dan pengguna yang didukung oleh implementasi SCIM Azure AD.

  2. Pahami implementasi SCIM Azure AD - Pahami cara Layanan Provisi Azure AD diterapkan untuk membuat model respons dan penanganan permintaan protokol SCIM Anda.

  3. Bangun titik akhir SCIM - Titik akhir harus kompatibel dengan SCIM 2.0 agar dapat terintegrasi dengan layanan provisi Azure AD. Sebagai opsi, gunakan pustaka Microsoft Common Language Infrastructure (CLI) dan sampel kode untuk menyusun titik akhir Anda. Sampel ini hanya untuk referensi dan pengujian; kami menyarankan untuk tidak menggunakannya sebagai dependensi di aplikasi produksi Anda.

  4. Integrasikan titik akhir SCIM Anda dengan Layanan Provisi Azure AD. Jika organisasi Anda menggunakan aplikasi pihak ketiga untuk mengimplementasikan profil SCIM 2.0 yang didukung Azure AD, Anda dapat dengan cepat mengotomatiskan penyediaan dan pembatalan penyediaan pengguna dan grup.

  5. [Opsional] Terbitkan aplikasi Anda ke galeri aplikasi Azure AD - Buat pelanggan mudah untuk menemukan aplikasi Anda dan dengan mudah mengonfigurasi provisi.

Diagram yang menunjukkan langkah yang diperlukan untuk mengintegrasikan titik akhir SCIM dengan Azure AD.

Desain skema pengguna dan grup Anda

Setiap aplikasi memerlukan atribut yang berbeda untuk membuat pengguna atau grup. Mulai integrasi Anda dengan mengidentifikasi objek yang diperlukan (pengguna, grup) dan atribut (nama, manajer, jabatan pekerjaan, dll.) yang dibutuhkan aplikasi Anda.

Standar SCIM mendefinisikan skema untuk mengelola pengguna dan grup.

Skema pengguna inti hanya memerlukan tiga atribut (semua atribut lainnya bersifat opsional):

  • id, penyedia layanan yang didefinisikan pengidentifikasi
  • userName, pengidentifikasi unik untuk pengguna (umumnya peta ke nama utama pengguna Azure AD)
  • meta, metadata baca-saja yang dikelola oleh penyedia layanan

Selain skema pengguna inti, standar SCIM mendefinisikan ekstensi pengguna perusahaan dengan model untuk memperluas skema pengguna untuk memenuhi kebutuhan aplikasi Anda.

Misalnya, jika aplikasi Anda memerlukan email pengguna dan manajer pengguna, gunakan skema inti untuk mengumpulkan email pengguna dan skema pengguna perusahaan untuk mengumpulkan manajer pengguna.

Untuk mendesain skema Anda, ikuti langkah-langkah berikut:

  1. Cantumkan atribut yang diperlukan aplikasi Anda, lalu kategorikan sebagai atribut yang diperlukan untuk autentikasi (misalnya, loginName dan email). Atribut diperlukan untuk mengelola siklus hidup pengguna (misalnya, status /aktif) dan semua atribut yang lain diperlukan agar aplikasi berfungsi (misalnya, manajer, tag).

  2. Periksa apakah atribut sudah ditentukan dalam skema pengguna inti atau skema pengguna perusahaan. Jika tidak, Anda harus menentukan ekstensi ke skema pengguna yang mencakup atribut yang hilang. Lihat contoh di bawah ini untuk ekstensi kepada pengguna untuk memungkinkan penyediaan pengguna tag.

  3. Petakan atribut SCIM ke atribut pengguna di Azure AD. Jika salah satu atribut yang telah Anda tentukan di titik akhir SCIM tidak memiliki rekanan yang jelas pada skema pengguna Azure AD, bimbing administrator penyewa untuk memperluas skema mereka atau menggunakan atribut ekstensi seperti yang ditunjukkan di bawah ini untuk properti tags.

Tabel berikut mencantumkan contoh atribut yang diperlukan:

Atribut aplikasi yang diperlukan Atribut SCIM yang dipetakan Atribut Azure AD yang dipetakan
nama log masuk userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName nama belakang
workMail emails[type eq “work”].value Email
manager manajer manager
tag urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
status aktif isSoftDeleted (nilai komputasi tidak disimpan pada pengguna)

Payload JSON berikut menunjukkan contoh skema SCIM:

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "Manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646"
   }
}   

Catatan

Selain atribut yang diperlukan untuk aplikasi, representasi JSON juga mencakup atribut id, externalId, dan meta yang diperlukan.

Proses ini membantu mengkategorikan antara /User dan /Group untuk memetakan atribut pengguna default di Azure AD ke SCIM RFC, lihat bagaimana menyesuaikan atribut yang dipetakan antara Azure AD dan titik akhir SCIM Anda.

Tabel berikut mencantumkan contoh atribut pengguna:

Pengguna Azure Active Directory urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted aktif
departemen urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
displayName displayName
employeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber nomorTelepon[ketik eq "faks"].harga
givenName name.givenName
jabatan judul
email emails[type eq "work"].value
mailNickname externalId
manajer urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
seluler nomorTelepons[ketik eq "HP"].harga
postalCode addresses[type eq "work"].postalCode
proxy-Addresses emails[type eq "other"].Value
physical-Delivery-OfficeName addresses[type eq "other"].Formatted
streetAddress addresses[type eq "work"].streetAddress
nama belakang name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

Tabel berikut mencantumkan contoh atribut grup:

Grup Azure AD urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
anggota anggota
objectId externalId

Catatan

Anda tidak diharuskan untuk mendukung pengguna dan grup, atau semua atribut yang ditampilkan di sini, ini hanya referensi tentang bagaimana atribut di Azure AD sering dipetakan ke properti dalam protokol SCIM.

Ada beberapa titik akhir yang didefinisikan dalam SCIM RFC. Anda dapat memulai dengan /User titik akhir dan kemudian memperluas dari sana. Tabel berikut mencantumkan beberapa titik akhir SCIM:

Titik akhir Deskripsi
/User Melakukan operasi CRUD pada objek pengguna.
/Group Melakukan operasi CRUD pada objek grup.
/Schemas Kumpulan atribut yang didukung oleh setiap klien dan penyedia layanan dapat bervariasi. Satu penyedia layanan mungkin termasuk name, title, dan emails, sementara penyedia layanan lain menggunakan name, title, dan phoneNumbers. Titik akhir skema memungkinkan penemuan atribut yang didukung.
/Bulk Operasi massal memungkinkan Anda melakukan operasi pada kumpulan objek sumber daya yang besar dalam satu operasi (misalnya, memperbarui keanggotaan untuk grup yang besar).
/ServiceProviderConfig Menyediakan detail tentang fitur standar SCIM yang didukung, misalnya metode autentikasi dan sumber daya yang didukung.
/ResourceTypes Menentukan metadata tentang setiap sumber daya.

Catatan

Gunakan /Schemas titik akhir untuk mendukung atribut kustom atau jika skema Anda sering berubah karena memungkinkan klien untuk mengambil skema terbaru secara otomatis. Gunakan /Bulk titik akhir untuk mendukung grup.

Memahami penerapan SCIM Microsoft Azure AD

Untuk mendukung API manajemen pengguna SCIM 2.0, bagian ini menjelaskan cara Layanan Provisi Azure AD diterapkan dan menunjukkan cara membuat model respons dan penanganan permintaan protokol SCIM Anda.

Penting

Perilaku implementasi Azure AD SCIM terakhir diperbaharui pada 18 Desember 2018. Untuk informasi tentang apa yang berubah, lihat kepatuhan protokol SCIM 2.0 dari layanan Penyediaan Pengguna Azure AD.

Dalam spesifikasi protokol SCIM 2.0, aplikasi Anda harus mendukung persyaratan ini:

Persyaratan Catatan referensi (protokol SCIM)
Membuat pengguna, dan dengan opsi membuat grup Bagian 3.3
Mengubah pengguna atau grup dengan permintaan PATCH Bagian 3.5.2. Dukungan memastikan bahwa grup dan pengguna disediakan secara berkinerja.
Mengambil sumber daya yang diketahui untuk pengguna atau grup yang dibuat sebelumnya Bagian 3.4.1
Pengguna atau grup kueri Bagian 3.4.2. Secara default, pengguna diambil oleh mereka id dan diminta oleh mereka username dan externalId, dan grup diminta oleh displayName.
Filter excludedAttributes=members saat memintai sumber daya grup Bagian 3.4.2.2
Mendukung daftar pengguna dan paginating Bagian 3.4.2.4.
Menghapus pengguna dengan lembut active=false dan memulihkan pengguna active=true Objek pengguna harus dikembalikan dalam permintaan apakah pengguna aktif atau tidak. Pengguna tidak boleh ditampilkan hanya saat dihapus secara permanen dari aplikasi.
Mendukung titik akhir /Schemas bagian 7 Titik akhir penemuan skema akan digunakan untuk menemukan atribut tambahan.
Terima token pembawa tunggal untuk autentikasi dan otorisasi Azure AD ke aplikasi Anda.

Gunakan panduan umum saat mengimplementasikan titik akhir SCIM untuk memastikan kompatibilitas dengan Azure AD:

Umum:

  • id adalah properti yang diperlukan untuk semua sumber daya. Setiap respons yang menampilkan sumber daya harus memastikan setiap sumber daya memiliki properti ini, kecuali ListResponse dengan nol elemen.
  • Nilai yang dikirim harus disimpan dalam format yang sama dengan nilai yang dikirim. Nilai yang tidak valid harus ditolak dengan pesan kesalahan deskriptif dan dapat ditindaklanjuti. Transformasi data tidak boleh terjadi antara data yang dikirim oleh Azure AD dan data yang disimpan di aplikasi SCIM. (misalnya. Nomor telepon yang dikirim sebagai 55555555555 tidak boleh disimpan/ditampilkan sebagai +5 (555) 555-5555)
  • Tidak perlu menyertakan seluruh sumber daya dalam respons PATCH.
  • Tidak memerlukan kecocokan peka huruf besar/kecil pada elemen struktural di SCIM, khususnya nilai operasi PATCHop, seperti yang didefinisikan dalam bagian 3.5.2. Azure AD mengeluarkan nilai op sebagai Tambahkan, Ganti, dan Hapus.
  • Microsoft Azure AD membuat permintaan untuk mengambil pengguna dan grup acak untuk memastikan bahwa titik akhir dan info masuk yang diberikan valid. Ini juga dilakukan sebagai bagian dari alur Koneksi Uji di portal Microsoft Azure.
  • Dukung HTTPS pada titik akhir SCIM Anda.
  • Atribut kompleks dan multinilai kustom didukung tetapi Azure AD tidak memiliki banyak struktur data kompleks untuk menarik data dalam kasus ini. Atribut kompleks jenis nilai/nama berpasangan sederhana dapat dipetakan dengan mudah, tetapi mengalirkan data ke atribut kompleks dengan tiga sub-atribut atau lebih tidak didukung dengan baik saat ini.
  • Nilai sub-atribut "jenis" dari atribut kompleks multinilai harus unik. Misalnya, tidak boleh ada dua alamat email yang berbeda dengan sub-jenis "kerja".
  • Header untuk semua respons seharusnya berupa content-Type: application/scim+json

Mengambil Sumber Daya:

/Pengguna:

  • Atribut hak tidak didukung.
  • Atribut apa pun yang dipertimbangkan untuk keunikan pengguna harus dapat digunakan sebagai bagian dari kueri yang difilter. (misalnya jika keunikan pengguna dievaluasi untuk userName dan email[type eq "work"], GET ke /Users dengan filter harus mengizinkan kueri userName eq "user@contoso.com" dan email [type eq "work"].value eq "user@contoso.com".

/Grup:

  • Grup bersifat opsional, tetapi hanya didukung jika implementasi SCIM mendukung permintaan PATCH.
  • Grup harus memiliki keunikan pada nilai 'displayName' agar cocok dengan Azure AD dan aplikasi SCIM. Keunikan ini bukan persyaratan protokol SCIM, tetapi merupakan persyaratan untuk mengintegrasikan layanan SCIM dengan Azure AD.

/Skema (Penemuan skema):

  • Sampel permintaan/tanggapan
  • Penemuan skema saat ini tidak didukung pada aplikasi SCM non-galeri kustom, tetapi tengah digunakan pada aplikasi galeri tertentu. Ke depannya, penemuan skema akan digunakan sebagai metode utama untuk menambahkan atribut tambahan ke skema dari aplikasi SCIM galeri yang sudah ada.
  • Jika nilai tidak ada, jangan kirim nilai null.
  • Nilai properti harus camel cased (misalnya readWrite).
  • Harus mengembalikan respons daftar.
  • Permintaan /schemas akan dibuat oleh Layanan Provisi Azure AD setiap kali seseorang menyimpan konfigurasi provisi di portal Azure atau setiap kali pengguna berada di halaman pengeditan provisi di portal Azure. Atribut lain yang ditemukan akan ditunjukkan kepada pelanggan dalam pemetaan atribut di bagian daftar atribut target. Penemuan skema hanya menyebabkan lebih banyak atribut target yang ditambahkan. Skema tersebut tidak akan mengakibatkan atribut dihapus.

Penyediaan dan pembatalan penyediaan pengguna

Diagram berikut menunjukkan pesan yang dikirim Azure AD ke titik akhir SCIM untuk mengelola siklus hidup pengguna di penyimpanan identitas aplikasi Anda.

Diagram yang menunjukkan urutan pembatalan provisi pengguna.

Penyediaan dan pembatalan penyediaan grup

Penyediaan dan pembatalan penyediaan grup bersifat opsional. Saat diimplementasikan dan diaktifkan, ilustrasi berikut menunjukkan pesan yang dikirim oleh Azure AD ke titik akhir SCIM untuk mengelola siklus hidup grup di penyimpanan identitas aplikasi Anda. Pesan tersebut berbeda dari pesan tentang pengguna dengan dua cara:

  • Permintaan untuk mengambil grup menentukan bahwa atribut anggota akan dikecualikan dari sumber daya apa pun yang disediakan sebagai tanggapan atas permintaan tersebut.
  • Permintaan untuk menentukan apakah atribut referensi memiliki nilai tertentu adalah permintaan tentang atribut anggota.

Diagram berikut menunjukkan urutan pembatalan provisi grup:

Diagram yang menunjukkan urutan pembatalan provisi grup.

Permintaan dan respons protokol SCIM

Artikel ini menyediakan contoh permintaan SCIM yang dikirimkan oleh Layanan Provisi Azure Active Directory (Azure AD) dan contoh respons yang diharapkan. Untuk hasil terbaik, Anda harus membuat kode aplikasi untuk menangani permintaan ini dalam format ini dan mengeluarkan respons yang diharapkan.

Penting

Untuk memahami bagaimana dan kapan layanan penyediaan pengguna Azure AD mengeluarkan operasi yang dijelaskan di bawah ini, lihat bagian Siklus penyediaan: Awal dan bertambah bertahap dalam Cara kerja penyediaan.

Operasi Pengguna

Operasi Grup

Penemuan skema

Operasi Pengguna

  • Pengguna dapat dikueri oleh userName atau emails[type eq "work"] atribut.

Buat Pengguna

Minta

POSTING /Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
Respons

HTTP/1.1 201 Dibuat

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Dapatkan Pengguna

Minta

DAPATKAN /Users/5d48a0a8e9f04aa38008

Respons (Pengguna ditemukan)

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Minta

DAPATKAN /Users/5171a35d82074e068ce2

Respons (Pengguna tidak ditemukan. Detail tidak diperlukan, hanya status.)
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Dapatkan Pengguna menurut kueri

Minta

DAPATKAN /Users?filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Dapatkan Pengguna menurut kueri - Hasil nol

Minta

DAPATKAN /Users?filter=userName eq "non-existent user"

Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Perbarui Pengguna [Properti multinilai]

Minta

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}
Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Perbarui Pengguna [Properti bernilai tunggal]

Minta

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}
Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_49dc1090-aada-4657-8434-4995c25a00f7@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Nonaktifkan Pengguna

Minta

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
Respons
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Hapus Pengguna

Minta

HAPUS /Users/5171a35d82074e068ce2 HTTP/1.1

Respons

HTTP/1.1 204 Tanpa Konten

Operasi Grup

  • Grup akan selalu dibuat dengan daftar anggota kosong.
  • Grup dapat dikueri menurut displayName atribut.
  • Pembaruan untuk grup permintaan PATCH harus menghasilkan HTTP 204 Tanpa Konten dalam respons. Tidak disarankan mengembalikan bodi dengan daftar semua anggota.
  • Tidak perlu mendukung pengembalian semua anggota grup.

Buat Grup

Minta

POSTING /Groups HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}
Respons

HTTP/1.1 201 Dibuat

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Dapatkan Grup

Minta

DAPATKAN /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1

Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Dapatkan Grup menurut displayName

Minta

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Respons

HTTP/1.1 200 OKE

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "id": "8c601452cc934a9ebef9",
        "externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
        "meta": {
            "resourceType": "Group",
            "created": "2018-03-27T22:02:32.000Z",
            "lastModified": "2018-03-27T22:02:32.000Z",
            
        },
        "displayName": "displayName",
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Perbarui Grup [Atribut non-anggota]

Minta

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}
Respons

HTTP/1.1 204 Tanpa Konten

Perbarui Grup [Tambahkan Anggota]

Minta

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Respons

HTTP/1.1 204 Tanpa Konten

Perbarui Grup [Hapus Anggota]

Minta

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
Respons

HTTP/1.1 204 Tanpa Konten

Hapus Grup

Minta

HAPUS /Groups/cdb1ce18f65944079d37 HTTP/1.1

Respons

HTTP/1.1 204 Tanpa Konten

Penemuan skema

Temukan skema

Minta

DAPATKAN /Schemas

Respons

HTTP/1.1 200 OKE

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

Persyaratan keamanan

Versi Protokol TLS

Satu-satunya versi protokol TLS yang dapat diterima adalah TLS 1.2 dan TLS 1.3. Tidak ada versi TLS lain yang diizinkan. Tidak ada versi SSL yang diizinkan.

  • Kunci RSA harus minimal 2.048 bit.
  • Tombol ECC harus minimal 256 bit, dihasilkan menggunakan kurva elips yang disetujui

Panjang Kunci

Semua layanan harus menggunakan sertifikat X.509 yang dihasilkan menggunakan kunci kriptografi dengan panjang yang cukup, artinya:

Cipher Suites

Semua layanan harus dikonfigurasi untuk menggunakan suite sandi berikut, dalam urutan yang ditentukan di bawah ini. Jika Anda hanya memiliki sertifikat RSA, menginstal ECDSA cipher suites tidak akan berpengaruh.

Bar minimum TLS 1.2 Cipher Suites:

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

Rentang IP

Layanan penyediaan Azure AD saat ini beroperasi di bawah Rentang IP untuk AzureActiveDirectory seperti yang tercantum di sini. Anda dapat menambahkan rentang IP yang tercantum di bawah tag AzureActiveDirectory untuk memungkinkan lalu lintas dari layanan penyediaan Azure AD ke aplikasi Anda. Anda perlu meninjau daftar rentang IP dengan hati-hati untuk alamat komputasi. Alamat seperti '40.126.25.32' dapat direpresentasikan dalam daftar rentang IP sebagai '40.126.0.0/18'. Anda juga dapat secara terprogram mengambil daftar rentang IP menggunakan API berikut.

Azure AD juga mendukung solusi berbasis agen untuk menyediakan konektivitas ke aplikasi di jaringan pribadi (lokal, yang dihosting di Azure, dihosting di AWS, dll.). Pelanggan dapat menyebarkan agen ringan yang menyediakan konektivitas ke Azure AD tanpa membuka port masuk, pada server jaringan privat mereka. Pelajari selengkapnya di sini.

Menyusun titik akhir SCIM

Sekarang setelah Anda mendesain skema dan memahami implementasi SCIM Azure AD, Anda dapat mulai mengembangkan titik akhir SCIM. Alih-alih memulai dari awal dan membangun implementasi sepenuhnya sendiri, Anda dapat mengandalkan sejumlah pustaka SCIM sumber terbuka yang diterbitkan oleh komunitas SCIM.

Untuk panduan tentang cara membuat titik akhir SCIM termasuk contoh, lihat Mengembangkan contoh titik akhir SCIM.

Contoh kode referensi .NET Core open source yang diterbitkan oleh tim penyediaan Azure AD adalah salah satu sumber daya yang dapat memulai pengembangan Anda. Setelah membangun titik akhir SCIM, Anda akan ingin mengujinya. Anda dapat menggunakan kumpulan pengujian Postman yang disediakan sebagai bagian dari kode referensi atau menjalankan permintaan/respons sampel yang disediakan di atas.

Catatan

Kode referensi dimaksudkan untuk membantu Anda mulai membangun titik akhir SCIM dan diberikan "SEBAGAIMANA ADANYA". Kontribusi dari komunitas dipersilakan untuk membantu membangun dan memelihara kode.

Solusinya terdiri dari dua proyek, Microsoft.SCIM dan Microsoft.SCIM.WebHostSample.

Proyek Microsoft.SCIM adalah pustaka yang menentukan komponen layanan web yang sesuai dengan spesifikasi SCIM. Yang menyatakan antarmuka Microsoft.SCIM.IProvider, meminta diterjemahkan ke dalam panggilan ke metode penyedia, yang akan diprogram untuk beroperasi di toko identitas.

Perincian: Permintaan diterjemahkan ke dalam panggilan ke metode penyedia

Proyek Microsoft.SCIM.WebHostSample adalah ASP.NET Core Web Application, berdasarkan templat Kosong. Ia memungkinkan kode sampel untuk disebarkan secara mandiri, dihosting dalam kontainer, atau dalam Internet Information Services. Yangi juga mengimplementasikan antarmuka Microsoft.SCIM.IProvider menyimpan kelas dalam memori sebagai toko identitas sampel.

public class Startup
{
    ...
    public IMonitor MonitoringBehavior { get; set; }
    public IProvider ProviderBehavior { get; set; }

    public Startup(IWebHostEnvironment env, IConfiguration configuration)
    {
        ...
        this.MonitoringBehavior = new ConsoleMonitor();
        this.ProviderBehavior = new InMemoryProvider();
    }
    ...

Membuat titik akhir SCIM kustom

Titik akhir SCIM harus memiliki alamat HTTP dan sertifikat autentikasi server yang mana otoritas sertifikasi akarnya adalah salah satu dari nama berikut:

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Go Daddy
  • VeriSign
  • WoSign
  • DST Root CA X3

SDK Inti .NET mencakup sertifikat pengembangan HTTPS yang dapat digunakan selama pengembangan, sertifikat diinstal sebagai bagian dari pengalaman pertama kali dijalankan. Tergantung pada bagaimana Anda menjalankan ASP.NET Core Web Application, yang akan mendengarkan port yang berbeda:

  • Microsoft.SCIM.WebHostSample: https://localhost:5001
  • IIS Express: https://localhost:44359

Untuk informasi lebih lanjut tentang HTTPS ASP.NET Core menggunakan tautan berikut: Berlakukan HTTPS di ASP.NET Core

Menangani autentikasi titik akhir

Permintaan dari Layanan Provisi Azure AD menyertakan token pembawa OAuth 2.0. Token pembawa adalah token keamanan yang dikeluarkan oleh server otorisasi, seperti Azure AD dan dipercaya oleh aplikasi Anda. Anda dapat mengonfigurasi layanan provisi Azure AD untuk menggunakan salah satu token berikut:

  • Token pembawa berumur panjang. Jika titik akhir SCIM memerlukan token pembawa OAuth dari penerbit selain Azure AD, maka salin token pembawa OAuth yang diperlukan ke bidang Token Rahasia opsional. Dalam lingkungan pengembangan, Anda dapat menggunakan token pengujian dari titik akhir /scim/token. Token pengujian tidak boleh digunakan di lingkungan produksi.

  • Token pembawa Azure AD. Jika bidang Token Rahasia dibiarkan kosong, Azure AD menyertakan token pembawa OAuth yang diterbitkan dari Azure AD dengan setiap permintaan. Aplikasi yang menggunakan Azure AD sebagai penyedia identitas dapat memvalidasi token yang dikeluarkan Azure AD ini.

    • Aplikasi yang menerima permintaan harus memvalidasi pengeluar token sebagai Azure AD untuk penyewa Azure AD yang diharapkan.
    • Di dalam token, penerbit diidentifikasi oleh klaim iss. Contohnya:"iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/" Di contoh ini, alamat dasar nilai klaim, https://sts.windows.net mengidentifikasi Azure AD sebagai penerbit, sementara segmen alamat relatif, 12345678-0000-0000-0000-000000000000, adalah pengidentifikasi unik penyewa Azure AD yang tokennya diterbitkan.
    • Audiens untuk token adalah ID Aplikasi untuk aplikasi tersebut di galeri. Aplikasi yang terdaftar dalam satu penyewa menerima klaim iss yang sama dengan permintaan SCIM. ID aplikasi untuk semua aplikasi kustom adalah 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Token yang dihasilkan oleh layanan penyediaan Azure AD hanya boleh digunakan untuk pengujian. Token tidak boleh digunakan di lingkungan produksi.

Dalam kode sampel, permintaan diautentikasi menggunakan paket Microsoft.AspNetCore.Authentication.JwtBearer. Kode berikut ini memberlakukan bahwa permintaan ke titik akhir layanan mana pun diautentikasi menggunakan token pembawa yang diterbitkan oleh Azure AD untuk penyewa tertentu:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

Token pembawa juga diperlukan untuk menggunakan pengujian Postman yang disediakan dan melakukan penelusuran kesalahan lokal menggunakan localhost. Kode sampel menggunakan ASP.NET Core untuk mengubah opsi autentikasi selama tahap pengembangan dan mengaktifkan penggunaan token yang ditandatangani sendiri.

Untuk informasi selengkapnya tentang beberapa lingkungan di ASP.NET Core, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Kode berikut ini memberlakukan permintaan tersebut ke salah satu titik akhir layanan diautentikasi menggunakan token pembawa yang ditandatangani dengan kunci kustom:

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Kirim permintaan GET (DAPATAKAN) ke pengontrol Token untuk mendapatkan token pembawa yang valid, metode GenerateJSONWebToken bertanggung jawab untuk membuat token yang cocok dengan parameter yang dikonfigurasi untuk pengembangan:

private string GenerateJSONWebToken()
{
    // Create token key
    SymmetricSecurityKey securityKey =
        new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
    SigningCredentials credentials =
        new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    // Set token expiration
    DateTime startTime = DateTime.UtcNow;
    DateTime expiryTime = startTime.AddMinutes(120);

    // Generate the token
    JwtSecurityToken token =
        new JwtSecurityToken(
            "Microsoft.Security.Bearer",
            "Microsoft.Security.Bearer",
            null,
            notBefore: startTime,
            expires: expiryTime,
            signingCredentials: credentials);

    string result = new JwtSecurityTokenHandler().WriteToken(token);
    return result;
}

Menangani penyediaan dan pembatalan penyediaan pengguna

Contoh 1. Mengkueri layanan untuk pengguna yang cocok

Azure AD membuat kueri layanan untuk pengguna dengan nilai atribut externalId yang cocok dengan nilai atribut mailNickname pengguna di Azure AD. Kueri dinyatakan sebagai permintaan Protokol Transfer Hiperteks (HTTP) seperti contoh ini, di mana jyoung adalah contoh mailNickname pengguna di Azure AD.

Catatan

Ini hanya contoh. Tidak semua pengguna akan memiliki atribut mailNickname, dan nilai yang diberikan pengguna mungkin tidak unik dalam direktori. Juga, atribut yang digunakan untuk pencocokan (yang dalam hal ini adalah externalId) dapat dikonfigurasi dalam pemetaan atribut Azure AD.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode QueryAsync penyedia layanan. Berikut adalah ciri khas dari metode tersebut:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);

Dalam kueri sampel, untuk pengguna dengan nilai tertentu untuk externalId atribut, nilai argumen yang diteruskan ke metode QueryAsync adalah:

  • parameters.AlternateFilters.Count: 1
  • parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
  • parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"

Contoh 2. Menyediakan pengguna

Jika respons terhadap kueri ke titik akhir SCIM untuk pengguna dengan nilai atribut externalId yang cocok dengan nilai atribut mailNickname pengguna tidak menampilkan pengguna apa pun, maka Azure AD meminta agar layanan menyediakan pengguna yang sesuai dengan yang ada di Azure AD. Berikut adalah contoh permintaan tersebut:

POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
   "schemas":
   [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
   "externalId":"jyoung",
   "userName":"jyoung@testuser.com",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"jyoung@Contoso.com",
       "primary":true}],
   "meta": {
     "resourceType":"User"},
    "name":{
     "familyName":"Young",
     "givenName":"Joy"},
   "phoneNumbers":null,
   "preferredLanguage":null,
   "title":null,
   "department":null,
   "manager":null}

Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode CreateAsync penyedia layanan. Berikut adalah ciri khas dari metode tersebut:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

Dalam permintaan provisi pengguna, nilai argumen sumber daya adalah instans kelas Microsoft.SCIM.Core2EnterpriseUser, yang didefinisikan dalam pustaka Microsoft.SCIM.Schemas. Jika permintaan untuk menyediakan pengguna berhasil, maka implementasi metode diharapkan untuk mengembalikan instance kelas Microsoft.SCIM.Core2EnterpriseUser, dengan nilai properti Pengidentifikasi diatur ke pengidentifikasi unik pengguna yang baru disediakan.

Contoh 3. Meminta status pengguna saat ini

Untuk memperbarui pengguna yang diketahui ada di penyimpanan identitas yang di-fronting oleh SCIM, Azure AD melanjutkan dengan meminta status pengguna saat ini dari layanan dengan permintaan seperti:

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode RetrieveAsync penyedia layanan. Berikut adalah ciri khas dari metode tersebut:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource and 
// Microsoft.SCIM.IResourceRetrievalParameters 
// are defined in Microsoft.SCIM.Schemas 

Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);

Dalam contoh permintaan untuk mengambil status pengguna saat ini, nilai properti objek yang disediakan sebagai nilai argumen parameter adalah sebagai berikut:

  • Pengidentifikasi: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Contoh 4. Meminta nilai atribut referensi yang akan diperbarui

Jika atribut referensi akan diperbarui, maka Azure AD meminta layanan untuk menentukan apakah nilai atribut referensi saat ini yang berada di penyimpanan identitas yang di-fronting oleh layanan sudah sesuai dengan nilai atribut tersebut di Azure AD. Untuk pengguna, satu-satunya atribut yang nilai saat ini diminta dengan cara ini adalah atribut manajer. Berikut adalah contoh permintaan untuk menentukan apakah atribut manajer objek pengguna saat ini memiliki nilai tertentu: Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode QueryAsync penyedia layanan. Nilai properti objek yang disediakan sebagai nilai argumen parameter adalah sebagai berikut:

  • parameters.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: "ID"
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(x).ComparisonValue: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: "2819c223-7f76-453a-919d-413861904646"
  • parameters.RequestedAttributePaths.ElementAt(0): "ID"
  • parameters.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Nilai indeks x bisa jadi 0 dan nilai indeks y bisa jadi1. Atau nilai x bisa jadi 1 dan nilai y bisa jadi 0. Hal ini tergantung urutan ekspresi parameter kueri filter.

Contoh 5. Permintaan dari Azure AD ke titik akhir SCIM untuk memperbarui pengguna

Berikut adalah contoh permintaan dari Azure AD ke titik akhir SCIM untuk memperbarui pengguna:

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode UpdateAsync penyedia layanan. Berikut adalah ciri khas dari metode tersebut:

// System.Threading.Tasks.Tasks and 
// System.Collections.Generic.IReadOnlyCollection<T>  // are defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch, 
// is defined in Microsoft.SCIM.Protocol. 

Task UpdateAsync(IRequest<IPatch> request);

Dalam contoh permintaan untuk memperbarui pengguna, objek yang disediakan sebagai nilai argumen patch memiliki nilai properti ini:

Argumen Nilai
ResourceIdentifier.Identifier "54D382A4-2050-4C03-94D1-E769F1D15682"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manager
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

Contoh 6. Membatalkan penyediaan pengguna

Untuk membatalkan provisi pengguna dari penyimpanan identitas yang di-fronting oleh titik akhir SCIM, Azure AD mengirimkan permintaan seperti:

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 HTTP/1.1
Authorization: Bearer ...

Dalam kode sampel, permintaan diterjemahkan ke dalam panggilan ke metode DeleteAsync penyedia layanan. Berikut adalah ciri khas dari metode tersebut:

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

Objek yang disediakan sebagai nilai argumen resourceIdentifier memiliki nilai properti ini dalam contoh permintaan untuk membatalkan penyediaan pengguna:

  • ResourceIdentifier.Identifier: "54D382A4-2050-4C03-94D1-E769F1D15682"
  • ResourceIdentifier.SchemaIdentifier: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Mengintegrasikan titik akhir SCIM Anda dengan Layanan Provisi Azure AD

Azure AD dapat dikonfigurasi untuk menyediakan pengguna dan grup yang ditetapkan secara otomatis ke aplikasi yang menerapkan profil tertentu dari protokol SCIM 2.0. Spesifikasi profil didokumentasikan dalam Memahami implementasi Azure AD SCIM.

Tanyakan kepada penyedia aplikasi Anda, atau dokumentasi penyedia aplikasi Anda untuk pernyataan kompatibilitas dengan persyaratan ini.

Penting

Implementasi Azure AD SCIM dibangun di atas layanan penyediaan pengguna Azure AD, yang dirancang untuk terus-menerus membuat pengguna tetap sinkron antara Azure AD dan aplikasi target, dan menerapkan serangkaian operasi standar yang sangat spesifik. Penting untuk memahami perilaku ini guna memahami perilaku Layanan Provisi Azure AD. Untuk informasi selengkapnya, lihat bagian Siklus penyediaan: Awal dan bertahap dalam Cara kerja penyediaan.

Memulai

Aplikasi yang mendukung profil SCIM yang dijelaskan dalam artikel ini dapat terhubung ke Azure AD menggunakan fitur "aplikasi non-galeri" di galeri aplikasi Azure AD. Setelah tersambung, Azure AD menjalankan proses sinkronisasi setiap 40 menit di mana ia meminta titik akhir SCIM aplikasi untuk pengguna dan grup yang ditetapkan, dan membuat atau memodifikasinya sesuai dengan detail tugas.

Untuk menghubungkan aplikasi yang mendukung SCIM:

  1. Masuk ke portal Azure AD. Anda bisa mendapatkan akses uji coba gratis untuk Azure AD dengan lisensi P2 dengan mendaftar ke program pengembang)

  2. Pilih Aplikasi perusahaan dari panel kiri. Buat daftar semua aplikasi yang dikonfigurasi ditampilkan, termasuk aplikasi yang ditambahkan dari galeri.

  3. Pilih + Aplikasi baru>+ Buat aplikasi Anda.

  4. Masukkan nama untuk aplikasi Anda, pilih opsi "integrasikan aplikasi lain yang tidak Anda temukan di galeri" dan pilih Tambahkan untuk membuat objek aplikasi. Aplikasi baru ditambahkan ke daftar aplikasi perusahaan dan terbuka ke layar manajemen aplikasinya.

    Cuplikan layar berikut menunjukkan galeri aplikasi Azure AD:

    Cuplikan layar yang menunjukkan galeri aplikasi Azure AD.

  5. Di layar manajemen aplikasi, pilih Penyediaan di panel kiri.

  6. Di menu Mode Penyediaan, pilih Otomatis.

    Cuplikan layar berikut menunjukkan pengaturan konfigurasi provisi di portal Azure:

    Cuplikan layar yang menunjukkan pengaturan konfigurasi provisi di portal Azure.

  7. Di bidang URL Penyewa, masukkan URL titik akhir SCIM aplikasi. Contoh: https://api.contoso.com/scim/

  8. Jika titik akhir SCIM memerlukan token pembawa OAuth dari penerbit selain Azure AD, maka salin token pembawa OAuth yang diperlukan ke bidang Token Rahasia opsional. Jika bidang ini dibiarkan kosong, Azure AD menyertakan token pembawa OAuth yang dikeluarkan dari Azure AD dengan setiap permintaan. Aplikasi yang menggunakan Azure AD sebagai penyedia identitas dapat memvalidasi token yang dikeluarkan Azure AD ini.

    Catatan

    Tidak disarankan untuk mengosongkan bidang ini dan mengandalkan token yang dibuat oleh Azure Active Directory. Opsi ini terutama tersedia untuk tujuan pengujian.

  9. Pilih Uji Koneksi agar Azure AD mencoba menyambungkan ke titik akhir SCIM. Jika upaya gagal, informasi kesalahan akan ditampilkan.

    Catatan

    Uji Koneksi akan menguji titik akhir SCIM untuk pengguna yang tidak ada, menggunakan GUID acak sebagai properti yang cocok dipilih dalam konfigurasi Azure AD. Respons yang diharapkan benar adalah HTTP 200 OKE dengan pesan SCIM ListResponse kosong.

  10. Jika upaya untuk terhubung ke aplikasi berhasil, pilih Simpan untuk menyimpan mandat admin.

  11. Di bagian Pemetaan, ada dua set pemetaan atribut yang dapat dipilih : satu untuk objek pengguna dan satu untuk objek grup. Pilih masing-masing untuk meninjau atribut yang disinkronkan dari Azure AD ke aplikasi Anda. Atribut yang dipilih sebagai properti yang Cocok digunakan untuk mencocokkan pengguna dan grup di aplikasi Anda untuk operasi pembaruan. Pilih Simpan untuk menerapkan perubahan apa pun.

    Catatan

    Anda dapat secara opsional menonaktifkan sinkronisasi objek grup dengan menonaktifkan pemetaan "grup".

  12. Di bawah Pengaturan, bidang Lingkup menentukan pengguna dan grup mana yang disinkronkan. Pilih Sinkronkan hanya pengguna dan grup yang ditetapkan (disarankan) hanya menyinkronkan pengguna dan grup yang ditetapkan di tab Pengguna dan grup.

  13. Setelah konfigurasi Anda selesai, atur Status Penyediaan ke Aktif.

  14. Pilih Simpan untuk memulai layanan penyediaan Azure AD.

  15. Jika hanya menyinkronkan pengguna dan grup yang ditetapkan (disarankan), pilih tab Pengguna dan grup dan tetapkan pengguna atau grup yang ingin Anda sinkronkan.

Setelah siklus awal dimulai, Anda dapat memilih Penyediaan log di panel kiri untuk memantau kemajuan, yang menampilkan semua tindakan yang dilakukan oleh layanan penyediaan di aplikasi Anda. Untuk informasi selengkapnya tentang cara membaca log provisi Microsoft Azure AD, lihat Pelaporan tentang provisi akun pengguna otomatis.

Catatan

Siklus awal membutuhkan waktu lebih lama untuk dilakukan daripada sinkronisasi nanti, yang terjadi sekitar setiap 40 menit selama layanan berjalan.

Jika Anda membuat aplikasi yang akan digunakan oleh lebih dari satu penyewa, Anda dapat membuatnya tersedia di galeri aplikasi Azure AD. Langkah ini akan memudahkan organisasi untuk menemukan aplikasi dan mengonfigurasi provisi. Memublikasikan aplikasi Anda di galeri Azure AD dan membuat penyediaan tersedia untuk orang lain itu mudah. Simak langkah-langkahnya di sini. Microsoft akan bekerja sama dengan Anda untuk mengintegrasikan aplikasi Anda ke galeri kami, menguji titik akhir Anda, dan merilis dokumentasi onboarding untuk digunakan pelanggan.

Menggunakan daftar periksa untuk onboard aplikasi Anda dengan cepat dan pelanggan memiliki pengalaman penyebaran yang lancar. Informasi akan dikumpulkan dari Anda ketika onboarding ke galeri.

  • Mendukung titik akhir pengguna dan grup SCIM 2.0 (Hanya satu yang diperlukan tetapi keduanya direkomendasikan)
  • Mendukung setidaknya 25 permintaan per detik per penyewa untuk memastikan bahwa pengguna dan grup disediakan dan dicabut aksesnya tanpa penundaan (Wajib)
  • Membuat kontak rekayasa dan dukungan untuk memandu pelanggan memposting galeri onboarding (Wajib)
  • 3 mandat pengujian yang tidak kedaluwarsa untuk aplikasi Anda (Wajib)
  • Mendukung pemberian kode otorisasi OAuth atau token berumur panjang seperti yang dijelaskan di bawah ini (Wajib)
  • Membuat rekayasa dan titik dukungan kontak untuk mendukung pelanggan memposting onboarding galeri (Wajib)
  • Mendukung penemuan skema (wajib)
  • Mendukung pembaruan beberapa keanggotaan grup dengan satu PATCH
  • Mendokumentasikan titik akhir SCIM Anda secara publik

Spesifikasi SCIM tidak mendefinisikan skema khusus SCIM untuk otentikasi dan otorisasi dan bergantung pada penggunaan standar industri yang ada.

Metode otorisasi Pro Kontra Dukungan
Nama pengguna dan kata sandi (tidak disarankan atau didukung oleh Azure AD) Mudah diimplementasikan Insecure - Kata sandi Anda tidak bermasalah Tidak didukung untuk aplikasi galeri baru atau non-galeri.
Token pembawa berumur panjang Token berumur panjang tidak mengharuskan pengguna untuk hadir. Mereka mudah digunakan oleh admin saat menyiapkan provisi. Token berumur panjang mungkin sulit untuk dibagikan dengan admin tanpa menggunakan metode yang tidak aman seperti email. Didukung untuk aplikasi galeri dan non-galeri.
Pemberian kode otorisasi OAuth Token akses berumur jauh lebih pendek daripada kata sandi dan memiliki mekanisme penyegaran otomatis yang tidak dimiliki token pembawa berumur panjang. Pengguna nyata harus hadir selama otorisasi awal, menambahkan tingkat akuntabilitas. Mengharuskan pengguna untuk hadir. Jika pengguna meninggalkan organisasi, token menjadi tidak valid dan otorisasi harus diselesaikan lagi. Didukung untuk aplikasi galeri, tetapi bukan aplikasi non-galeri. Namun, Anda dapat memberikan token akses di UI sebagai token rahasia untuk tujuan pengujian jangka pendek. Dukungan untuk hibah kode OAuth pada non-galeri ada di backlog kami, selain dukungan untuk URL auth/token yang dapat dikonfigurasi di aplikasi galeri.
Hibah mandat klien OAuth Token akses berumur jauh lebih pendek daripada kata sandi dan memiliki mekanisme penyegaran otomatis yang tidak dimiliki token pembawa berumur panjang. Baik hibah kode otorisasi dan mandat klien membuat jenis token akses yang sama, sehingga bergerak di antara metode ini transparan ke API. Provisi dapat sepenuhnya otomatis dan token baru dapat diminta secara diam-diam tanpa interaksi pengguna. Didukung untuk aplikasi galeri, tetapi bukan aplikasi non-galeri. Namun, Anda dapat memberikan token akses di UI sebagai token rahasia untuk tujuan pengujian jangka pendek. Dukungan untuk pemberian kredensial klien OAuth di non-galeri ada di backlog kami.

Catatan

Tidak disarankan untuk membiarkan bidang token kosong di UI aplikasi kustom konfigurasi penyediaan Azure AD. Token yang dihasilkan terutama tersedia untuk tujuan pengujian.

Aliran hibah kode OAuth

Layanan penyediaan mendukung pemberian kode otorisasi dan setelah mengirimkan permintaan Anda untuk memublikasikan aplikasi Anda di galeri, tim kami akan bekerja sama dengan Anda untuk mengumpulkan informasi berikut:

  • URL Otorisasi, URL oleh klien untuk mendapatkan otorisasi dari pemilik sumber daya melalui pengalihan agen pengguna. Pengguna dialihkan ke URL ini untuk mengotorisasi akses.

  • URL pertukaran token, URL oleh klien untuk bertukar hibah otorisasi untuk token akses, biasanya dengan autentikasi klien.

  • ID Klien, server otorisasi mengeluarkan pengidentifikasi klien terdaftar, yang merupakan string unik yang mewakili informasi pendaftaran yang disediakan oleh klien. Pengidentifikasi klien bukanlah rahasia; ia diekspos ke pemilik sumber daya dan tidak boleh digunakan sendiri untuk autentikasi klien.

  • Rahasia klien, rahasia yang dihasilkan oleh server otorisasi yang seharusnya menjadi nilai unik yang hanya diketahui oleh server otorisasi.

Catatan

URL Otorisasi dan URL pertukaran Token saat ini tidak dapat dikonfigurasi per penyewa.

Catatan

OAuth v1 tidak didukung karena paparan rahasia klien. OAuth v2 didukung.

Praktik terbaik (disarankan, tetapi tidak wajib):

  • Mendukung beberapa URL pengalihan. Administrator dapat mengonfigurasi penyediaan dari "portal.azure.com" dan "aad.portal.azure.com". Mendukung beberapa URL pengalihan akan memastikan bahwa pengguna dapat mengotorisasi akses dari salah satu portal.
  • Dukung beberapa rahasia untuk perpanjangan yang mudah, tanpa downtime.

Cara mengatur alur pemberian kode OAuth

  1. Masuk ke portal Microsoft Azure, buka Aplikasi Perusahaan>Aplikasi>Penyediaan dan pilih Otorisasi.

    1. Portal Microsoft Azure mengalihkan pengguna ke URL Otorisasi (halaman masuk untuk aplikasi pihak ketiga).

    2. Admin memberikan mandat ke aplikasi pihak ketiga.

    3. Aplikasi pihak ketiga mengalihkan pengguna kembali ke portal Microsoft Azure dan menyediakan kode hibah

    4. Layanan Provisi Azure AD memanggil URL token dan menyediakan kode pemberian. Aplikasi pihak ketiga merespons dengan token akses, token refresh, dan tanggal kedaluwarsa

  2. Ketika siklus penyediaan dimulai, layanan memeriksa apakah token akses saat ini valid dan menukarnya dengan token baru jika diperlukan. Token akses disediakan dalam setiap permintaan yang dibuat ke aplikasi dan validitas permintaan diperiksa sebelum setiap permintaan.

Catatan

Meskipun tidak mungkin untuk mengatur OAuth pada aplikasi non-galeri, Anda dapat secara manual membuat token akses dari server otorisasi Anda dan memasukkannya sebagai token rahasia ke aplikasi non-galeri. Tindakan ini memungkinkan Anda memverifikasi kompatibilitas server SCIM dengan Layanan Provisi Azure AD sebelum melakukan onboarding ke galeri aplikasi, yang mendukung pemberian kode OAuth.

Token pembawa OAuth berumur panjang: Jika aplikasi Anda tidak mendukung alur pemberian kode otorisasi OAuth, sebaliknya buat token pembawa OAuth berumur panjang yang dapat digunakan administrator untuk menyiapkan integrasi provisi. Token harus abadi, atau pekerjaan penyediaan akan dikarantina ketika token kedaluwarsa.

Untuk metode autentikasi dan otorisasi lebih lanjut, beri tahu kami di UserVoice.

Untuk membantu mendorong kesadaran dan permintaan integrasi bersama kami, kami sarankan Anda memperbarui dokumentasi yang ada dan memperkuat integrasi di saluran pemasaran Anda. Kami menyarankan Anda untuk menyelesaikan daftar periksa berikut untuk mendukung peluncuran:

  • Pastikan tim penjualan dan dukungan pelanggan Anda sadar, siap, dan dapat berbicara dengan kemampuan integrasi. Beri arahan singkat pada tim Anda, termasuk FAQ dan sertakan integrasi ke dalam materi penjualan Anda.
  • Buat posting blog atau siaran pers yang menjelaskan integrasi bersama, manfaatnya, dan cara memulai. Contoh: Siaran Imprivata dan Azure AD
  • Manfaatkan media sosial Anda seperti Twitter, Facebook, atau LinkedIn untuk mempromosikan integrasi kepada pelanggan Anda. Pastikan untuk menyertakan @AzureAD sehingga kami dapat me-retweet posting Anda. Contoh: Posting Imprivata Twitter
  • Buat atau perbarui halaman/situs web pemasaran Anda (misalnya halaman integrasi, halaman mitra, halaman harga, dll.) untuk menyertakan ketersediaan integrasi bersama. Contoh: Halaman integrasi Pingboard,halaman integrasi Smartsheet, halaman harga Monday.com
  • Buat artikel pusat bantuan atau dokumentasi teknis tentang bagaimana pelanggan bisa memulai. Contoh: Integrasi Envoy + Microsoft Azure AD.
  • Beri tahu pelanggan tentang integrasi baru melalui komunikasi pelanggan Anda (buletin bulanan, kampanye email, catatan rilis produk).

Langkah berikutnya