Agent 入站权限控制

更新时间:
复制 MD 格式

Agent 开启 API 访问后,可通过入站权限控制决定哪些调用方能够访问。本文介绍如何在 AgentCore 控制台配置入站访问方式并管理授权用户,以及如何按所选方式使用固定 API Key 或用户身份(OAuth 2.0 Authorization Code + PKCE)调用 Agent。先完成配置,再按所选方式执行调用;仅需配置权限时,可跳过调用相关章节。

功能说明

AgentCore 支持以下入站访问方式,对应控制台 Agent 详情页的 入站安全等级 区域。

访问方式适用场景调用凭证
公开访问适用于无需识别调用者身份的公开服务或临时联调。无
固定 API Key适用于服务到服务调用、自动化任务等无终端用户参与的场景。AgentCore 生成的 API Key
用户身份适用于需要识别终端用户,并按用户控制 Agent 访问权限的场景。接入应用所属用户池的令牌端点签发的 Access Token

用户身份支持以下用户范围。

用户范围说明
全部用户当前 Workspace 身份体系中,所有满足基础身份校验条件的用户均可访问。
指定用户仅允许授权列表中的用户访问。授权列表为空时,所有用户均无法访问。

如需识别调用方身份或限制访问范围,可在 入站安全等级 区域改选其他入站访问方式,参见配置入站访问方式。

前提条件

按配置阶段与调用阶段分别满足以下条件:

  • 配置阶段:

    • 已创建 Workspace 和 Agent,且 Agent 状态正常。

    • 使用用户身份访问时,当前 Workspace 下已创建用户。具体操作,请参见管理用户。

    • 使用外部企业账号登录时,已完成账号集成,并将用户同步到当前 Workspace。

  • 调用阶段:

    • 使用用户身份调用时,已按使用用户身份调用 Agent创建接入应用并获得 Client ID 与 Client Secret。

    • 本机已安装 curl,调用示例均通过 curl 命令执行。

    • 使用用户身份调用时,可用浏览器完成交互式登录。仅在终端执行 curl 无法完成交互式登录。

配置入站访问方式

  1. 登录 AgentCore 控制台。

  2. 进入目标 Workspace。

  3. 在左侧导航栏,单击 Agent。

  4. 找到目标 Agent,单击 Agent 名称进入详情页。

  5. 单击详情页导航的 API 访问。

  6. 打开 开启 API 访问 开关。

  7. 在 Endpoint 信息 区域选择访问类型,并复制 Endpoint。

  8. 在 入站安全等级 区域编辑访问权限,选择入站访问方式:公开访问、固定 API Key 或 用户身份。

  9. 选择 用户身份 时,继续选择用户范围(各范围的含义参见功能说明):

    • 全部用户

    • 指定用户

    重要

    选择 指定用户 且授权列表为空时,所有用户的访问请求都会被拒绝。保存配置后,请前往管理指定用户添加允许访问的用户。

  10. 单击 保存。

配置保存后,页面中的 入站安全等级 会展示当前生效的入站访问方式。

管理指定用户

当入站访问方式为 用户身份 且用户范围为 指定用户 时,需要配置允许访问 Agent 的用户。

  1. 进入目标 Agent 的 API 访问 页面。

  2. 在用户授权区域,单击 添加用户。

  3. 从当前 Workspace 的用户列表中选择一个或多个用户。

  4. 单击 确定。

授权完成后,已授权用户列表会展示这些用户,可以按用户名或显示名称筛选。

如需撤销权限,在已授权用户列表找到目标用户,单击 删除,并确认操作。授权列表清空后,Agent 仍保持 用户身份 > 指定用户 配置,但所有用户的访问请求都会被拒绝。

说明

如果授权来源为 Team,用户权限会随 Team 成员或 Agent 归属关系变化而更新。此类授权需在 Team 维护,不能在 Agent 权限列表单独删除。

使用固定 API Key 调用 Agent

  1. 在 Agent 的 API 访问 页面,确认入站访问方式为 固定 API Key。

  2. 单击 获取鉴权信息。

  3. 复制页面展示的 Header 名称和 API Key。

  4. 使用页面中的 AG-UI 调用地址发起请求。

curl -N -X POST '<AG_UI_ENDPOINT>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'X-AgentCore-Session-ID: thread-demo' \
  -H '<API_KEY_HEADER>: <API_KEY>' \
  -d '{
    "threadId": "thread-demo",
    "runId": "run-demo",
    "messages": [
      {
        "id": "message-demo",
        "role": "user",
        "content": "Introduce yourself in one sentence."
      }
    ],
    "tools": [],
    "context": [],
    "state": {},
    "forwardedProps": {}
  }'

使用用户身份调用 Agent

用户身份模式使用接入应用所属用户池的令牌端点签发的 OAuth 2.0 Access Token,获取 Token 时使用 Authorization Code + PKCE 流程,code_challenge_method 固定为 S256。以下示例通过终端 curl 命令演示完整流程,并借助浏览器完成交互式登录。Client Secret 只能保存于服务端安全存储,执行授权码换 Token 请求时应使用保存 Client Secret 的服务端环境。

