跳到主要内容

使用 SCIM 进行用户和组的配置

使用 SCIM 进行用户和组的配置 - 主图

在本文中

您可以使用跨域身份管理系统（SCIM）API 标准来为您的 Notion 工作区提供和管理用户和组 🔑​

目录

  • 使用 Notion 的 SCIM API 可以做什么
  • 如何设置 SCIM 配置
  • 使用 Notion 的 SCIM 前提条件
  • 生成您的 SCIM API 令牌
  • 撤销令牌
  • 替换现有令牌
  • 服务提供商配置
  • 身份提供者 (IdP) 设置
  • Azure
  • Google
  • Gusto
  • Okta
  • OneLogin
  • Rippling
  • 用户
  • 组

使用 Notion 的 SCIM API 可以做什么​

用户配置与管理：

  • 创建并删除工作区成员
  • 更新成员的个人资料信息
  • 检索工作区中的成员
  • 通过电子邮件或姓名查找成员

群组配置和管理：

  • 在您的工作区中创建和删除群组
  • 向群组添加和移除成员
  • 检索您的工作区中的群组
  • 根据名称查找群组

不支持的功能：

  • 管理工作区访客

如何使用 SCIM 设置配置​

我们目前支持 Okta、OneLogin、Rippling、Gusto 和自定义 SCIM 应用。
如果您使用其他身份提供者，请告诉我们。

使用 Notion 进行 SCIM 的先决条件​

  • 您的工作区必须是 企业计划
  • 您的身份提供者（IdP）必须支持 SAML 2.0 协议
  • 只有 Workspace Owner 才能为 Notion 工作区配置 SCIM
  • 至少一个域已由 Workspace Owner 验证。了解更多关于域验证 →

生成您的 SCIM API 令牌​

企业计划工作区所有者可通过以下路径生成和查看 SCIM API 令牌：
设置和成员 → 安全性和身份 → SCIM 配置

  • 点击右上角的 + 新建令牌 按钮生成新令牌
  • 每个工作区所有者生成 唯一的令牌，仅自己可见

撤销令牌​

当工作区所有者离开工作区或角色变更时，其令牌将自动注销。
系统会向剩余的工作区所有者发送通知，提示替换已注销的令牌。

此外，任何工作区所有者均可手动撤销活跃令牌：
点击对应令牌旁的 🗑️ 图标即可。

替换现有令牌​

若令牌被撤销，需在所有相关集成中将其替换。

依赖该令牌的所有 SCIM 集成和用户配置将 立即禁用，直至使用有效令牌更新。

注意： 为避免中断现有集成，请在撤销前确保替换所有关联的管理员令牌。

服务提供商配置​

  • GET /ServiceProviderConfig
    GET https://api.notion.com/scim/v2/ServiceProviderConfig
    检索可用 SCIM 规范功能的描述。
    定义见 SCIM 协议规范第 5 节

  • GET /ResourceTypes
    GET https://api.notion.com/scim/v2/ResourceTypes
    检索可用的 SCIM 资源类型列表。
    定义见 SCIM 协议规范第 6 节

身份提供者（IdP）设置​

Azure​

更多说明请参考 Azure Active Directory 帮助中心：
配置 Notion 进行自动用户提供

Notion 的 Azure SCIM 集成支持以下功能：

  • 创建用户
  • 删除用户
  • 同步用户属性（Azure AD ↔ Notion）
  • 提供组及组成员身份
  • 单点登录 至 Notion（推荐）

注意： 部署前请参考 Azure 文档 制定计划。

步骤 1：在 Notion 中启用配置

  1. 进入 设置和成员 → 身份验证和自动化配置
  2. 滚动至 SCIM 自动化配置 部分
  3. 若未生成令牌，点击 + 添加令牌 并复制
    → 此令牌将在第 5.5 步作为 Secret Token 使用
  4. Notion 的 SCIM 租户 URL 为：
    https://www.notion.so/scim/v2
    → 第 5.5 步需填写此 URL

步骤 2：从 Azure AD 应用程序库添加 Notion

  • 按 此处说明 添加应用
  • Azure AD 可根据用户 / 组属性决定配置范围：

