จัดเตรียมผู้ใช้และกลุ่มด้วย SCIM

ในเอกสารช่วยเหลือนี้

คุณสามารถจัดเตรียมและจัดการผู้ใช้และกลุ่มในพื้นที่ทำงาน Notion ของคุณด้วยมาตรฐาน API ของ System for Cross-domain Identity Management (SCIM) 🔑

หมายเหตุ: ฟีเจอร์นี้ใช้งานได้เฉพาะสำหรับผู้ใช้ในแพ็คเกจ Enterprise เท่านั้น

สิ่งที่คุณสามารถทำได้ด้วย SCIM API ของ Notion

SCIM API ของ Notion ช่วยให้คุณสามารถทำสิ่งต่อไปนี้ได้:

การจัดเตรียมและการจัดการผู้ใช้

สร้างและลบสมาชิกในพื้นที่ทำงานของคุณ
อัปเดตข้อมูลโพรไฟล์ของสมาชิก
เรียกดูข้อมูลสมาชิกในพื้นที่ทำงานของคุณ
ค้นหาสมาชิกตามอีเมลหรือชื่อ

การจัดเตรียมและการจัดการกลุ่ม

สร้างและลบกลุ่มในพื้นที่ทำงานของคุณ
เพิ่มและลบสมาชิกในกลุ่ม
เรียกดูข้อมูลกลุ่มในพื้นที่ทำงานของคุณ
ค้นหากลุ่มตามชื่อ

หมายเหตุ: ในขณะนี้ คุณไม่สามารถจัดการ ผู้ใช้ชั่วคราว ของพื้นที่ทำงานโดยใช้ SCIM API ของ Notion ได้

วิธีตั้งค่าการจัดเตรียมด้วย SCIM

ปัจจุบันเรารองรับ Okta, OneLogin, Rippling และแอปพลิเคชัน SCIM แบบกำหนดเอง หากคุณใช้ผู้ให้บริการข้อมูลประจำตัวรายอื่น โปรดแจ้งให้เราทราบ ดูคำแนะนำสำหรับการตั้งค่าผู้ให้บริการข้อมูลประจำตัวสำหรับแอปเฉพาะ ที่นี่ →

ข้อกำหนดเบื้องต้นสำหรับ SCIM กับ Notion

ในการใช้ SCIM กับ Notion:

พื้นที่ทำงานของคุณต้องอยู่บนแพ็คเกจ Enterprise
ผู้ให้บริการข้อมูลประจำตัว (IdP) ของคุณต้องรองรับโปรโตคอล SAML 2.0 ดูคำแนะนำสำหรับการตั้งค่าผู้ให้บริการข้อมูลประจำตัวสำหรับแอปเฉพาะ ที่นี่ →
เจ้าของพื้นที่ทำงานต้องกำหนดค่า SCIM สำหรับพื้นที่ทำงาน Notion นั้นๆ
คุณต้องยืนยันความเป็นเจ้าของโดเมนอีเมลหากต้องการใช้ SCIM เพื่อแก้ไขชื่อหรือที่อยู่อีเมลของผู้ใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการยืนยันโดเมน →

สร้างโทเค็น SCIM API ของคุณ

เฉพาะ เจ้าขององค์กร ในแพ็คเกจ Enterprise เท่านั้นที่สามารถสร้างและดูโทเค็น SCIM API ได้ ในการสร้างโทเค็น SCIM API:

เปิดตัวสลับพื้นที่ทำงานและเลือก จัดการองค์กร คุณอาจต้อง ตั้งค่าองค์กร ก่อนหากคุณยังไม่ได้ดำเนินการ ดูข้อมูลเพิ่มเติม ที่นี่ →
ในแท็บ ทั่วไป ของการควบคุมระดับองค์กรของคุณ ให้เลือก > ถัดจาก การจัดเตรียม SCIM

หมายเหตุ: สำหรับแต่ละพื้นที่ทำงานที่คุณต้องการจัดการผ่าน SCIM คุณต้องสร้างโทเค็น SCIM API แยกต่างหาก

เพิกถอนโทเค็น

เมื่อเจ้าของพื้นที่ทำงานออกจากพื้นที่ทำงานหรือมีการเปลี่ยนบทบาทของพวกเขา โทเค็นของพวกเขาจะถูกเพิกถอน เมื่อเกิดเหตุการณ์นี้ ระบบจะส่งข้อความอัตโนมัติไปยังเจ้าของพื้นที่ทำงานที่เหลือเพื่อแจ้งให้พวกเขาทราบถึงการแทนที่โทเค็นที่ถูกเพิกถอน