创建接入应用

  1. 在左侧导航栏选择 身份与权限 > 应用接入。

  2. 创建接入应用,配置应用名称、用户来源和回调地址。

  3. 安全保存创建结果中的 Client ID 和 Client Secret。Client Secret 仅展示一次。

  4. 进入应用详情,复制元数据地址。

  5. 访问元数据地址,从 OpenID Configuration 中读取以下端点,不要自行拼接端点地址:

    • authorization_endpoint:用户授权端点。

    • token_endpoint:令牌端点。

发起用户授权

  1. 为本次授权生成以下随机值:

    • STATE:用于关联授权请求和回调,防止跨站请求伪造。

    • CODE_VERIFIER:PKCE 原始随机字符串,长度为 43~128 个字符,只能包含字母、数字及 -、.、_、~。

    • CODE_CHALLENGE:对 CODE_VERIFIER 的 ASCII 字节执行 SHA-256,再进行不带 = padding 的 Base64 URL 编码得到的值,即 BASE64URL(SHA256(ASCII(CODE_VERIFIER)))。

  2. 使用浏览器访问 authorization_endpoint,并携带以下参数。

    参数取值或说明
    response_type固定为 code。
    client_id创建接入应用后获得的 Client ID。
    redirect_uri必须与接入应用中登记的回调地址完全一致。
    scopeopenid agent:invoke agent:offline_access
    state本次授权生成的 STATE。
    code_challenge本次授权生成的 CODE_CHALLENGE。
    code_challenge_method固定为 S256。

    agent:offline_access 用于申请 Refresh Token,以便在 Access Token 过期后刷新令牌。

    可以使用以下命令发起授权请求:

    curl -i -G '<AUTHORIZATION_ENDPOINT>' \
      --data-urlencode 'response_type=code' \
      --data-urlencode 'client_id=<CLIENT_ID>' \
      --data-urlencode 'redirect_uri=<REDIRECT_URI>' \
      --data-urlencode 'scope=openid agent:invoke agent:offline_access' \
      --data-urlencode "state=${STATE}" \
      --data-urlencode "code_challenge=${CODE_CHALLENGE}" \
      --data-urlencode 'code_challenge_method=S256'

    命令通常返回 HTTP 302。从响应的 location Header 复制登录地址,并用浏览器打开该地址,完成用户登录和授权。

  3. 用户完成登录和授权后,浏览器会重定向到以下地址:

    <REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>
  4. 校验回调中的 state 是否与授权请求中的 STATE 一致。校验通过后,读取 code 参数中的授权码。

使用授权码换取 Token

向 token_endpoint 发起以下请求。redirect_uri 必须与授权请求及接入应用中登记的地址完全一致,code_verifier 必须是生成 CODE_CHALLENGE 时使用的原始值。

curl -sS --show-error --max-time 30 \
  '<TOKEN_ENDPOINT>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<CLIENT_SECRET>' \
  --data-urlencode 'code=<AUTHORIZATION_CODE>' \
  --data-urlencode 'redirect_uri=<REDIRECT_URI>' \
  --data-urlencode 'code_verifier=<CODE_VERIFIER>'

从响应中读取 access_token。调用 Agent 时必须使用 Access Token,不要使用 id_token。Client Secret、Access Token 和 Refresh Token 均属于敏感信息。

如果本机已安装 jq,可以在命令末尾添加 | jq . 格式化 JSON 响应。jq 不是发起请求的必要条件;未安装时不要添加该管道。

调用 Agent

将 Access Token 原文放入 x-agentcore-accessor-jwt 请求头,AG_UI_ENDPOINT 必须是 Agent 的完整 AG-UI 调用地址。除鉴权 Header 外,请求与使用固定 API Key 调用 Agent中的示例完全相同。

curl -N -X POST '<AG_UI_ENDPOINT>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'X-AgentCore-Session-ID: thread-demo' \
  -H 'x-agentcore-accessor-jwt: <ACCESS_TOKEN>' \
  -d '{
    "threadId": "thread-demo",
    "runId": "run-demo",
    "messages": [
      {
        "id": "message-demo",
        "role": "user",
        "content": "Introduce yourself in one sentence."
      }
    ],
    "tools": [],
    "context": [],
    "state": {},
    "forwardedProps": {}
  }'

刷新 Access Token

当接入应用允许 agent:offline_access,并且本次授权成功时,令牌响应会返回 refresh_token。Access Token 过期后,可以使用 Refresh Token 获取新的 Access Token,无需再次引导用户登录。

curl -sS --show-error --max-time 30 \
  '<TOKEN_ENDPOINT>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<CLIENT_SECRET>' \
  --data-urlencode 'refresh_token=<REFRESH_TOKEN>'

从响应中读取新的 access_token。如果响应同时返回新的 refresh_token,应使用新值替换旧值,并通过服务端安全存储保存。已安装 jq 时,也可以在命令末尾添加 | jq . 格式化响应。