步骤 3：配置自动用户提供给 Notion

  1. 登录 Azure 门户
  2. 选择 企业应用程序 → 所有应用程序
  3. 在列表中选择 Notion
  4. 点击 Provisioning 标签页
  5. 将 Provisioning Mode 设为 Automatic
  6. 在 Admin Credentials 中填入：
    • Tenant URL: https://www.notion.so/scim/v2
    • Secret Token: 上一步复制的令牌
  7. 点击 Test Connection 验证连接
    → 失败请检查管理员权限并重试
  8. 点击 Save
  9. 在 Mappings 下配置用户同步选项
  10. 检查属性映射，确认后保存
  11. 在 Mappings 下配置组同步选项
  12. 检查组属性映射，确认后保存
  13. 在 Settings 中将 Provisioning Status 设为 On
  14. 使用 Scope 定义要同步的用户 / 组
  15. 点击 Save 开始配置

注意： 此操作将触发初始同步周期，耗时较长。后续周期约每 40 分钟执行一次。

Google​

更多说明请参考 Google Workspace 管理帮助中心：
配置 Notion 用户供应

Notion 的 Google SCIM 集成支持：

  • 创建用户
  • 更新用户属性（仅限组织域邮箱用户）
  • 停用用户（从工作区移除）

注意： Google SCIM 不支持组配置。

步骤 1：在 Notion 中启用配置

  1. 进入 设置与成员 → 身份验证与配置
  2. 滚动至 SCIM 配置 部分
  3. 点击现有令牌旁的 “复制”，或点击 + 添加令牌 创建新令牌

步骤 2：在 Google 中配置

  1. 确保已 登录管理员账户
  2. 按 Google 文档 操作，从 “为 Notion 应用程序设置自动配置” 开始

Gusto​

详细设置请参考：
Gusto 与 Notion 集成

步骤 1：连接并验证账户

  1. 在 Notion 侧边栏进入 设置与成员 → 身份验证与配置
  2. 在 SCIM 配置 下点击 + 添加令牌 并复制
  3. 在 Gusto 中：
    • 将令牌粘贴至 SCIM API 密钥字段
    • 输入您的 Notion 账户邮箱

步骤 2：匹配 Gusto 团队成员与 Notion 用户

Okta​

Notion 的 Okta 集成 支持：

  • 创建用户
  • 更新用户属性（组织域邮箱用户）
  • 停用用户（从工作区移除）
  • 推送群组

步骤 1：在 Notion 中启用配置

  1. 进入 设置和成员 → 身份验证和配置
  2. 滚动至 SAML 单点登录 (SSO) 部分
  3. 点击 编辑 SAML SSO 配置
  4. 复制 Assertion Consumer Service (ACS) URL，稍后使用
  5. 返回并滚动至 SCIM provisioning 部分
  6. 若未生成令牌，点击 + 添加令牌 并复制，稍后使用

步骤 2：在 Okta 中配置

  1. 从 Okta 应用目录 添加 Notion 应用
  2. 在 Login Options → Application username format 选择 Email
  3. 在 Provisioning 标签页：
    • 点击 Configure API integration
    • 勾选 Enable API integration
    • 在 API Token 中粘贴 Notion SCIM 令牌
    • 点击 Save
  4. 点击 Provisioning to App 旁的编辑按钮，启用所需功能（创建/更新/停用用户），保存
  5. 在 Push Groups 标签页，点击 Push Groups 添加需同步的 Okta 群组

注意： 更新用户 / 组时，请勿从 Okta 删除 Notion 应用，否则将移除所有已配置用户。
遇到问题请联系 [email protected]

OneLogin​

更多文档请参考：
向 Notion 提供用户

Notion 的 OneLogin 集成支持：

  • 创建用户
  • 更新用户属性（组织域邮箱用户）
  • 停用用户（从工作区移除）
  • 创建规则，将 OneLogin 角色映射至 Notion 权限组

注意： 若通过 OneLogin 提供用户，请 先配置 SCIM，再配置 SSO。

步骤 1：在 Notion 中启用配置

  1. 进入 设置和成员 → 身份验证和提供功能
  2. 滚动至 SAML 单点登录 (SSO) 部分
  3. 点击 编辑 SAML SSO 配置
  4. 复制 断言消费者服务 (ACS) URL，稍后使用
  5. 返回并滚动至 SCIM 提供功能 部分
  6. 若未生成令牌，点击 + 添加令牌 并复制，稍后使用

