4. GitLab用户与权限体系设计

GitLab 的权限体系不是一张“用户—项目”的平面表，而是一棵由群组（Group）、子群组（Subgroup）、项目（Project）构成的命名空间树。理解这棵树，是设计 SSO、SCIM 与细粒度权限的前提：权限继承沿树自上而下流动，身份来源则从外部 IdP 自外向内注入。本节围绕这两条主线展开。

一、命名空间树：群组、子群组与项目的层级关系

GitLab 中每个项目必须归属于某个命名空间。命名空间有两种：用户个人命名空间和群组命名空间。企业场景应统一使用群组命名空间，因为个人命名空间无法被组织级策略覆盖，人员离职后资产归属会失控。

群组可以嵌套子群组，形成任意深度的层级。典型的企业结构是“业务线 → 产品 → 组件”三层，例如：

gitlab.example.com
└── platform（顶级群组，Platform 业务线）
    ├── payment（子群组，支付产品）
    │   ├── payment-api（项目）
    │   └── payment-web（项目）
    └── identity（子群组，身份产品）
        └── sso-gateway（项目）

层级设计有三条硬约束需要记住。第一，路径即权限边界：子群组会继承父群组的成员与权限，但父群组不会自动获得子群组中更细的权限，除非显式添加成员。第二，项目路径不可跨群组迁移，一旦确定顶级群组名称，后续改名会引发所有 CI 配置、镜像地址、Webhook 的连锁修改，因此命名应在规划阶段冻结。第三，层级深度建议不超过 4 层，过深会导致权限排查困难、审计日志难以聚合。

一个常见的误区是把“组织架构”直接映射为“群组层级”。组织架构会频繁调整，而群组路径是技术资产标识。更稳妥的做法是：群组层级按产品/系统划分，人员归属通过 IdP 的组声明动态映射，这样组织调整时只需改 IdP 的组映射规则，不必迁移 GitLab 项目。

二、SAML/OIDC 单点登录：身份如何进入 GitLab

GitLab 支持 SAML 2.0 与 OpenID Connect 两种 SSO 协议。SAML 适合已有企业 IdP（如 ADFS、Okta、Azure AD）且需要强断言签名的场景；OIDC 基于 OAuth 2.0，配置更轻量，适合云原生 IdP。两者在 GitLab 中的定位是认证（Authentication），即“证明你是谁”，不负责授权。

以 SAML 为例，关键配置项包括：IdP 的 SSO URL、证书指纹、GitLab 的 Assertion Consumer Service URL（形如 https://gitlab.example.com/users/auth/saml/callback），以及 NameID 格式。NameID 建议使用 emailAddress 或持久化唯一标识，避免用户改邮箱后账号失联。

属性映射是 SSO 设计中最容易被忽视的部分。IdP 断言中的属性需要映射到 GitLab 用户字段，例如：

# gitlab.rb 中的 SAML 属性映射示例
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "企业统一登录",
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "AA:BB:CC:...",
      idp_sso_target_url: "https://idp.example.com/sso/saml",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      attribute_statements: {
        email: ["urn:oid:0.9.2342.19200300.100.1.3"],
        name: ["urn:oid:2.16.840.1.113730.3.1.241"],
        first_name: ["urn:oid:2.5.4.42"],
        last_name: ["urn:oid:2.5.4.4"]
      }
    }
  }
]

OIDC 的配置逻辑类似，但使用 openid_connect 提供者，需要填写 issuer、client_id、client_secret 与 discovery 端点。无论哪种协议，都应开启 omniauth_auto_link_saml_user 或对应的自动关联，使已有本地账号在首次 SSO 登录时按邮箱自动绑定，避免重复账号。

三、SCIM 同步：把 IdP 的组与用户生命周期带进 GitLab

SCIM（System for Cross-domain Identity Management）解决的是用户生命周期自动化：入职创建、转岗调整、离职禁用。GitLab 的 SCIM 能力主要面向群组级同步，即 IdP 中的某个组可以映射为 GitLab 群组，组内成员的增删会自动同步。

配置 SCIM 的前提是已启用 SAML SSO，并在群组设置中生成 SCIM Token。IdP 侧需要配置 SCIM 端点，形如：

SCIM Base URL: https://gitlab.example.com/api/scim/v2/groups/platform
SCIM Token:    glpat-xxxxxxxxxxxxxxxxxxxx

同步过程中需要关注三个判断点。第一，用户匹配依据：SCIM 默认按 externalId 或 userName（通常是邮箱）匹配已有用户，若 IdP 与 GitLab 邮箱不一致，会创建重复账号。第二，组映射粒度：建议 IdP 组与 GitLab 子群组一一对应，避免一个 IdP 组映射到多个 GitLab 群组造成权限扩散。第三，离职处理：IdP 中禁用用户后，SCIM 会将其从群组移除，但不会自动删除 GitLab 账号，需要配合定期审计清理。

四、细粒度权限模型：角色、继承与例外

GitLab 的权限由“角色（Role）+ 作用域（Scope）”共同决定。群组和项目各有五个基础角色：Guest、Reporter、Developer、Maintainer、Owner。角色沿命名空间树继承，子群组和项目默认继承父群组成员的角色。

设计细粒度权限时，核心原则是最小权限 + 显式例外。例如，外包人员只需读取代码和提交 Issue，应授予 Reporter；CI 机器人需要推送镜像和触发流水线，应授予 Developer 并配合保护分支；只有平台管理员才授予 Owner。对于需要跨群组访问的场景，优先使用“共享项目”而非直接添加成员，因为共享关系可审计、可撤销。

保护分支与保护环境是权限模型的重要补充。即使某用户是 Developer，若目标分支被保护且未列入允许推送列表，其推送仍会被拒绝。因此，权限设计不能只看角色，还要看分支保护规则、环境部署权限、变量访问级别这三层约束。

五、落地检查清单

在完成上述设计后，建议用以下清单做一次自检，确保身份与权限两条链路闭合：

最后强调一个工程习惯：所有权限变更都应通过 IdP 或 GitLab API 完成，避免在 Web 界面手工添加成员。手工操作无法被 SCIM 覆盖，会在下一次同步时产生冲突，也会让审计日志失去一致性。把群组层级、SSO 属性映射、SCIM 组映射、角色基线这四份配置纳入版本管理，权限体系才真正可维护、可审计、可复现。