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 provisi otomatis pengguna dan grup antara aplikasi Anda dan Microsoft Azure Active Directory. Artikel ini menjelaskan tentang cara membuat titik akhir SCIM dan berintegrasi dengan layanan penyediaan Azure AD. Spesifikasi SCIM menyediakan skema pengguna umum untuk penyediaan. Ketika digunakan bersama dengan standar federasi seperti SAML atau OpenID Connect, SCIM memberi administrator solusi berbasis standar untuk manajemen akses.

Provisioning from Azure AD to an app with SCIM

SCIM adalah definisi standar dari dua titik akhir: /Users titik akhir dan titik akhir /Groups. Ini menggunakan kata kerja REST umum untuk membuat, memperbarui, dan menghapus objek, serta 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 penyediaan ke aplikasi akan memerlukan membangun dan mengintegrasikan titik akhir SCIM dengan klien Azure AD SCIM. Gunakan langkah-langkah berikut untuk mulai menyediakan pengguna dan grup ke dalam aplikasi Anda.

  1. Desain skema pengguna dan grup Anda

    Lakukan identifikasi terhadap objek dan atribut aplikasi untuk menentukan bagaimana mereka memetakan ke skema pengguna dan grup yang didukung oleh implementasi SCIM Azure AD.

  2. Memahami penerapan SCIM Microsoft Azure AD

    Pahami bagaimana klien SCIM Azure AD diimplementasikan untuk membuat model penanganan dan respons permintaan protokol SCIM Anda.

  3. Menyusun titik akhir SCIM

    Titik akhir harus kompatibel dengan SCIM 2.0 agar dapat diintegrasikan dengan layanan penyediaan 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 klien SCIM 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. Publikasikan aplikasi Anda ke galeri aplikasi Azure AD

    Memudahkan pelanggan untuk menemukan aplikasi Anda dan dengan mudah mengonfigurasi penyediaan.

Steps for integrating a SCIM endpoint with 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. Buat daftar atribut yang diperlukan aplikasi Anda, lalu kategorikan sebagai atribut yang diperlukan untuk autentikasi (misalnya loginName dan email), atribut yang diperlukan untuk mengelola siklus hidup pengguna (misalnya status/aktif), dan semua atribut lain yang 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 Anda 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 tags properti.

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)

Contoh daftar atribut yang diperlukan

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

Contoh skema yang ditentukan oleh muatan JSON

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.

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 nomorTelepon[ketik eq "kerja"].harga
user-PrincipalName userName

Contoh daftar atribut pengguna dan grup

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

Contoh daftar atribut grup

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.

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 besar objek sumber daya dalam satu operasi (misalnya memperbarui keanggotaan untuk grup besar).
/ServiceProviderConfig Menyediakan detail tentang fitur standar SCIM yang didukung, misalnya sumber daya yang didukung dan metode autentikasi.
/ResourceTypes Menentukan metadata tentang setiap sumber daya.

Contoh daftar titik akhir

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 bagaimana klien SCIM Azure AD diimplementasikan dan menunjukkan bagaimana cara membuat model penanganan dan respons 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.5
Terima token pembawa tunggal untuk autentikasi dan otorisasi Azure AD ke aplikasi Anda.
Menghapus pengguna dengan lembut active=false dan memulihkan pengguna active=true Objek pengguna harus dikembalikan dalam permintaan apakah pengguna aktif atau tidak. Satu-satunya waktu pengguna tidak boleh dikembalikan adalah ketika sulit dihapus dari aplikasi.
Mendukung titik akhir /Schemas bagian 7 Titik akhir penemuan skema akan digunakan untuk menemukan atribut tambahan.
Mendukung daftar pengguna dan paginating bagian 3.4.2.4.

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 mengembalikan sumber daya harus memastikan setiap sumber daya memiliki properti ini, kecuali ListResponse dengan nol anggota.
  • 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 Active Directory 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 tipe nama/nilai 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".
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 to /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' untuk tujuan pencocokan antara Azure Active Directory dan aplikasi SCIM. Ini bukan persyaratan protokol SCIM, tetapi merupakan persyaratan untuk mengintegrasikan layanan SCIM dengan Azure Active Directory.
/Skema (Penemuan skema):
  • Sampel permintaan/tanggapan
  • Penemuan skema saat ini tidak didukung pada aplikasi SCM non-galeri kustom, tetapi sedang 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 kosong.
  • Nilai properti harus berbayang unta (misalnya readWrite).
  • Harus mengembalikan respons daftar.
  • Permintaan /schemas akan dibuat oleh klien SCIM Azure AD setiap kali seseorang menyimpan konfigurasi penyediaan di portal Microsoft Azure atau setiap kali pengguna berada di halaman penyediaan pengeditan pada portal Microsoft Azure. Setiap atribut tambahan yang ditemukan akan permulaan bagi pelanggan dalam pemetaan atribut di bawah daftar atribut target. Penemuan skema hanya menyebabkan atribut target tambahan menjadi ditambahkan. Skema tersebut tidak akan mengakibatkan atribut dihapus.

