MLflow Authentication Python API 深度指南AuthServiceClient 与认证实体模型全解析【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 作为面向 Agent、LLM 与机器学习模型的开源 AI 工程平台其自带的 Basic Authentication 插件为追踪服务器提供了用户、角色RBAC与资源权限的一整套访问控制能力。本指南以官方 API 参考文档 docs/api_reference/source/auth/python-api.rst 为骨架系统讲解mlflow.server.auth.client.AuthServiceClient的全部客户端方法与mlflow.server.auth.entities中的实体数据模型并结合仓库源码剖析其底层 REST 调用链、权限等级设计与测试验证方式帮助你用 Python 代码完整地管理 MLflow 认证体系。一、认证插件与 Python API 的关系MLflow 追踪服务器默认不启用身份认证需要启动 Basic Authentication 插件mlflow.server.auth后才能使用认证能力。该插件在 mlflow/server/auth/ 目录下实现核心模块包括client.py面向用户的AuthServiceClient客户端类即本文主角entities.py用户、角色、权限等 REST 响应的数据模型routes.py全部认证相关 REST 端点路径定义permissions.py权限等级READ/USE/EDIT/MANAGE与资源类型常量config.py与basic_auth.ini认证插件的配置读取与默认配置。官方 API 文档正是通过 Sphinx 的autoclass与automodule指令将client.py与entities.py中的公开 API 自动渲染成 python-api.rst 页面。因此Authentication Python API 的完整内容就是客户端方法 实体模型两部分下文逐一展开。二、AuthServiceClient认证服务的 Python 客户端AuthServiceClient定义在 mlflow/server/auth/client.py#L35官方文档对其定位的说明是面向启用了默认基本认证插件的 MLflow 追踪服务器的客户端并明确推荐使用mlflow.server.get_app_client()工厂函数来实例化而非直接调用构造函数。2.1 实例化方式构造函数签名只有一个必填参数tracking_uri即本地或远程追踪服务器的地址from mlflow.server.auth.client import AuthServiceClient # 直接构造不推荐 client AuthServiceClient(http://localhost:5000) # 推荐通过应用客户端工厂构造 client mlflow.server.get_app_client(basic-auth, http://localhost:5000)get_app_client实现在 mlflow/server/init.py#L245它根据app_name例如basic-auth从 Python 入口点mlflow.app.client中查找并加载对应的客户端类找不到时抛出MlflowException。使用工厂方法的优势在于未来认证插件实现变化时调用方代码无需改动。2.2 底层 REST 调用机制AuthServiceClient的所有方法都收敛到私有方法_requestclient.py#L49def _request(self, endpoint, method, *, expected_status: int 200, **kwargs): host_creds get_default_host_creds(self.tracking_uri) resp http_request(host_creds, endpoint, method, **kwargs) resp verify_rest_response(resp, endpoint, expected_statusexpected_status) if resp.status_code 204 or not resp.content: return {} return resp.json()其工作流程为通过get_default_host_creds(tracking_uri)解析主机凭据——这也是为什么所有需要鉴权的操作都要求先配置MLFLOW_TRACKING_USERNAME与MLFLOW_TRACKING_PASSWORD环境变量用http_request发起 HTTP 请求端点路径来自routes.py中的常量用verify_rest_response校验响应状态码默认期望 200204 No Content或空响应体统一返回{}否则解析 JSON。端点路径集中在 mlflow/server/auth/routes.py例如用户管理端点CREATE_USER /api/2.0/mlflow/users/create、GET_USER /api/2.0/mlflow/users/get角色管理端点RBAC 部分则统一走/api/2.0/mlflow/roles/*version3路径。每个端点同时暴露 REST 与 AJAX 两个变体分别供 Python 客户端与 MLflow 前端 UI 使用。三、用户管理 APIAuthServiceClient提供 5 个用户管理方法覆盖用户的创建、查询、改密、管理员授权与删除全生命周期。3.1 create_user 创建用户client AuthServiceClient(tracking_uri) user client.create_user(newuser, newpassword) print(fuser_id: {user.id}) print(fusername: {user.username}) print(fpassword_hash: {user.password_hash}) print(fis_admin: {user.is_admin})输出示例来自官方 docstringuser_id: 3 username: newuser password_hash: REDACTED is_admin: False要点参数username与password其中 password 不允许为空字符串若用户名已存在抛出mlflow.exceptions.RestException返回User实体对象其password_hash属性恒为REDACTED——这是 entities.py#L51 中User.from_json的刻意设计哈希值只允许在服务端存储绝不通过 REST API 回传明文哈希新建用户默认is_adminFalse。3.2 get_user 查询用户export MLFLOW_TRACKING_USERNAMEadmin export MLFLOW_TRACKING_PASSWORDpasswordclient AuthServiceClient(tracking_uri) client.create_user(newuser, newpassword) user client.get_user(newuser)用户不存在时抛出RestException。注意调用前必须先设置管理员凭据环境变量因为用户管理端点要求认证。3.3 update_user_password 修改密码# 管理员路径 —— 无需 current_password client.update_user_password(newuser, anotherpassword) # 自助服务路径 —— 必须提供 current_password client.update_user_password(newuser, thirdpassword, current_passwordanotherpassword)方法签名client.py#L145def update_user_password(self, username: str, password: str, current_password: str | None None)设计规则current_password为可选项但用户修改自己的密码自助服务时必填否则服务端拒绝请求管理员修改他人密码时可省略该参数底层发送PATCH /api/2.0/mlflow/users/update-password若用户不存在、或 current_password 缺失/错误抛出RestException。3.4 update_user_admin 设置管理员client.update_user_admin(newuser, True)将is_admin更新为True/False发送PATCH /api/2.0/mlflow/users/update-admin用户不存在时抛出RestException。3.5 delete_user 删除用户client.delete_user(newuser)发送DELETE /api/2.0/mlflow/users/delete。删除操作同样受管理员权限约束。3.6 用户管理 API 一览方法HTTP端点REST 路径关键行为create_userPOST/mlflow/users/create重名抛异常password 不可为空get_userGET/mlflow/users/get不存在抛异常update_user_passwordPATCH/mlflow/users/update-password自助改密需current_passwordupdate_user_adminPATCH/mlflow/users/update-admin设置/取消管理员delete_userDELETE/mlflow/users/delete删除指定用户测试用例位于 tests/server/auth/test_client.py例如test_create_user、test_get_user分别验证了未认证访问抛UNAUTHENTICATEDYou are not authenticated.与非管理员调用抛PERMISSION_DENIEDPermission denied.的异常路径可作为调用方错误处理的参照。四、角色管理 APIRBAC角色管理是AuthServiceClient在# ---- Role management (RBAC) ----注释client.py#L256之后集中提供的能力让管理员把一组权限打包成角色再批量授予用户。4.1 角色的创建、查询与列表# 创建角色指定 workspace 与名称description 可选 role client.create_role(workspacedefault, namedata-scientist, descriptionML training access) print(role.id, role.name, role.workspace, role.description) # 按 ID 查询角色 role client.get_role(role_id1) # 列出某 workspace 下的全部角色 roles client.list_roles(workspacedefault) # 跨 workspace 列出全部角色admin-only服务端强制校验 all_roles client.list_all_roles()签名说明create_role(workspace, name, descriptionNone) - Roleget_role(role_id) - Rolerole_id会被转为字符串作为查询参数list_roles(workspace) - list[Role]list_all_roles()与list_roles共用LIST_ROLES端点但省略workspace参数后返回跨 workspace 的全量列表仅管理员可用服务端强制校验见 client.py#L339-L343。4.2 角色的更新与删除# 更新角色名称与描述均可选 role client.update_role(role_id1, nameml-engineer, descriptionUpdated) # 删除角色 client.delete_role(role_id1)update_role只把非 None 字段放入请求体发送PATCH /api/2.0/mlflow/roles/update。4.3 角色权限RolePermission管理角色本身不携带权限需要向角色添加资源级权限条目# 给角色添加一条权限对实验资源类型、匹配模式 42 的实验授予 EDIT rp client.add_role_permission( role_id1, resource_typeexperiment, resource_pattern42, permissionEDIT, ) print(rp.id, rp.role_id, rp.resource_type, rp.resource_pattern, rp.permission) # 列出角色全部权限条目 perms client.list_role_permissions(role_id1) # 修改某条权限条目的权限等级 rp client.update_role_permission(role_permission_id1, permissionMANAGE) # 移除权限条目 client.remove_role_permission(role_permission_id1)resource_pattern是资源匹配模式可用于匹配单个资源 ID 或一组资源结合 workspace 与资源类型共同定位目标。权限等级取值必须是READ/USE/EDIT/MANAGE之一详见下文权限模型一节。4.4 用户与角色的绑定# 把角色分配给用户 assignment client.assign_role(usernamealice, role_id1) print(assignment.id, assignment.user_id, assignment.role_id) # 解除角色 client.unassign_role(usernamealice, role_id1) # 查看某用户拥有的角色 roles client.list_user_roles(usernamealice) # 查看某角色下的全部用户-角色绑定 assignments client.list_role_users(role_id1)角色相关方法的端点路径集中在 routes.py#L53-L78全部为/api/2.0/mlflow/roles/*version3与/api/2.0/mlflow/users/roles/*系列并成对提供 AJAX 路径供前端使用。五、统一用户权限便捷 API在# ---- Unified per-user permission convenience APIs ----注释client.py#L345之后AuthServiceClient提供了一组面向单个用户的统一授权/撤销/检查便捷方法用统一的(resource_type, resource_id)形态覆盖资源授权并保留传统按资源 MANAGE 委托的语义。# 授予用户对某资源的权限 client.grant_user_permission( usernamealice, resource_typeexperiment, resource_id42, permissionEDIT, ) # 撤销用户对某资源的权限 client.revoke_user_permission(usernamealice, resource_typeexperiment, resource_id42) # 查询用户对某资源的有效权限 result client.get_user_permission( usernamealice, resource_typeexperiment, resource_id42 ) print(result.allowed) # 是否允许访问对应 Permission.can_use print(result.permission) # 解析后的有效权限名如 EDIT从 routes.py 的注释可知routes.py#L16-L26grant/revoke会写入用户在活动 workspace 下的合成角色__user_id__而get_user_permission对应GET /mlflow/users/permissions/get按照与运行时鉴权相同的方式解析用户的有效权限因此调用方看到的检查结果与实际请求的鉴权结果完全一致。返回的GetUserPermissionResult中allowed镜像Permission.can_use常规访问层permission为解析后的有效权限名见 entities.py#L502-L525。六、entities 实体数据模型mlflow/server/auth/entities.py 定义了认证 API 的所有数据载体。它们普遍具备三个特征只读property访问、to_json()序列化、from_json()反序列化。下文按功能分组说明。6.1 用户实体 Userclass User: id # 用户 ID username # 用户名 password_hash # 恒为 REDACTEDfrom_json 强制脱敏 is_admin # 是否为管理员可写属性User.to_json()输出{id, username, is_admin}不含密码哈希from_json将哈希固定为REDACTEDentities.py#L46-L53从根源上杜绝哈希泄露。6.2 角色相关实体Roleentities.py#L353id、name可写、workspace、description可写、permissionsRolePermission列表。from_json在缺少 workspace 字段时回退到DEFAULT_WORKSPACE_NAME。RolePermissionentities.py#L416id、role_id、resource_type、resource_pattern、permission可写。UserRoleAssignmententities.py#L468id、user_id、role_id表示用户-角色绑定关系。6.3 资源权限实体针对不同类型的资源认证系统各自定义了权限实体字段模式统一为(资源标识, user_id, permission)实体资源标识字段适用资源ExperimentPermissionexperiment_id实验RegisteredModelPermissionnameworkspace注册模型ScorerPermissionexperiment_id,scorer_name在线评分器GatewaySecretPermissionsecret_idGateway 密钥GatewayEndpointPermissionendpoint_idGateway 端点GatewayModelDefinitionPermissionmodel_definition_idGateway 模型定义MCPServerPermissionnameMCP 服务器RegisteredModelPermission与ScorerPermission拥有两个资源标识字段分别用resolve_entity_workspace_name解析 workspace。这些实体的存在说明认证粒度不仅覆盖传统 ML 资源实验、模型也延伸到 Gateway、MCP 等新一代 Agent/LLM 能力面。6.4 查询结果与工作区权限GetUserPermissionResultentities.py#L502allowed: boolpermission: strget_user_permission的返回类型。WorkspacePermissionentities.py#L528workspace、user_id、permission构造时强制校验三者非空缺失即抛MlflowException.invalid_parameter_value额外暴露只读属性can_use即get_permission(permission).can_use。from_json同样对缺失字段做显式校验。七、权限等级模型与资源类型底层支撑理解AuthServiceClient的权限参数取值必须回到 mlflow/server/auth/permissions.py 中的权限模型。7.1 五种权限等级Permission是一个 dataclass拥有can_read / can_use / can_update / can_delete / can_manage五个能力位permissions.py#L7-L14。系统预定义了五个等级permissions.py#L17-L60权限名can_readcan_usecan_updatecan_deletecan_manage语义READ✅❌❌❌❌只读USE✅✅❌❌❌可使用EDIT✅✅✅❌❌可编辑MANAGE✅✅✅✅✅完全管理NO_PERMISSIONS❌❌❌❌❌无权限权限之间有优先级排序PERMISSION_PRIORITYNO_PERMISSIONS READ USE EDIT MANAGEmax_permission(a, b)据此合并取较高者。7.2 资源类型与可授权限约束具体资源类型RESOURCE_TYPE_EXPERIMENT、RESOURCE_TYPE_REGISTERED_MODEL、RESOURCE_TYPE_PROMPT、RESOURCE_TYPE_SCORER、RESOURCE_TYPE_GATEWAY_SECRET、RESOURCE_TYPE_GATEWAY_ENDPOINT、RESOURCE_TYPE_GATEWAY_MODEL_DEFINITION、RESOURCE_TYPE_MCP_SERVER只接受READ/USE/EDIT/MANAGE显式NO_PERMISSIONS被拒绝——因为缺失授权 配置的 default_permission已经足以表达无访问权工作区级资源类型RESOURCE_TYPE_WORKSPACEresource_pattern必须为*只接受USE工作区成员访问 创建资源 继承 default_permission与MANAGE额外获得角色/用户管理工作区管理权READ/EDIT被有意排除permissions.py#L96-L134。所有非法的权限名、资源类型或不匹配的组合都会抛出MlflowExceptionINVALID_PARAMETER_VALUE在调用add_role_permission等 API 前即可被服务端校验拦截。八、配置与认证前提要使用上述 Python API需要先以 Basic Authentication 插件模式启动追踪服务器并配置认证参数。8.1 配置文件 basic_auth.ini默认配置位于 mlflow/server/auth/basic_auth.ini[mlflow] default_permission READ database_uri sqlite:///basic_auth.db admin_username admin admin_password password1234 authorization_function mlflow.server.auth:authenticate_request_basic_auth # 为 true 时用户继承 reserved default workspace 的 default_permission grant_default_workspace_access false # workspace_cache_max_size 10000 # workspace_cache_ttl_seconds 3600 # auth_cache_max_size 10000 # auth_cache_ttl_seconds 08.2 配置项语义来自 config.pyread_auth_config()mlflow/server/auth/config.py#L30读取该文件并解析为AuthConfigNamedTupledefault_permission资源无显式授权时用户的默认权限默认READdatabase_uri认证数据的存储后端默认 SQLiteadmin_username/admin_password初始管理员凭据authorization_function鉴权函数入口默认mlflow.server.auth:authenticate_request_basic_auth可通过 mlflow/environment_variables.py 中的MLFLOW_AUTH_CONFIG_PATH指定自定义配置文件路径grant_default_workspace_access用户是否继承 default workspace 的默认权限默认 falseworkspace_cache_max_size/workspace_cache_ttl_seconds资源到工作区查询缓存默认 10000 / 3600 秒auth_cache_max_size/auth_cache_ttl_seconds用户名/密码校验缓存默认关闭TTL0开启后 PBKDF2 哈希比对在同一 (user, password) 上每个 TTL 窗口内最多执行一次文档注释称请求密集型鉴权工作负载可带来约 3 倍吞吐提升但缓存位于各 worker 进程内会引入最长一个 TTL 的陈旧窗口多 worker 部署与带外变更直接 SQL、外部 IdP 同步需要自行权衡read_database_uri可选的只读数据库 URI。8.3 客户端凭据所有需要鉴权的 API 调用都要通过环境变量携带凭据export MLFLOW_TRACKING_USERNAMEadmin export MLFLOW_TRACKING_PASSWORDpassword未认证调用将抛出RestExceptionUNAUTHENTICATEDYou are not authenticated.已认证但权限不足则抛出PERMISSION_DENIEDPermission denied.这与测试文件 tests/server/auth/test_client.py 中assert_unauthenticated/assert_unauthorized两个辅助上下文管理器断言的行为完全一致。九、测试验证与最佳实践仓库在 tests/server/auth/ 下对客户端 API 提供了成体系的测试覆盖test_client.py用户管理全流程创建、查询、改密、管理员、删除、当前用户查询以及未认证/越权异常路径test_client_rbac.py角色 CRUD、角色权限条目、用户-角色绑定的行为验证test_client_workspace.pyworkspace 相关授权行为验证。测试通过_init_server(appmlflow.server.auth:create_app, ...)以隔离的 SQLite 后端启动真实 Flask 服务器test_client.py#L43-L59因此是端到端的 REST 验证。实际集成时的建议一律通过get_app_client(basic-auth, tracking_uri)获取客户端避免直接依赖AuthServiceClient的实现细节密码哈希只读不看User.password_hash恒为REDACTED不要依赖它做任何校验逻辑区分管理员路径与自助服务路径改密时用户改自己的密码必须传current_password管理员改他人密码可省略角色权限条目的permission只能取READ/USE/EDIT/MANAGEworkspace 级授权只接受USE/MANAGE非法取值会在服务端被拒绝用get_user_permission做授权预检它按运行时鉴权同样的逻辑解析有效权限返回的allowed与permission即真实请求会看到的结果生产环境务必修改basic_auth.ini中的默认管理员密码并按需开启auth_cache_ttl_seconds注意多 worker 的陈旧窗口。十、结语MLflow Authentication Python API 以AuthServiceClient为统一入口向上提供用户、角色RBAC、角色权限与按用户便捷授权四层操作能力向下以entities实体模型承载所有 REST 响应并由permissions.py的 READ/USE/EDIT/MANAGE 权限模型与多类资源类型构成授权语义的底层支撑。配合 python-api.rst 自动生成的 API 参考、routes.py 的端点清单以及 tests/server/auth/ 的端到端测试你可以据此在团队中落地一套按角色授权、按资源管控、按用户审计的完整访问控制体系。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MLflow Authentication Python API 深度指南：AuthServiceClient 与认证实体模型全解析
MLflow Authentication Python API 深度指南AuthServiceClient 与认证实体模型全解析【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 作为面向 Agent、LLM 与机器学习模型的开源 AI 工程平台其自带的 Basic Authentication 插件为追踪服务器提供了用户、角色RBAC与资源权限的一整套访问控制能力。本指南以官方 API 参考文档 docs/api_reference/source/auth/python-api.rst 为骨架系统讲解mlflow.server.auth.client.AuthServiceClient的全部客户端方法与mlflow.server.auth.entities中的实体数据模型并结合仓库源码剖析其底层 REST 调用链、权限等级设计与测试验证方式帮助你用 Python 代码完整地管理 MLflow 认证体系。一、认证插件与 Python API 的关系MLflow 追踪服务器默认不启用身份认证需要启动 Basic Authentication 插件mlflow.server.auth后才能使用认证能力。该插件在 mlflow/server/auth/ 目录下实现核心模块包括client.py面向用户的AuthServiceClient客户端类即本文主角entities.py用户、角色、权限等 REST 响应的数据模型routes.py全部认证相关 REST 端点路径定义permissions.py权限等级READ/USE/EDIT/MANAGE与资源类型常量config.py与basic_auth.ini认证插件的配置读取与默认配置。官方 API 文档正是通过 Sphinx 的autoclass与automodule指令将client.py与entities.py中的公开 API 自动渲染成 python-api.rst 页面。因此Authentication Python API 的完整内容就是客户端方法 实体模型两部分下文逐一展开。二、AuthServiceClient认证服务的 Python 客户端AuthServiceClient定义在 mlflow/server/auth/client.py#L35官方文档对其定位的说明是面向启用了默认基本认证插件的 MLflow 追踪服务器的客户端并明确推荐使用mlflow.server.get_app_client()工厂函数来实例化而非直接调用构造函数。2.1 实例化方式构造函数签名只有一个必填参数tracking_uri即本地或远程追踪服务器的地址from mlflow.server.auth.client import AuthServiceClient # 直接构造不推荐 client AuthServiceClient(http://localhost:5000) # 推荐通过应用客户端工厂构造 client mlflow.server.get_app_client(basic-auth, http://localhost:5000)get_app_client实现在 mlflow/server/init.py#L245它根据app_name例如basic-auth从 Python 入口点mlflow.app.client中查找并加载对应的客户端类找不到时抛出MlflowException。使用工厂方法的优势在于未来认证插件实现变化时调用方代码无需改动。2.2 底层 REST 调用机制AuthServiceClient的所有方法都收敛到私有方法_requestclient.py#L49def _request(self, endpoint, method, *, expected_status: int 200, **kwargs): host_creds get_default_host_creds(self.tracking_uri) resp http_request(host_creds, endpoint, method, **kwargs) resp verify_rest_response(resp, endpoint, expected_statusexpected_status) if resp.status_code 204 or not resp.content: return {} return resp.json()其工作流程为通过get_default_host_creds(tracking_uri)解析主机凭据——这也是为什么所有需要鉴权的操作都要求先配置MLFLOW_TRACKING_USERNAME与MLFLOW_TRACKING_PASSWORD环境变量用http_request发起 HTTP 请求端点路径来自routes.py中的常量用verify_rest_response校验响应状态码默认期望 200204 No Content或空响应体统一返回{}否则解析 JSON。端点路径集中在 mlflow/server/auth/routes.py例如用户管理端点CREATE_USER /api/2.0/mlflow/users/create、GET_USER /api/2.0/mlflow/users/get角色管理端点RBAC 部分则统一走/api/2.0/mlflow/roles/*version3路径。每个端点同时暴露 REST 与 AJAX 两个变体分别供 Python 客户端与 MLflow 前端 UI 使用。三、用户管理 APIAuthServiceClient提供 5 个用户管理方法覆盖用户的创建、查询、改密、管理员授权与删除全生命周期。3.1 create_user 创建用户client AuthServiceClient(tracking_uri) user client.create_user(newuser, newpassword) print(fuser_id: {user.id}) print(fusername: {user.username}) print(fpassword_hash: {user.password_hash}) print(fis_admin: {user.is_admin})输出示例来自官方 docstringuser_id: 3 username: newuser password_hash: REDACTED is_admin: False要点参数username与password其中 password 不允许为空字符串若用户名已存在抛出mlflow.exceptions.RestException返回User实体对象其password_hash属性恒为REDACTED——这是 entities.py#L51 中User.from_json的刻意设计哈希值只允许在服务端存储绝不通过 REST API 回传明文哈希新建用户默认is_adminFalse。3.2 get_user 查询用户export MLFLOW_TRACKING_USERNAMEadmin export MLFLOW_TRACKING_PASSWORDpasswordclient AuthServiceClient(tracking_uri) client.create_user(newuser, newpassword) user client.get_user(newuser)用户不存在时抛出RestException。注意调用前必须先设置管理员凭据环境变量因为用户管理端点要求认证。3.3 update_user_password 修改密码# 管理员路径 —— 无需 current_password client.update_user_password(newuser, anotherpassword) # 自助服务路径 —— 必须提供 current_password client.update_user_password(newuser, thirdpassword, current_passwordanotherpassword)方法签名client.py#L145def update_user_password(self, username: str, password: str, current_password: str | None None)设计规则current_password为可选项但用户修改自己的密码自助服务时必填否则服务端拒绝请求管理员修改他人密码时可省略该参数底层发送PATCH /api/2.0/mlflow/users/update-password若用户不存在、或 current_password 缺失/错误抛出RestException。3.4 update_user_admin 设置管理员client.update_user_admin(newuser, True)将is_admin更新为True/False发送PATCH /api/2.0/mlflow/users/update-admin用户不存在时抛出RestException。3.5 delete_user 删除用户client.delete_user(newuser)发送DELETE /api/2.0/mlflow/users/delete。删除操作同样受管理员权限约束。3.6 用户管理 API 一览方法HTTP端点REST 路径关键行为create_userPOST/mlflow/users/create重名抛异常password 不可为空get_userGET/mlflow/users/get不存在抛异常update_user_passwordPATCH/mlflow/users/update-password自助改密需current_passwordupdate_user_adminPATCH/mlflow/users/update-admin设置/取消管理员delete_userDELETE/mlflow/users/delete删除指定用户测试用例位于 tests/server/auth/test_client.py例如test_create_user、test_get_user分别验证了未认证访问抛UNAUTHENTICATEDYou are not authenticated.与非管理员调用抛PERMISSION_DENIEDPermission denied.的异常路径可作为调用方错误处理的参照。四、角色管理 APIRBAC角色管理是AuthServiceClient在# ---- Role management (RBAC) ----注释client.py#L256之后集中提供的能力让管理员把一组权限打包成角色再批量授予用户。4.1 角色的创建、查询与列表# 创建角色指定 workspace 与名称description 可选 role client.create_role(workspacedefault, namedata-scientist, descriptionML training access) print(role.id, role.name, role.workspace, role.description) # 按 ID 查询角色 role client.get_role(role_id1) # 列出某 workspace 下的全部角色 roles client.list_roles(workspacedefault) # 跨 workspace 列出全部角色admin-only服务端强制校验 all_roles client.list_all_roles()签名说明create_role(workspace, name, descriptionNone) - Roleget_role(role_id) - Rolerole_id会被转为字符串作为查询参数list_roles(workspace) - list[Role]list_all_roles()与list_roles共用LIST_ROLES端点但省略workspace参数后返回跨 workspace 的全量列表仅管理员可用服务端强制校验见 client.py#L339-L343。4.2 角色的更新与删除# 更新角色名称与描述均可选 role client.update_role(role_id1, nameml-engineer, descriptionUpdated) # 删除角色 client.delete_role(role_id1)update_role只把非 None 字段放入请求体发送PATCH /api/2.0/mlflow/roles/update。4.3 角色权限RolePermission管理角色本身不携带权限需要向角色添加资源级权限条目# 给角色添加一条权限对实验资源类型、匹配模式 42 的实验授予 EDIT rp client.add_role_permission( role_id1, resource_typeexperiment, resource_pattern42, permissionEDIT, ) print(rp.id, rp.role_id, rp.resource_type, rp.resource_pattern, rp.permission) # 列出角色全部权限条目 perms client.list_role_permissions(role_id1) # 修改某条权限条目的权限等级 rp client.update_role_permission(role_permission_id1, permissionMANAGE) # 移除权限条目 client.remove_role_permission(role_permission_id1)resource_pattern是资源匹配模式可用于匹配单个资源 ID 或一组资源结合 workspace 与资源类型共同定位目标。权限等级取值必须是READ/USE/EDIT/MANAGE之一详见下文权限模型一节。4.4 用户与角色的绑定# 把角色分配给用户 assignment client.assign_role(usernamealice, role_id1) print(assignment.id, assignment.user_id, assignment.role_id) # 解除角色 client.unassign_role(usernamealice, role_id1) # 查看某用户拥有的角色 roles client.list_user_roles(usernamealice) # 查看某角色下的全部用户-角色绑定 assignments client.list_role_users(role_id1)角色相关方法的端点路径集中在 routes.py#L53-L78全部为/api/2.0/mlflow/roles/*version3与/api/2.0/mlflow/users/roles/*系列并成对提供 AJAX 路径供前端使用。五、统一用户权限便捷 API在# ---- Unified per-user permission convenience APIs ----注释client.py#L345之后AuthServiceClient提供了一组面向单个用户的统一授权/撤销/检查便捷方法用统一的(resource_type, resource_id)形态覆盖资源授权并保留传统按资源 MANAGE 委托的语义。# 授予用户对某资源的权限 client.grant_user_permission( usernamealice, resource_typeexperiment, resource_id42, permissionEDIT, ) # 撤销用户对某资源的权限 client.revoke_user_permission(usernamealice, resource_typeexperiment, resource_id42) # 查询用户对某资源的有效权限 result client.get_user_permission( usernamealice, resource_typeexperiment, resource_id42 ) print(result.allowed) # 是否允许访问对应 Permission.can_use print(result.permission) # 解析后的有效权限名如 EDIT从 routes.py 的注释可知routes.py#L16-L26grant/revoke会写入用户在活动 workspace 下的合成角色__user_id__而get_user_permission对应GET /mlflow/users/permissions/get按照与运行时鉴权相同的方式解析用户的有效权限因此调用方看到的检查结果与实际请求的鉴权结果完全一致。返回的GetUserPermissionResult中allowed镜像Permission.can_use常规访问层permission为解析后的有效权限名见 entities.py#L502-L525。六、entities 实体数据模型mlflow/server/auth/entities.py 定义了认证 API 的所有数据载体。它们普遍具备三个特征只读property访问、to_json()序列化、from_json()反序列化。下文按功能分组说明。6.1 用户实体 Userclass User: id # 用户 ID username # 用户名 password_hash # 恒为 REDACTEDfrom_json 强制脱敏 is_admin # 是否为管理员可写属性User.to_json()输出{id, username, is_admin}不含密码哈希from_json将哈希固定为REDACTEDentities.py#L46-L53从根源上杜绝哈希泄露。6.2 角色相关实体Roleentities.py#L353id、name可写、workspace、description可写、permissionsRolePermission列表。from_json在缺少 workspace 字段时回退到DEFAULT_WORKSPACE_NAME。RolePermissionentities.py#L416id、role_id、resource_type、resource_pattern、permission可写。UserRoleAssignmententities.py#L468id、user_id、role_id表示用户-角色绑定关系。6.3 资源权限实体针对不同类型的资源认证系统各自定义了权限实体字段模式统一为(资源标识, user_id, permission)实体资源标识字段适用资源ExperimentPermissionexperiment_id实验RegisteredModelPermissionnameworkspace注册模型ScorerPermissionexperiment_id,scorer_name在线评分器GatewaySecretPermissionsecret_idGateway 密钥GatewayEndpointPermissionendpoint_idGateway 端点GatewayModelDefinitionPermissionmodel_definition_idGateway 模型定义MCPServerPermissionnameMCP 服务器RegisteredModelPermission与ScorerPermission拥有两个资源标识字段分别用resolve_entity_workspace_name解析 workspace。这些实体的存在说明认证粒度不仅覆盖传统 ML 资源实验、模型也延伸到 Gateway、MCP 等新一代 Agent/LLM 能力面。6.4 查询结果与工作区权限GetUserPermissionResultentities.py#L502allowed: boolpermission: strget_user_permission的返回类型。WorkspacePermissionentities.py#L528workspace、user_id、permission构造时强制校验三者非空缺失即抛MlflowException.invalid_parameter_value额外暴露只读属性can_use即get_permission(permission).can_use。from_json同样对缺失字段做显式校验。七、权限等级模型与资源类型底层支撑理解AuthServiceClient的权限参数取值必须回到 mlflow/server/auth/permissions.py 中的权限模型。7.1 五种权限等级Permission是一个 dataclass拥有can_read / can_use / can_update / can_delete / can_manage五个能力位permissions.py#L7-L14。系统预定义了五个等级permissions.py#L17-L60权限名can_readcan_usecan_updatecan_deletecan_manage语义READ✅❌❌❌❌只读USE✅✅❌❌❌可使用EDIT✅✅✅❌❌可编辑MANAGE✅✅✅✅✅完全管理NO_PERMISSIONS❌❌❌❌❌无权限权限之间有优先级排序PERMISSION_PRIORITYNO_PERMISSIONS READ USE EDIT MANAGEmax_permission(a, b)据此合并取较高者。7.2 资源类型与可授权限约束具体资源类型RESOURCE_TYPE_EXPERIMENT、RESOURCE_TYPE_REGISTERED_MODEL、RESOURCE_TYPE_PROMPT、RESOURCE_TYPE_SCORER、RESOURCE_TYPE_GATEWAY_SECRET、RESOURCE_TYPE_GATEWAY_ENDPOINT、RESOURCE_TYPE_GATEWAY_MODEL_DEFINITION、RESOURCE_TYPE_MCP_SERVER只接受READ/USE/EDIT/MANAGE显式NO_PERMISSIONS被拒绝——因为缺失授权 配置的 default_permission已经足以表达无访问权工作区级资源类型RESOURCE_TYPE_WORKSPACEresource_pattern必须为*只接受USE工作区成员访问 创建资源 继承 default_permission与MANAGE额外获得角色/用户管理工作区管理权READ/EDIT被有意排除permissions.py#L96-L134。所有非法的权限名、资源类型或不匹配的组合都会抛出MlflowExceptionINVALID_PARAMETER_VALUE在调用add_role_permission等 API 前即可被服务端校验拦截。八、配置与认证前提要使用上述 Python API需要先以 Basic Authentication 插件模式启动追踪服务器并配置认证参数。8.1 配置文件 basic_auth.ini默认配置位于 mlflow/server/auth/basic_auth.ini[mlflow] default_permission READ database_uri sqlite:///basic_auth.db admin_username admin admin_password password1234 authorization_function mlflow.server.auth:authenticate_request_basic_auth # 为 true 时用户继承 reserved default workspace 的 default_permission grant_default_workspace_access false # workspace_cache_max_size 10000 # workspace_cache_ttl_seconds 3600 # auth_cache_max_size 10000 # auth_cache_ttl_seconds 08.2 配置项语义来自 config.pyread_auth_config()mlflow/server/auth/config.py#L30读取该文件并解析为AuthConfigNamedTupledefault_permission资源无显式授权时用户的默认权限默认READdatabase_uri认证数据的存储后端默认 SQLiteadmin_username/admin_password初始管理员凭据authorization_function鉴权函数入口默认mlflow.server.auth:authenticate_request_basic_auth可通过 mlflow/environment_variables.py 中的MLFLOW_AUTH_CONFIG_PATH指定自定义配置文件路径grant_default_workspace_access用户是否继承 default workspace 的默认权限默认 falseworkspace_cache_max_size/workspace_cache_ttl_seconds资源到工作区查询缓存默认 10000 / 3600 秒auth_cache_max_size/auth_cache_ttl_seconds用户名/密码校验缓存默认关闭TTL0开启后 PBKDF2 哈希比对在同一 (user, password) 上每个 TTL 窗口内最多执行一次文档注释称请求密集型鉴权工作负载可带来约 3 倍吞吐提升但缓存位于各 worker 进程内会引入最长一个 TTL 的陈旧窗口多 worker 部署与带外变更直接 SQL、外部 IdP 同步需要自行权衡read_database_uri可选的只读数据库 URI。8.3 客户端凭据所有需要鉴权的 API 调用都要通过环境变量携带凭据export MLFLOW_TRACKING_USERNAMEadmin export MLFLOW_TRACKING_PASSWORDpassword未认证调用将抛出RestExceptionUNAUTHENTICATEDYou are not authenticated.已认证但权限不足则抛出PERMISSION_DENIEDPermission denied.这与测试文件 tests/server/auth/test_client.py 中assert_unauthenticated/assert_unauthorized两个辅助上下文管理器断言的行为完全一致。九、测试验证与最佳实践仓库在 tests/server/auth/ 下对客户端 API 提供了成体系的测试覆盖test_client.py用户管理全流程创建、查询、改密、管理员、删除、当前用户查询以及未认证/越权异常路径test_client_rbac.py角色 CRUD、角色权限条目、用户-角色绑定的行为验证test_client_workspace.pyworkspace 相关授权行为验证。测试通过_init_server(appmlflow.server.auth:create_app, ...)以隔离的 SQLite 后端启动真实 Flask 服务器test_client.py#L43-L59因此是端到端的 REST 验证。实际集成时的建议一律通过get_app_client(basic-auth, tracking_uri)获取客户端避免直接依赖AuthServiceClient的实现细节密码哈希只读不看User.password_hash恒为REDACTED不要依赖它做任何校验逻辑区分管理员路径与自助服务路径改密时用户改自己的密码必须传current_password管理员改他人密码可省略角色权限条目的permission只能取READ/USE/EDIT/MANAGEworkspace 级授权只接受USE/MANAGE非法取值会在服务端被拒绝用get_user_permission做授权预检它按运行时鉴权同样的逻辑解析有效权限返回的allowed与permission即真实请求会看到的结果生产环境务必修改basic_auth.ini中的默认管理员密码并按需开启auth_cache_ttl_seconds注意多 worker 的陈旧窗口。十、结语MLflow Authentication Python API 以AuthServiceClient为统一入口向上提供用户、角色RBAC、角色权限与按用户便捷授权四层操作能力向下以entities实体模型承载所有 REST 响应并由permissions.py的 READ/USE/EDIT/MANAGE 权限模型与多类资源类型构成授权语义的底层支撑。配合 python-api.rst 自动生成的 API 参考、routes.py 的端点清单以及 tests/server/auth/ 的端到端测试你可以据此在团队中落地一套按角色授权、按资源管控、按用户审计的完整访问控制体系。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考