注意： 仅工作区所有者可复制自己生成的令牌。若他人已创建，请协调是否需要新令牌。
一旦生成者离开或被降级，其所有令牌将过期。

步骤 2：在 OneLogin 中配置

  1. 进入 管理 → 应用程序 → 应用程序
  2. 点击 添加应用，搜索 Notion，选择 SAML 2.0 版本
  3. 点击 保存
  4. 进入 配置 标签页：
    • 将 ACS URL 粘贴至 消费者 URL
    • 将 SCIM 令牌粘贴至 SCIM Bearer Token
    • 点击 启用
  5. 进入 供应商设置 标签页：
    • 在 Workflow 下勾选 “启用供应”
    • 点击右上角 保存
  6. （可选）启用 “需要管理员批准”
  7. （可选）设置用户从 OneLogin 删除时的行为：
    • 删除：从 Notion 工作区移除
    • 不执行任何操作
  8. 点击右上角 保存

Rippling​

详细文档请查看：
Rippling App Shop — Notion

用户​

下表列出 SCIM 用户属性与 Notion 用户字段的映射关系。其余属性将被忽略。

SCIM 用户属性

  • GET /Users
    GET https://api.notion.com/scim/v2/Users
    获取工作区成员分页列表。
    使用 startIndex（从 1 开始）和 count 分页。
    使用 filter 过滤，支持 email、given_name、family_name。
    示例：
    GET https://api.notion.com/scim/v2/Users?startIndex=1&count=50&filter=email eq [email protected]
    → given_name 和 family_name 区分大小写，email 自动转小写。

  • GET /Users/<id>
    GET https://api.notion.com/scim/v2/Users/<id>
    通过 Notion 用户 ID 获取特定成员。
    ID 为 32 字符 UUID，格式：00000000-0000-0000-0000-000000000000
    → meta.created 和 meta.lastModified 无实际时间意义。

  • POST /Users
    POST https://api.notion.com/scim/v2/Users
    若用户已存在相同邮箱的 Notion 账户，则加入工作区。
    否则创建新用户并加入工作区，与其配置文件映射。

  • PATCH /Users/<id>
    PATCH https://api.notion.com/scim/v2/Users/<id>
    通过操作序列更新用户，返回更新后记录。

    注意： 仅当验证用户邮箱域所有权后，方可更新资料（通常与 SAML SSO 域一致）。
    联系我们 验证新域。

  • PUT /Users/<id>
    PUT https://api.notion.com/scim/v2/Users/<id>
    更新并返回用户记录。

  • DELETE /Users/<id>
    DELETE https://api.notion.com/scim/v2/Users/<id>
    从工作区移除用户，并注销其所有会话。
    → 用户账户本身无法通过 SCIM 删除，需手动操作。
    也可通过 PATCH 或 PUT 将 active 设为 false 实现移除。

注意： 创建 SCIM 机器人令牌的工作区所有者 无法通过 API 移除自己。
若通过 SCIM API 移除所有者，其所有令牌将被撤销，相关集成将失效。

群组​

  • GET /Groups
    GET https://api.notion.com/scim/v2/Groups
    获取工作区群组分页列表。
    使用 startIndex（从 1 开始）和 count（最大 100）分页。
    示例：GET https://api.notion.com/scim/v2/Groups?startIndex=1&count=5
    若不分页，最多返回 100 个群组。
    使用 filter 按 displayName 过滤。
    示例：GET https://api.notion.com/scim/v2/Groups?filter=displayName eq Designers

  • GET /Groups/<id>
    GET https://api.notion.com/scim/v2/Groups/<id>
    通过 Notion 群组 ID 获取特定群组。
    ID 为 32 字符 UUID，格式：00000000-0000-0000-0000-000000000000

  • POST /Groups
    POST https://api.notion.com/scim/v2/Groups
    创建新工作区群组。

  • PATCH /Groups/<id>
    PATCH https://api.notion.com/scim/v2/Groups/<id>
    通过操作序列更新群组。

  • PUT /Groups/<id>
    PUT https://api.notion.com/scim/v2/Groups/<id>
    更新群组。

  • DELETE /Groups/<id>
    DELETE https://api.notion.com/scim/v2/Groups/<id>
    删除工作区群组。

注意： 若删除会导致某页面无人拥有完全访问权限，则禁止删除。