Penyediaan dan pembatalan penyediaan pengguna

Ilustrasi berikut menunjukkan pesan yang dikirim Azure AD ke layanan SCIM untuk mengelola siklus hidup pengguna di toko identitas aplikasi Anda.

Shows the user provisioning and deprovisioning sequence
Urutan penyediaan dan pembatalan penyediaan 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 layanan 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.

Shows the group provisioning and deprovisioning sequence
Urutan penyediaan dan pembatalan penyediaan grup

Permintaan dan respons protokol SCIM

Bagian ini menyediakan contoh permintaan SCIM yang dikeluarkan oleh klien SCIM 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. Perhatikan bahwa 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. Perhatikan bahwa 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. Perhatikan bahwa 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 merancang skema Anda dan memahami implementasi Azure AD SCIM, Anda dapat mulai mengembangkan titik akhir SCIM Anda. Alih-alih memulai dari awal dan membangun implementasi sepenuhnya sendiri, Anda dapat mengandalkan sejumlah perpustakaan SCIM open source 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 Anda membangun titik akhir SCIM, Anda akan ingin mengujinya. Anda dapat menggunakan pengumpulan tes petugas pos 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.

Breakdown: A request translated into calls to the provider's methods

Proyek Microsoft.SCIM.WebHostSample adalah Visual Studio ASP.NET Core Web Application, berdasarkan tempat Kosong. Yang memungkinkan kode sampel untuk digunakan sebagai mandiri, dihosting dalam kontainer atau dalam Layanan Informasi Internet. 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

Layanan SCIM harus memiliki alamat HTTP dan sertifikat otentikasi server di mana otoritas sertifikasi akar adalah salah satu 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 Azure Active Directory menyertakan token pembawa OAuth 2.0. Setiap layanan yang menerima permintaan harus mengautentikasi penerbit sebagai Azure Active Directory untuk penyewa Azure Active Directory yang diharapkan.

Dalam token, penerbit diidentifikasi oleh klaim ISS, seperti "iss":"https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/". Dalam contoh ini, alamat dasar nilai klaim, https://sts.windows.net, mengidentifikasi Azure Active Directory sebagai penerbit, sementara segmen alamat relatif, cbb1a5ac-f33b-45fa-9bf5-f37db0fed422, adalah pengidentifikasi unik penyewa Azure Active Directory yang tokennya diterbitkan.

Audiens untuk token akan menjadi ID template aplikasi untuk aplikasi di galeri, masing-masing aplikasi yang terdaftar dalam satu penyewa mungkin menerima klaim yang iss sama dengan permintaan SCIM. ID templat aplikasi untuk semua aplikasi kustom adalah 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Token yang dihasilkan oleh layanan penyediaan Azure AD hanya boleh digunakan untuk pengujian. Yang tidak boleh digunakan di lingkungan produksi.

Dalam kode sampel, permintaan diautentikasi menggunakan paket Microsoft.AspNetCore.Authentication.JwtBearer. Kode berikut ini memberlakukan bahwa permintaan ke salah satu titik akhir layanan diautentikasi menggunakan token pembawa yang dikeluarkan oleh Azure Active Directory 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/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/";
                        options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                        ...
                    });
            }
            ...
        }

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