นอกจากนี้ โทเค็นที่ใช้งานอยู่ยังสามารถถูกเพิกถอนโดยเจ้าของพื้นที่ทำงานคนใดก็ได้ในพื้นที่ทำงานนั้น ในการเพิกถอนโทเค็น ให้คลิก 🗑 ที่อยู่ข้างโทเค็นนั้นๆ

แทนที่โทเค็นที่มีอยู่

หากโทเค็นถูกเพิกถอน คุณจะต้องแทนที่โทเค็นนั้นในการผสานการทำงานที่มีอยู่ทั้งหมด

การผสานการทำงาน SCIM และการจัดเตรียมผู้ใช้ใดๆ ที่อาศัยโทเค็นที่ถูกเพิกถอนจะถูกปิดใช้งานจนกว่าจะถูกแทนที่ด้วยโทเค็นที่ใช้งานได้

หมายเหตุ: เพื่อหลีกเลี่ยงไม่ให้การผสานการทำงานที่มีอยู่ใช้งานไม่ได้ โปรดตรวจสอบให้แน่ใจว่าได้แทนที่โทเค็นใดๆ ที่เชื่อมโยงกับผู้ดูแล ก่อนที่จะยกเลิกการจัดเตรียมผู้ดูแล

ระงับอีเมลคำเชิญ

ในการควบคุมว่าผู้ใช้จะได้รับคำเชิญเข้าสู่พื้นที่ทำงานและกลุ่มทางอีเมลหรือไม่เมื่อมีการจัดเตรียมโดย SCIM เจ้าขององค์กรในแผน Enterprise สามารถ:

เปิดตัวสลับพื้นที่ทำงานของคุณแล้วเลือก จัดการองค์กร
ในแท็บ ทั่วไป ให้เปิด ระงับอีเมลคำเชิญจากการจัดเตรียม SCIM หากคุณไม่ต้องการส่งอีเมลถึงผู้ใช้

การจัดเตรียมสมาชิกแบบจำกัดสิทธิผ่าน SCIM

ในการจัดเตรียม สมาชิกแบบจำกัดสิทธิ ผ่าน SCIM คุณต้องตั้งค่าแอตทริบิวต์ 'role' ของ SCIM เป็น 'restricted_member':

\"urn:ietf:params:scim:schemas:extension:notion:2.0:User\": { role: string // \"owner\" | \"membership_admin\" | \"member\" | \"restricted_member\" }

ในการเปลี่ยนสถานะผู้ใช้ชั่วคราวบนหน้าให้เป็นสมาชิกแบบจำกัดสิทธิผ่าน SCIM คุณต้องใช้ POST /scim/v2/Users

การกำหนดค่าผู้ให้บริการ (Service Provider)

GET /ServiceProviderConfig
- GET
- เรียกดูคำอธิบายของคุณสมบัติข้อมูลจำเพาะ SCIM ที่มีอยู่
- กำหนดไว้ใน ส่วนที่ 5 ของข้อกำหนดโปรโตคอล SCIM
GET /ResourceTypes
- GET
- เรียกดูรายการประเภททรัพยากร SCIM ที่มีอยู่
- กำหนดไว้ใน ส่วนที่ 6 ของข้อกำหนดโปรโตคอล SCIM

ผู้ใช้

ตารางด้านล่างสรุปการแมปข้อมูลระหว่างแอตทริบิวต์ผู้ใช้ SCIM และช่องข้อมูลโพรไฟล์ผู้ใช้ Notion เจ้าขององค์กรจะเป็นผู้เลือกแอตทริบิวต์ที่จะส่งไปยัง Notion และสามารถอัปเดตแอตทริบิวต์ดังกล่าวได้ตลอดเวลา Notion จะประมวลผลแอตทริบิวต์ที่คุณส่งผ่าน Notion SCIM API เพื่อปรับปรุงประสบการณ์ในการจัดเตรียมและจัดการผู้ใช้และกลุ่มต่างๆ

