Cấp quyền người dùng & nhóm với SCIM

Trong tài liệu trợ giúp này

Bạn có thể cấp quyền và quản lý người dùng cũng như nhóm trong không gian làm việc Notion của mình bằng tiêu chuẩn API Hệ thống quản lý danh tính liên miền (SCIM) 🔑

Lưu ý: Tính năng này chỉ khả dụng cho người dùng trên Gói Enterprise.

Những điều bạn có thể làm với API SCIM của Notion

API SCIM của Notion cho phép bạn thực hiện những việc sau:

Cấp quyền và quản lý người dùng

Tạo và xóa thành viên trong không gian làm việc của bạn.
Cập nhật thông tin hồ sơ của thành viên.
Truy xuất các thành viên trong không gian làm việc của bạn.
Tìm thành viên theo email hoặc tên.

Cấp quyền và quản lý nhóm

Tạo và xóa nhóm trong không gian làm việc của bạn.
Thêm và xóa thành viên trong một nhóm.
Truy xuất các nhóm trong không gian làm việc của bạn.
Tìm nhóm theo tên.

Lưu ý: Tại thời điểm này, bạn không thể quản lý khách không gian làm việc bằng SCIM API của Notion.

Cách thiết lập cấp quyền với SCIM

Hiện tại chúng tôi hỗ trợ Okta, OneLogin, Rippling và các ứng dụng SCIM tùy chỉnh. Nếu bạn sử dụng Nhà cung cấp danh tính khác, vui lòng cho chúng tôi biết. Xem hướng dẫn thiết lập Nhà cung cấp danh tính cho các ứng dụng cụ thể tại đây →

Điều kiện tiên quyết để sử dụng SCIM với Notion

Để sử dụng SCIM với Notion:

Không gian làm việc của bạn phải thuộc Gói Enterprise.
Nhà cung cấp danh tính (IdP) của bạn phải hỗ trợ giao thức SAML 2.0. Xem hướng dẫn thiết lập Nhà cung cấp danh tính cho các ứng dụng cụ thể tại đây →
Chủ sở hữu không gian làm việc phải định cấu hình SCIM cho không gian làm việc Notion.
Bạn phải xác minh quyền sở hữu đối với tên miền email nếu muốn sử dụng SCIM để sửa đổi tên hoặc địa chỉ email của người dùng. Tìm hiểu thêm về xác minh miền →

Tạo mã thông báo API SCIM của bạn

Chỉ chủ sở hữu tổ chức gói Enterprise mới có thể tạo và xem mã thông báo API SCIM. Để tạo mã thông báo API SCIM:

Mở trình chuyển đổi không gian làm việc và chọn Quản lý tổ chức. Bạn có thể cần Thiết lập tổ chức trước nếu bạn chưa thực hiện. Tìm hiểu thêm tại đây →
Trong tab Chung của các tùy chọn kiểm soát cấp tổ chức, hãy chọn > bên cạnh Cấp quyền SCIM.

Lưu ý: Đối với mỗi không gian làm việc bạn muốn quản lý qua SCIM, bạn phải tạo một mã thông báo SCIM API riêng.

Thu hồi mã thông báo

Khi một chủ sở hữu không gian làm việc rời khỏi không gian làm việc hoặc vai trò của họ bị thay đổi, mã thông báo của họ sẽ bị thu hồi. Khi điều này xảy ra, một tin nhắn tự động sẽ được gửi đến các chủ sở hữu không gian làm việc còn lại để thông báo cho họ thay thế mã thông báo đã bị thu hồi.

Ngoài ra, các mã thông báo đang hoạt động có thể bị thu hồi bởi bất kỳ chủ sở hữu không gian làm việc nào trong không gian làm việc đó. Để thu hồi mã thông báo, hãy nhấp vào 🗑 bên cạnh mã thông báo tương ứng.

Thay thế các mã thông báo hiện có

Nếu một mã thông báo bị thu hồi, bạn sẽ cần thay thế nó trong bất kỳ tích hợp hiện có nào.

Mọi tích hợp SCIM và việc cấp quyền người dùng dựa vào mã thông báo đã bị thu hồi sẽ bị vô hiệu hóa cho đến khi được thay thế bằng mã thông báo đang hoạt động.

Lưu ý: Để tránh làm gián đoạn các tích hợp hiện có, hãy đảm bảo thay thế mọi mã thông báo liên kết với quản trị viên trước khi hủy cấp quyền cho họ.

Chặn email mời

Để kiểm soát việc người dùng có nhận được lời mời tham gia không gian làm việc và nhóm qua email khi được cấp quyền bởi SCIM hay không, chủ sở hữu tổ chức gói Enterprise có thể:

