Label Studio Enterprise LDAP 认证配置实战通过环境变量将 AD/LDAP 目录接入标注平台【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本指南基于官方文档 docs/source/guide/auth_ldap.md 展开系统讲解如何在 Label Studio Enterprise本地部署版中启用 LDAP 认证、把 LDAP 用户与组织角色、工作区进行映射并开启 TLS 加密连接。读完本文你将掌握一套完整的、可直接复制到 Docker 环境变量文件中的 LDAP 接入方案实现用企业目录账号登录标注平台 目录组自动映射权限的实战能力。版本边界提示LDAP 认证是 Label Studio Enterprise Edition 的专有能力且仅适用于本地on-prem安装。若你正在使用社区版Community Edition该功能不可用可参阅 label_studio_compare.md 了解各版本功能差异。本文涉及的 Enterprise 专属行为以官方文档与仓库源码中可见的配置证据为准。LDAP 认证在 Label Studio 中的定位在 Label Studio Enterprise 的身份体系中LDAP 与 SSO、SCIM 分工不同。官方概览文档 admin_auth.md 明确指出SSO 负责认证authenticationSCIM 负责用户与组的自动供给provisioning而 LDAP 主要面向本地on-prem部署——使用者在自托管环境中直接对企业目录如 Active Directory / OpenLDAP完成认证同时将 RBAC 与项目/工作区权限继续保留在 Label Studio 内管理。启用 LDAP 认证后可以获得两个核心收益统一登录用户直接使用企业目录账号用户名或邮箱登录 Label Studio UI无需单独维护平台密码权限自动映射将特定 LDAP 组映射到 Label Studio Enterprise 的roles组织角色与workspaces工作区从而更轻松地搭建基于角色的访问控制RBAC与项目访问体系替代逐个成员手工授权详见 manage_users.md。从仓库源码可以印证 LDAP 在认证链路中的位置。在 label_studio/core/settings/base.py 中默认的认证后端为AUTH_USER_MODEL users.User AUTHENTICATION_BACKENDS [ rules.permissions.ObjectPermissionBackend, django.contrib.auth.backends.ModelBackend, ] USE_USERNAME_FOR_LOGIN False即社区默认使用 Django 的ModelBackend平台内用户名/密码认证且USE_USERNAME_FOR_LOGIN默认为False默认只允许用邮箱登录。Enterprise 版在启用 LDAP 后会在认证后端链中注入基于django-auth-ldap的 LDAP Backend——该底层库的日志记录器已在 label_studio/core/settings/base.py 中配置django_auth_ldap: {level: os.environ.get(LOG_LEVEL, DEBUG)}日志级别跟随全局LOG_LEVEL环境变量默认DEBUG便于排障时追踪 LDAP 绑定与搜索过程。此外label_studio/core/settings/base.py 中RoleSourceEnum枚举明确包含(ldap, LDAP)这一角色来源说明经由 LDAP 映射获得的组织角色在系统中会被标记来源为ldap与 manual手工、saml、scim 等来源区分管理。前置条件与启用原则在动手配置前请注意以下启用原则启用后原生认证即失效一旦开启 LDAP 认证用户将不能再使用 Label Studio 原生认证登录 UI所有登录请求都改由目录服务裁决。请务必先完成 LDAP 连通性与映射验证再正式切换。认证与授权在平台内完成LDAP 只负责你是谁认证登录后的组织角色与工作区权限仍由 Label Studio Enterprise 分配可通过环境变量自动映射也可在平台内手工调整除非按下文关闭手工管理。配置载体为 Docker 环境变量所有 LDAP 参数均通过 Docker 的环境变量文件env file注入无需修改代码或数据库。基础认证配置一份可直接套用的环境变量文件官方文档给出了完整的 LDAP 环境变量示例以下是逐项展开后的完整配置务必替换为你自己的目录服务器实际值# 1. 启用 LDAP 认证 AUTH_LDAP_ENABLED1 # 2. 目录服务器地址使用 ldaps:// 保证连接加密 AUTH_LDAP_SERVER_URIldaps://ldap.example.com # 3. 服务账号bind DN与密码用于绑定查询目录 AUTH_LDAP_BIND_DNuiduser,ousysadmins,o123abc,dczexample,dccom AUTH_LDAP_BIND_PASSWORDpassword123 # 4. 允许用户使用用户名而不只是邮箱登录 Label Studio USE_USERNAME_FOR_LOGIN1 # 5. 简单用户搜索基于 DN 模板直接定位用户 # %(user)s 会被替换为用户输入的登录标识 AUTH_LDAP_USER_DN_TEMPLATEuid%(user)s,ouUsers,o123abc,dcexample,dccom # 6. 指定组织所有者邮箱所有 LDAP 用户将被分配到该组织 # 警告该邮箱对应的用户必须在任何 LDAP 用户登录之前完成注册 AUTH_LDAP_ORGANIZATION_OWNER_EMAILheartexheartex.net # 7. 用户属性映射从 LDAP 记录中取出以下字段填充用户资料 AUTH_LDAP_USER_ATTR_MAP_FIRST_NAMEfirstName # 名 AUTH_LDAP_USER_ATTR_MAP_LAST_NAMElastName # 姓 AUTH_LDAP_USER_ATTR_MAP_EMAILmail # 邮箱对应 AUTH_LDAP_USER_QUERY_FIELDemail 场景 AUTH_LDAP_USER_ATTR_MAP_USERNAMEsAMAccountName # 用户名对应 AUTH_LDAP_USER_QUERY_FIELDusername 场景 # 8. 在 Label Studio 中查询认证用户的字段可选 email 或 username AUTH_LDAP_USER_QUERY_FIELDemail # 9. 组搜索参数 AUTH_LDAP_GROUP_SEARCH_BASE_DNouUsers,ogroup-id,dcexample,dccom AUTH_LDAP_GROUP_SEARCH_FILTER_STR(objectClassgroupOfNames) AUTH_LDAP_GROUP_TYPEou关键参数语义说明环境变量作用取值要点AUTH_LDAP_ENABLED总开关1启用置空或0关闭AUTH_LDAP_SERVER_URI目录服务器地址生产环境务必使用ldaps://加密协议也支持ldap://明文仅限受信内网AUTH_LDAP_BIND_DN/AUTH_LDAP_BIND_PASSWORD绑定查询凭据使用具备只读查询权限的服务账号 DN避免使用高权限管理员账号USE_USERNAME_FOR_LOGIN是否允许用户名登录与 label_studio/core/settings/base.py 中的默认值False相反设为1后登录表单同时接受用户名AUTH_LDAP_USER_DN_TEMPLATE用户定位模板模板中的%(user)s占位符会被登录输入替换实现简单搜索式的用户定位AUTH_LDAP_ORGANIZATION_OWNER_EMAIL组织归属指定指定平台内已注册用户的邮箱作为组织归属锚点该用户必须先注册否则 LDAP 用户登录时无法确定组织AUTH_LDAP_USER_ATTR_MAP_*LDAP 属性 → 平台用户字段映射FIRST_NAME/LAST_NAME对应姓名EMAIL对应邮箱USERNAME对应用户名取值须与目录中的真实属性名一致AD 常用sAMAccountName、mailOpenLDAP 常用givenName、sn、mail、uidAUTH_LDAP_USER_QUERY_FIELD平台侧查询字段email或username须与上面属性映射的字段配对使用AUTH_LDAP_GROUP_SEARCH_BASE_DN组搜索基 DN指定从目录树的哪个分支开始搜索组AUTH_LDAP_GROUP_SEARCH_FILTER_STR组搜索过滤器如(objectClassgroupOfNames)、AD 中常用(objectClassgroup)AUTH_LDAP_GROUP_TYPE组的类型标识示例中为ou按目录结构实际情况填写如group、groupOfNames等登录标识与属性映射的配合逻辑AUTH_LDAP_USER_QUERY_FIELD决定用户登录时平台侧拿哪个字段去匹配email或username而AUTH_LDAP_USER_ATTR_MAP_EMAIL/AUTH_LDAP_USER_ATTR_MAP_USERNAME决定登录成功后从 LDAP 记录中取哪个属性来填充这两个平台字段。例如官方示例选择AUTH_LDAP_USER_QUERY_FIELDemail则配合AUTH_LDAP_USER_ATTR_MAP_EMAILmail——用户以邮箱登录平台以 LDAP 的mail属性作为邮箱来源若希望用用户名登录Windows AD 场景常用则改为AUTH_LDAP_USER_QUERY_FIELDusername并配合AUTH_LDAP_USER_ATTR_MAP_USERNAMEsAMAccountName。进阶递归扫描多个 LDAP 组默认的AUTH_LDAP_USER_DN_TEMPLATE属于简单搜索它通过 DN 模板精确定位单个用户不支持跨多个组递归查找。当你的用户分散在多个 LDAP 组中、希望统一授权登录时可以改为递归扫描方案替换基础配置中的第 5 项# 将该参数留空禁用 DN 模板的简单搜索 AUTH_LDAP_USER_DN_TEMPLATE # 指定允许登录的多个组用英文分号 ; 分隔 AUTH_LDAP_USER_SEARCH_BASESouguests,dcdomain,dccom;ouowners,dcdomain,dccom要点AUTH_LDAP_USER_SEARCH_BASES中的每个条目都是一个搜索基 DN系统会在这些基下递归扫描组成员凡命中者即获得登录授权组之间用;分隔与下文角色映射、工作区映射中的分隔约定一致两种方案二选一要么用AUTH_LDAP_USER_DN_TEMPLATE精确模板要么用AUTH_LDAP_USER_SEARCH_BASES递归搜索此时模板必须留空官方文档提示此处原写法AUTH_LDAP_USER_ON_TEMPLATE即指该模板参数。用户角色映射LDAP 组 → 组织角色启用 LDAP 后可将目录组自动映射到 Label Studio Enterprise 的组织角色实现进组即授权。组织角色对应关系可参考 label_studio/core/settings/base.py 中的角色枚举Owner所有者、Administrator管理员、Manager经理、Reviewer审核员、Annotator标注员、Deactivated已停用、Not Activated未激活。映射使用;分隔多个组一个角色可对应多个目录组AUTH_LDAP_ORGANIZATION_ROLE_ADMINISTRATORcnadmins,ouusers,o123abc,dcexample,dccom AUTH_LDAP_ORGANIZATION_ROLE_MANAGERcnmanagers,ouusers,o123abc,dcexample,dccom AUTH_LDAP_ORGANIZATION_ROLE_REVIEWERcnreviewers,ouusers,o123abc,dcexample,dccom AUTH_LDAP_ORGANIZATION_ROLE_ANNOTATORcnannotators,ouusers,o123abc,dcexample,dccom;cnguests,ouusers,o123abc,dcexample,dccom AUTH_LDAP_ORGANIZATION_ROLE_NOT_ACTIVATEDcnnot,ouusers,o123abc,dcexample,dccom AUTH_LDAP_ORGANIZATION_ROLE_DEACTIVATEDcndeactivated,ouusers,o123abc,dcexample,dccom语义说明AUTH_LDAP_ORGANIZATION_ROLE_ADMINISTRATOR落入该组的用户自动获得 Administrator 角色AUTH_LDAP_ORGANIZATION_ROLE_MANAGER/_REVIEWER/_ANNOTATOR分别映射 Manager、Reviewer、AnnotatorAUTH_LDAP_ORGANIZATION_ROLE_NOT_ACTIVATED映射未激活状态如新入职未启用账号AUTH_LDAP_ORGANIZATION_ROLE_DEACTIVATED映射已停用状态如离职账号登录将被拒绝或降级示例中_ANNOTATOR同时映射了cnannotators与cnguests两个组展示了一角色多组的写法。结合源码可见这些由映射获得的组织角色在系统内部会以RoleSourceEnum中的ldap来源记录label_studio/core/settings/base.py从而与手工分配、SAML、SCIM 分配的角色来源区分开便于审计与追溯。工作区映射LDAP 组 → 工作区工作区Workspace是 Label Studio Enterprise 组织内隔离项目与成员的重要单元。工作区映射使用JSON 格式键为工作区标题Workspace Title值为对应的 LDAP 组同样使用;分隔多个组。注意整个 JSON 要用单引号包裹避免 Shell 对双引号做插值AUTH_LDAP_ORGANIZATION_WORKSPACES{Workspace 1:cnteam1,ouusers,o60cbc901ec2e8e387a3b2d3e,dcjumpcloud,dccom,Workspace 2:cnteam2,ouusers,o60cbc901ec2e8e387a3b2d3e,dcjumpcloud,dccom}该示例的含义cnteam1,...组的用户自动加入Workspace 1cnteam2,...组的用户自动加入Workspace 2。若要一个工作区对应多个组可将值写为cnteam1,ouusers,...;cnteam3,ouusers,...形式。完全由 LDAP 接管用户权限管理如果你希望平台内的角色与工作区分配完全由 LDAP 映射决定不再允许通过 Label Studio 的 UI/API 手工分配可在环境变量文件中追加以下三项MANUAL_PROJECT_MEMBER_MANAGEMENT0 MANUAL_WORKSPACE_MANAGEMENT0 MANUAL_ROLE_MANAGEMENT0设置说明MANUAL_PROJECT_MEMBER_MANAGEMENT0禁用平台内手工管理项目成员MANUAL_WORKSPACE_MANAGEMENT0禁用平台内手工管理工作区成员MANUAL_ROLE_MANAGEMENT0禁用平台内手工分配组织角色。这三项置 0 后Label Studio 的 API 与 UI 将不再提供针对单个用户的角色/工作区分配入口权限完全依赖环境变量文件中的 LDAP 映射规则实现目录即单一事实来源source of truth。这也意味着任何权限调整都必须回到目录服务器与映射配置上完成适合权限治理要求严格的团队。为 LDAP/Active Directory 启用 TLS 加密默认使用ldap://明文协议存在凭据泄露风险强烈建议开启 TLS。在环境变量文件中增加AUTH_LDAP_CONNECTION_OPTIONSOPT_X_TLS_CACERTFILE/path/to/cert.crt;OPT_X_TLS_NEWCTX0参数说明OPT_X_TLS_CACERTFILE指向 CA 证书文件路径用于校验目录服务器证书若目录服务器使用自签名证书必须将OPT_X_TLS_NEWCTX0作为AUTH_LDAP_CONNECTION_OPTIONS的最后一个条目追加否则 TLS 上下文可能无法正确初始化导致连接失败多选项之间同样使用;分隔该变量的值会被透传给底层django-auth-ldap的AUTH_LDAP_CONNECTION_OPTIONS设置对应其日志配置 label_studio/core/settings/base.py 所在的同一 Django 配置体系作用于 LDAP 连接的 TLS/网络参数。常见问题与排障建议登录总失败如何定位由于django_auth_ldap的日志级别默认跟随LOG_LEVELlabel_studio/core/settings/base.py在DEBUG级别下可在应用日志中看到绑定bind、搜索search与用户映射全过程。常见原因包括AUTH_LDAP_BIND_DN/BIND_PASSWORD无查询权限、AUTH_LDAP_USER_DN_TEMPLATE的 DN 拼写与目录结构不符、AUTH_LDAP_USER_QUERY_FIELD与属性映射不配对。AUTH_LDAP_ORGANIZATION_OWNER_EMAIL报错该邮箱对应的用户必须在任何 LDAP 用户登录之前已在平台注册否则系统无法确定 LDAP 用户应归属的组织。请先手工创建或通过邀请流程注册该组织所有者账号。用户能认证但权限不对检查组 DN 与角色/工作区映射是否精确匹配目录中的真实 DN注意大小写与ou/cn/o/dc层级映射采用精确 DN 匹配;分隔的多个组都会被匹配。自签名证书连接失败确认已按上文在AUTH_LDAP_CONNECTION_OPTIONS末尾追加OPT_X_TLS_NEWCTX0并保证证书文件路径在容器内可读注意 Docker 挂载与权限。版本边界确认LDAP 认证仅限 Enterprise 且仅限 on-prem 部署云版SaaS请改用 SSOSAML与 SCIM 方案详见 admin_auth.md 与 auth_setup.md。总结LDAP 认证为 Label Studio Enterprise 本地部署提供了企业目录账号 平台内 RBAC的组合方案通过一组环境变量即可完成目录连接、用户属性同步、组织归属指定并通过角色映射与工作区映射把目录组自动翻译为平台权限配合MANUAL_*_MANAGEMENT0可实现权限治理完全外置通过AUTH_LDAP_CONNECTION_OPTIONS可加固 TLS 链路。配置全程无需改动平台代码仓库侧的证据label_studio/core/settings/base.py 的认证后端与USE_USERNAME_FOR_LOGIN默认值、RoleSourceEnum 中的ldap来源、django_auth_ldap日志配置也印证了该机制在认证链与角色溯源体系中的落点。建议在生产环境切换前先在测试环境完成全部映射验证。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