แอตทริบิวต์ SCIM	ช่องข้อมูลโพรไฟล์ผู้ใช้ Notion	เนมสเปซภายนอก
userName	อีเมล (ต้องระบุข้อมูลในช่องนี้)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.formatted	ชื่อ (ช่องชื่อที่แนะนำ เนื่องจาก Notion มีช่องชื่อเพียงช่องเดียว คุณจึงสามารถสร้างนิพจน์ใน Okta เพื่อรวมช่องชื่อต่างๆ เข้าด้วยกันได้)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.familyName	ชื่อ (สามารถใช้ร่วมกับ name.givenName เพื่อเป็นทางเลือกแทน name.formatted)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.givenName	ชื่อ (สามารถใช้ร่วมกับ name.familyName เพื่อเป็นทางเลือกแทน name.formatted)	`urn:ietf:params:scim:schemas:core:2.0:User`
รูปภาพ	รูปโพรไฟล์	`urn:ietf:params:scim:schemas:core:2.0:User`
title	ชื่อ	`urn:ietf:params:scim:schemas:core:2.0:User`
phoneNumbers	เบอร์โทร	`urn:ietf:params:scim:schemas:core:2.0:User`
ที่อยู่	ที่อยู่	`urn:ietf:params:scim:schemas:core:2.0:User`
บทบาท	บทบาท	`urn:ietf:params:scim:schemas:core:2.0:User`
ภาษา	ภาษา	`urn:ietf:params:scim:schemas:core:2.0:User`
preferredLanguage	ภาษาที่ต้องการ	`urn:ietf:params:scim:schemas:core:2.0:User`
userType	ประเภทผู้ใช้	`urn:ietf:params:scim:schemas:core:2.0:User`
อีเมล	อีเมล	`urn:ietf:params:scim:schemas:core:2.0:User`
ใช้งานอยู่	ใช้งานอยู่	`urn:ietf:params:scim:schemas:core:2.0:User`
manager.value	ผู้จัดการ (ควรเป็นที่อยู่อีเมล)	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
manager.displayName	ผู้จัดการ	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
ฝ่าย	ฝ่าย	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
แผนก	แผนก	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
costCenter	ศูนย์ต้นทุน	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
องค์กร	องค์กร	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
หมายเลขพนักงาน	หมายเลขพนักงาน	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
บทบาท	บทบาทในพื้นที่ทำงาน Notion ("owner" \| "membership_admin" \| "member")	`urn:ietf:params:scim:schemas:extension:notion:2.0:Use`

หมายเหตุ: Notion จะจัดเก็บเฉพาะรายการ phoneNumbers รายการแรกที่มี primary=true เท่านั้น รายการอื่นๆ ทั้งหมดจะถูกละทิ้ง ฟิลด์ type จะถูกละเว้นโดยสิ้นเชิง โปรดทราบว่า primary ไม่ได้เป็นส่วนหนึ่งของข้อกำหนด SCIM 2.0 ซึ่ง Notion จัดการในรูปแบบที่แตกต่างจากมาตรฐาน หากไม่มีรายการใดที่มี primary=true จะไม่มีการจัดเก็บหมายเลขโทรศัพท์ใดๆ

GET /Users
- GET
- เรียกดูรายการสมาชิกพื้นที่ทำงานแบบแบ่งหน้า
- คุณสามารถแบ่งหน้าโดยใช้พารามิเตอร์ startIndex และ count โปรดทราบว่า startIndex เริ่มต้นที่ 1 และ count มีค่าสูงสุดที่ 100
- คุณสามารถกรองผลลัพธ์ด้วยพารามิเตอร์ filter แอตทริบิวต์ที่ถูกต้องในการกรองคือ email, given_name และ family_name เช่น GET
- โปรดทราบว่า given_name และ family_name มีความไวต่อความแตกต่างของตัวพิมพ์ใหญ่และตัวพิมพ์เล็ก และอีเมลจะถูกแปลงเป็นตัวพิมพ์เล็ก
GET /Users/
- GET
- ดึงข้อมูลสมาชิกพื้นที่ทำงานที่ระบุโดยใช้ Notion user ID ของสมาชิกนั้น ซึ่งจะเป็น UUID ที่มี 32 อักขระในรูปแบบดังนี้: 00000000-0000-0000-0000-000000000000
- โปรดทราบว่า meta.created และ meta.lastModified ไม่ได้สะท้อนค่าการประทับเวลาที่มีความหมาย
POST /Users
- POST
- หากผู้ใช้ที่คุณกำลังเพิ่มมีบัญชีผู้ใช้ Notion ที่มีอีเมลเดียวกันอยู่แล้ว พวกเขาจะถูกเพิ่มลงในพื้นที่ทำงานของคุณ
- หากผู้ใช้ไม่มีอยู่จริง การเรียกใช้คำสั่งนี้จะสร้างผู้ใช้ Notion ใหม่และเพิ่มผู้ใช้นั้นลงในพื้นที่ทำงานของคุณ โดยจะเชื่อมโยงเข้ากับโพรไฟล์ผู้ใช้ Notion ที่ถูกสร้างขึ้น
- SCIM API จะอ่านพร็อพเพอร์ตี้รูปโปรไฟล์เมื่อสร้างผู้ใช้ แต่จะไม่ทำในการอัปเดตในอนาคต
PATCH /Users/
- PATCH
- อัปเดตผ่านชุดการดำเนินการ และส่งคืนบันทึกที่อัปเดตแล้วของผู้ใช้