Mở bộ chuyển đổi không gian làm việc của bạn và chọn Quản lý tổ chức.
Trong tab Chung, hãy bật Chặn email mời từ việc cấp quyền SCIM nếu bạn không muốn gửi email cho người dùng.

Cấp quyền cho thành viên bị hạn chế thông qua SCIM

Để cấp quyền cho một thành viên bị hạn chế thông qua SCIM, bạn phải đặt thuộc tính 'role' của SCIM thành 'restricted_member':

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

Để chuyển đổi khách trang thành thành viên bị hạn chế thông qua SCIM, bạn phải sử dụng POST /scim/v2/Users.

Cấu hình Nhà cung cấp dịch vụ

GET /ServiceProviderConfig
- GET
- Truy xuất mô tả về các tính năng đặc tả SCIM khả dụng.
- Được xác định trong Mục 5 của Đặc tả Giao thức SCIM.
GET /ResourceTypes
- GET
- Truy xuất danh sách các loại tài nguyên SCIM khả dụng.
- Được xác định trong Mục 6 của Đặc tả Giao thức SCIM.

Người dùng

Bảng biểu dưới đây phác thảo ánh xạ giữa các thuộc tính người dùng SCIM và các trường hồ sơ người dùng Notion. Chủ sở hữu tổ chức chọn các thuộc tính nào để gửi đến Notion và có thể cập nhật các thuộc tính đó bất kỳ lúc nào. Notion xử lý các thuộc tính bạn gửi thông qua API SCIM của Notion để cải thiện trải nghiệm cấp quyền và quản lý người dùng và nhóm.

Thuộc tính SCIM	Trường Hồ sơ người dùng Notion	Không gian tên bên ngoài
userName	Email (Đây là trường bắt buộc)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.formatted	Tên (Trường tên được khuyến nghị. Vì Notion có một trường tên duy nhất, bạn có thể tạo một biểu thức trong Okta để kết hợp bất kỳ trường tên nào.)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.familyName	Tên (Có thể sử dụng kết hợp với name.givenName như một giải pháp thay thế cho name.formatted.)	`urn:ietf:params:scim:schemas:core:2.0:User`
name.givenName	Tên (Có thể sử dụng kết hợp với name.familyName như một giải pháp thay thế cho name.formatted.)	`urn:ietf:params:scim:schemas:core:2.0:User`
ảnh	Ảnh Hồ sơ	`urn:ietf:params:scim:schemas:core:2.0:User`
title	Tiêu đề	`urn:ietf:params:scim:schemas:core:2.0:User`
phoneNumbers	Số điện thoại	`urn:ietf:params:scim:schemas:core:2.0:User`
addresses	Địa chỉ	`urn:ietf:params:scim:schemas:core:2.0:User`
vai trò	Vai trò	`urn:ietf:params:scim:schemas:core:2.0:User`
locale	Ngôn ngữ	`urn:ietf:params:scim:schemas:core:2.0:User`
preferredLanguage	Ngôn ngữ ưu tiên	`urn:ietf:params:scim:schemas:core:2.0:User`
userType	Loại người dùng	`urn:ietf:params:scim:schemas:core:2.0:User`
emails	Email	`urn:ietf:params:scim:schemas:core:2.0:User`
active	Đang hoạt động	`urn:ietf:params:scim:schemas:core:2.0:User`
manager.value	Người quản lý (Đây phải là một địa chỉ email)	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
manager.displayName	Quản lý	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
division	Bộ phận	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
department	Phòng ban	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
costCenter	Trung tâm chi phí	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
tổ chức	Tổ chức	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
employeeNumber	Mã nhân viên	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
vai trò	Vai trò trong không gian làm việc Notion ("chủ sở hữu" \| "quản trị thành viên" \| "thành viên")	`urn:ietf:params:scim:schemas:extension:notion:2.0:Use`

Lưu ý: Notion chỉ lưu mục phoneNumbers đầu tiên có chính=true. Tất cả các mục khác sẽ bị loại bỏ. Trường type hoàn toàn bị bỏ qua. Lưu ý rằng chính không nằm trong thông số kỹ thuật SCIM 2.0 — Notion xử lý trường này khác với tiêu chuẩn. Nếu không có mục nào có chính=true, sẽ không có số điện thoại nào được lưu.

