单点登录

让用户和服务使用来自您的身份提供商的令牌调用您自托管的 Claude Managed Agents 服务器。

默认情况下,您的服务器接受一个共享密钥,即服务器 API 密钥。使用 “single sign-on”(单点登录)时,每个用户或服务还可以使用来自您的 OpenID Connect (OIDC) 身份提供商的令牌调用服务器。服务器根据令牌中的组为调用方分配角色。服务器 API 密钥仍可作为管理员凭据使用。

本页面介绍如何添加您的身份提供商、各角色可执行的操作,以及如何让开发者从终端登录。

添加您的身份提供商

在您的身份提供商中注册服务器

将服务器注册为一个 API,并使用类似 api://cma-server 的标识符,然后让客户端为其请求令牌。

在设置文件中列出身份提供商

在设置文件的 auth.issuers 下添加一个条目:

示例代码
auth:
  issuers:
    - name: okta
      issuer_url: https://login.example.com/oauth2/default
      audiences: [api://cma-server]
      roles:
        - group: cma-admins
          role: admin
        - group: "eng-*"
          role: developer
  • name 用于在日志行中标识该签发方,服务器还会将其记录为每个资源创建者的一部分。一旦有人创建了资源,就不要再更改它。
  • issuer_url 必须等于您令牌的 iss 声明。
  • audiences 列出令牌的 aud 声明可以携带的值,例如第一步中的标识符。
  • roles 将组映射到 admin、developer 或 user。匹配到的最高角色生效。

有关其他字段,请参阅签发方条目。如果您的提供商是 Microsoft Entra ID,另请参阅 Microsoft Entra ID。

重启服务器并检查登录

重启服务器。调用方在任何接受服务器 API 密钥的路由上,以 Authorization: Bearer <token> 的形式发送令牌。

对于每个经令牌验证的请求,服务器都会记录 auth=oidc、签发方的 name 以及调用方的主体(sub=)。

如果登录失败

响应原因服务器日志行中包含
401,与错误 API 密钥相同令牌未通过检查。日志行中有具体原因。oidc token
403令牌的组未匹配任何 roles 条目token holds no role

Microsoft Entra ID

Entra ID 在两个方面与其他提供商不同。这两项设置都放在签发方条目中:

  • 用户身份: Entra ID 会在每个客户端应用程序中为同一个人提供不同的 sub,因此使用默认值会将一个人记录为多个创建者。请设置 subject_claim: oid。
  • 组: 如果某人属于很多组,Entra ID 会在令牌中省略 groups 声明。这样该用户就不会匹配任何 roles 条目。为避免这种情况,请让 Entra ID 仅发出分配给该应用程序的组。或者在 Entra ID 中为用户分配应用角色,并设置 groups_claim: roles,让服务器读取应用角色来代替组。

各角色可执行的操作

角色智能体、技能、会话、vault 和记忆存储环境
admin 以及服务器 API 密钥查看和更改所有内容创建、更改和删除环境,并创建其密钥
developer 或 user仅查看和更改该调用方创建的内容列出、读取环境,并在其中运行会话

developer 和 user 拥有相同的访问权限。拥有这两种角色之一的调用方:

  • 无法看到他人创建的资源。 该资源不会出现在列表中,对其 ID 的请求所得到的响应与对未知 ID 的请求相同。这也包括在您启用单点登录之前使用服务器 API 密钥创建的所有内容。
  • 无法与其他调用方或组共享资源。

请将 admin 映射到精确的组名。管理员还可以启动使用任何用户 vault 的会话。因此,请仅将该角色授予您信任其可接触每个用户 MCP 令牌的组。

让开发者从终端登录

开发者可以通过您的身份提供商登录,然后以自己的身份使用 ant CLI,而无需服务器 API 密钥。前两步由您完成,第三步由每位开发者完成。

在您的身份提供商中注册应用程序

注册一个具有以下特征的原生("public")应用程序:

  • 不设客户端密钥
  • 使用带 PKCE 的授权码授权方式
  • 重定向 URI 为 http://127.0.0.1/callback

某些提供商需要使用其他重定向 URI 之一。

将应用程序添加到签发方条目

在签发方条目中添加 login_client_id 和 login_scopes,然后重启服务器:

示例代码
login_client_id: 0oa1b2c3d4e5f6g7h8i9
login_scopes: [openid, cma-server.access]

login_scopes 列出您的提供商签发 aud 声明位于签发方条目 audiences 列表中的令牌所需的作用域。

登录

每位开发者从解压后归档的顶层目录运行登录命令:

示例代码
./cma-server-admin login https://cma.example.com

服务器的 URL 必须使用 https://,或是指向 localhost、127.0.0.1 或 ::1 的 http://。使用其他重定向 URI 之一时,请在命令中添加相应的标志。

该命令会在浏览器中打开提供商的登录页面,然后写入一个名为 cma-server 的 ant CLI 配置文件。在任何 ant 命令中传入 --profile cma-server,或运行 ant profile activate cma-server 将该配置文件设为默认。

令牌过期后,开发者需再次运行 login。要改为让 ant CLI 续期令牌,请将 offline_access 添加到 login_scopes。

其他重定向 URI

提供商需注册的重定向 URI开发者需在 login 命令中添加的标志
Microsoft Entra IDhttp://localhost/callback-listen localhost:0
要求重定向 URI 中包含端口的提供商使用固定端口的 URI,例如 http://127.0.0.1:8123/callback-listen 127.0.0.1:8123

要列出其他标志,请在 login 命令中添加 -h。

让用户登录您服务器上的控制台

您服务器上的控制台通过您为终端登录注册的应用程序让用户登录。要完成其设置,请参阅设置登录。

文档内容持续同步更新