หมายเหตุ: คุณสามารถอัปเดตข้อมูลโพรไฟล์ของสมาชิกได้ก็ต่อเมื่อคุณได้ยืนยันความเป็นเจ้าของโดเมนอีเมลของผู้ใช้แล้วเท่านั้น (โดยปกติแล้วโดเมนนี้จะเป็นโดเมนเดียวกับโดเมนอีเมลที่คุณกำหนดค่าไว้สำหรับ SAML Single Sign-On กับ Notion) ยืนยันโดเมนของคุณโดยใช้คำแนะนำ ที่นี่ →

PUT /Users/
- PUT
- อัปเดตและส่งคืนบันทึกที่อัปเดตแล้วของผู้ใช้
DELETE /Users/
- DELETE
- นำผู้ใช้ออกจากพื้นที่ทำงานของคุณ ผู้ใช้จะถูกออกจากระบบทุกเซสชันที่ใช้งานอยู่
  - บัญชีผู้ใช้ไม่สามารถลบผ่าน SCIM ได้ การลบบัญชีต้องทำด้วยตนเอง
  - การนำผู้ใช้ออกจากพื้นที่ทำงานของคุณสามารถทำได้โดยการตั้งค่าแอตทริบิวต์ผู้ใช้ active เป็น false โดยการส่งคำขอ PATCH /Users/ หรือ PUT /Users/
  - เจ้าของพื้นที่ทำงานที่สร้างโทเค็นบอท SCIM ไม่สามารถถูกลบผ่าน API ได้ เมื่อเจ้าของพื้นที่ทำงานถูกลบผ่าน SCIM API โทเค็นใดๆ ที่พวกเขาสร้างขึ้นจะถูกเพิกถอน และการผสานการทำงานใดๆ ที่ใช้บอทนั้นจะใช้งานไม่ได้

หมายเหตุ: คุณสามารถกำหนดระดับพื้นที่ทำงานให้กับ ผู้ใช้ โดยใช้แอตทริบิวต์ role ซึ่งเป็นส่วนขยายของสคีมาผู้ใช้ที่มีอยู่ รูปแบบคือ:

\"urn:ietf:params:scim:schemas:extension:notion:2.0:User\": { role: string // \"owner\" | \"membership_admin\" | \"member\" }

กลุ่ม

GET /Groups
- GET
- ดึงรายการกลุ่มพื้นที่ทำงานแบบแบ่งหน้า
- คุณสามารถแบ่งหน้าโดยใช้พารามิเตอร์ startIndex และ count โปรดทราบว่า startIndex เริ่มต้นที่ 1 และ count มีค่าสูงสุดที่ 100 เช่น GET
  - หากไม่มีการใช้การแบ่งหน้า จะมีการส่งคืนกลุ่มพื้นที่ทำงานสูงสุด 100 กลุ่มในการร้องขอหนึ่งครั้ง
- คุณสามารถกรองผลลัพธ์ได้ด้วยพารามิเตอร์ filter กลุ่มสามารถกรองได้โดยใช้แอตทริบิวต์ displayName เช่น GET
GET /Groups/
- GET
- ดึงข้อมูลกลุ่มพื้นที่ทำงานเฉพาะโดยใช้ Notion group ID ของกลุ่มนั้น ซึ่งจะเป็น UUID ที่มี 32 อักขระในรูปแบบต่อไปนี้: 00000000-0000-0000-0000-000000000000
POST /Groups
- POST
- สร้างกลุ่มพื้นที่ทำงานใหม่
PATCH /Groups/
- PATCH
- อัปเดตกลุ่มพื้นที่ทำงานผ่านชุดการดำเนินการต่างๆ
PUT /Groups/
- PUT
- อัปเดตกลุ่มพื้นที่ทำงาน
DELETE /Groups/
- DELETE
- ลบกลุ่มพื้นที่ทำงาน

หมายเหตุ: ห้ามลบกลุ่ม ถ้าจะทำให้ไม่มีใครมีการเข้าถึงเต็มรูปแบบในอย่างน้อยหนึ่งหน้า

ดูข้อมูลเพิ่มเติม

ตั้งค่าผู้ให้บริการข้อมูลประจำตัว (IdP) สำหรับ SCIM