GET /Users
- GET
- Truy xuất danh sách thành viên không gian làm việc được phân trang.
- Bạn có thể phân trang bằng cách sử dụng các tham số startIndex và count. Lưu ý rằng startIndex bắt đầu từ 1 và count có giá trị tối đa là 100.
- Bạn có thể lọc kết quả bằng tham số filter. Các thuộc tính hợp lệ để lọc là email, given_name và family_name, ví dụ: GET
- Lưu ý rằng given_name và family_name có phân biệt chữ hoa chữ thường. Email được chuyển đổi thành chữ thường.
GET /Users/
- GET
- Truy xuất một thành viên không gian làm việc cụ thể theo ID người dùng Notion của thành viên đó. Đây sẽ là một UUID gồm 32 ký tự theo định dạng sau: 00000000-0000-0000-0000-000000000000.
- Lưu ý rằng meta.created và meta.lastModified không phản ánh các giá trị dấu thời gian có ý nghĩa.
POST /Users
- POST
- Nếu người dùng bạn đang thêm đã có tài khoản người dùng Notion với cùng địa chỉ email, thì họ sẽ được thêm vào không gian làm việc của bạn.
- Nếu người dùng không tồn tại, việc gọi lệnh này sẽ tạo một người dùng Notion mới và sau đó thêm người dùng đó vào không gian làm việc của bạn. Họ sẽ được ánh xạ tới hồ sơ người dùng Notion đã được tạo.
- SCIM API sẽ đọc thuộc tính ảnh hồ sơ khi tạo người dùng, nhưng không đọc trong các bản cập nhật sau này.
PATCH /Users/
- PATCH
- Cập nhật thông qua một loạt các thao tác và trả về bản ghi người dùng đã cập nhật.

Lưu ý: Bạn chỉ có thể cập nhật thông tin hồ sơ của thành viên nếu bạn đã xác minh quyền sở hữu tên miền email của người dùng (thường giống với các tên miền email bạn đã định cấu hình cho SAML đăng nhập một lần với Notion). Xác minh tên miền của bạn theo hướng dẫn tại đây →

PUT /Users/
- PUT
- Cập nhật và trả về bản ghi người dùng đã cập nhật.
DELETE /Users/
- DELETE
- Xóa người dùng khỏi không gian làm việc của bạn. Người dùng sẽ bị đăng xuất khỏi tất cả các phiên hoạt động.
  - Tài khoản người dùng không thể bị xóa thông qua SCIM. Việc xóa tài khoản phải được thực hiện thủ công.
  - Việc xóa người dùng khỏi không gian làm việc của bạn cũng có thể đạt được bằng cách đặt thuộc tính người dùng active thành false bằng cách gửi yêu cầu PATCH /Users/ hoặc PUT /Users/.
  - Chủ sở hữu không gian làm việc đã tạo mã thông báo bot SCIM không thể bị xóa thông qua API. Khi một chủ sở hữu không gian làm việc bị xóa thông qua SCIM API, mọi mã thông báo họ đã tạo sẽ bị thu hồi và mọi tích hợp sử dụng bot đó sẽ bị hỏng.

Lưu ý: Bạn có thể chỉ định cấp độ không gian làm việc cho Người dùng bằng thuộc tính role, đây là phần mở rộng của lược đồ Người dùng hiện có. Định dạng là:

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

Nhóm

GET /Groups
- GET
- Truy xuất danh sách các nhóm không gian làm việc được phân trang.
- Bạn có thể phân trang bằng cách sử dụng các tham số startIndex và count. Lưu ý rằng startIndex bắt đầu từ 1 và count có giá trị tối đa là 100, ví dụ: GET
  - Nếu không sử dụng phân trang, tối đa 100 nhóm không gian làm việc sẽ được trả về trong một yêu cầu.
- Bạn có thể lọc kết quả bằng tham số filter. Các nhóm có thể được lọc theo thuộc tính displayName của chúng, ví dụ: GET
GET /Groups/
- GET
- Truy xuất một nhóm không gian làm việc cụ thể theo ID nhóm Notion của nó. Đây sẽ là một UUID gồm 32 ký tự theo định dạng sau: 00000000-0000-0000-0000-000000000000.
POST /Groups
- POST
- Tạo một nhóm không gian làm việc mới.
PATCH /Groups/
- PATCH
- Cập nhật một nhóm không gian làm việc thông qua một loạt các thao tác.
PUT /Groups/
- PUT
- Cập nhật một nhóm không gian làm việc.
DELETE /Groups/
- DELETE
- Xóa một nhóm không gian làm việc.

Ghi chú: Việc xóa nhóm sẽ bị cấm nếu hành động đó khiến không ai có Truy cập đầy đủ vào một hoặc nhiều trang.

Tìm hiểu thêm

Thiết lập Nhà cung cấp danh tính (IdP) cho SCIM