Token pembawa juga diperlukan untuk menggunakan tes petugas pos yang disediakan dan melakukan debugging 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 Active Directory membuat kueri layanan untuk pengguna dengan nilai atribut externalId yang cocok dengan nilai atribut mailNickname pengguna di Azure AD. Kueri dinyatakan sebagai permintaan Hypertext Transfer Protocol (HTTP) seperti contoh ini, di mana jyoung adalah contoh mailNickname pengguna di Azure Active Directory.

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 layanan web untuk pengguna dengan nilai atribut externalId yang cocok dengan nilai atribut mailNickname pengguna tidak mengembalikan 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 untuk menyediakan 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 dipimpin oleh SCIM, Azure Active Directory 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"
  • Pengidentifikasi Skemar: "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 Active Directory meminta layanan untuk menentukan apakah nilai atribut referensi saat ini berada di penyimpanan identitas yang di depan layanan sudah sesuai dengan nilai atribut tersebut di Azure Active Directory. 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"

Di sini, nilai indeks x bisa 0 dan nilai indeks y bisa 1, atau nilai x bisa 1 dan nilai y bisa 0, tergantung pada urutan ekspresi parameter permintaan filter.

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

Berikut adalah contoh permintaan dari Azure Active Directory ke layanan 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 sebagai PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest sebagai PatchRequest2).Operations.ElementAt(0).Path.AttributePath "manager"
(PatchRequest sebagai PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest sebagai PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(PatchRequest sebagai PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 2819c223-7f76-453a-919d-413861904646

Contoh 6. Membatalkan penyediaan pengguna

Untuk membatalkan penyediaan pengguna dari toko identitas yang berhadapan dengan layanan 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"

Integrasikan titik akhir SCIM Anda dengan klien SCIM 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 untuk memahami perilaku klien Azure AD SCIM. 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 dihubungkan ke Azure Active Directory 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. Perhatikan bahwa Anda bisa mendapatkan akses uji coba gratis untuk Azure Active Directory dengan lisensi P2 dengan mendaftar untuk 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.

    Screenshot shows the Azure AD application galleryGaleri aplikasi Azure AD

    Catatan

    Jika Anda menggunakan pengalaman galeri aplikasi lama, ikuti panduan layar di bawah ini.

    Screenshot shows the Azure AD old app gallery experiencePengalaman galeri aplikasi lama Azure AD

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

  6. Di menu Mode Penyediaan, pilih Otomatis.

    Example: An app's Provisioning page in the Azure portal
    Mengonfigurasi penyediaan di portal Microsoft 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 Active Directory 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 Active Directory 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), pastikan untuk memilih 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. Ini akan memudahkan organisasi untuk menemukan aplikasi dan mengonfigurasi penyediaan. 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 admin saat menyiapkan penyediaan. 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 jauh lebih pendek daripada kata sandi, dan memiliki mekanisme penyegaran otomatis yang tidak memiliki token pembawa berumur panjang. Pengguna nyata harus hadir selama otorisasi awal, menambahkan tingkat akuntabilitas. Mengharuskan pengguna untuk hadir. Jika pengguna meninggalkan organisasi, token 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 jauh lebih pendek daripada kata sandi, dan memiliki mekanisme penyegaran otomatis yang tidak memiliki 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. Penyediaan dapat sepenuhnya otomatis, dan token baru dapat diminta secara diam-diam tanpa interaksi pengguna. Tidak didukung untuk aplikasi galeri dan non-galeri. Dukungan 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; itu terpapar pada pemilik sumber daya dan tidak boleh digunakan sendiri untuk otentikasi 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 aliran hibah 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 penyediaan Azure AD memanggil URL token dan menyediakan kode hibah. 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 Anda menggunakan klien SCIM Azure AD sebelum melakukan onboarding ke galeri aplikasi, yang mendukung pemberian kode OAuth.

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

Untuk metode autentikasi dan otorisasi tambahan, 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. Di bawah ini adalah serangkaian aktivitas daftar periksa yang kami sarankan Anda selesaikan untuk mendukung peluncuran

Langkah berikutnya