Agent 入站权限控制
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 无法完成交互式登录。
配置入站访问方式
登录 AgentCore 控制台。
进入目标 Workspace。
在左侧导航栏,单击 Agent。
找到目标 Agent,单击 Agent 名称进入详情页。
单击详情页导航的 API 访问。
打开 开启 API 访问 开关。
在 Endpoint 信息 区域选择访问类型,并复制 Endpoint。
在 入站安全等级 区域编辑访问权限,选择入站访问方式:公开访问、固定 API Key 或 用户身份。
选择 用户身份 时,继续选择用户范围(各范围的含义参见功能说明):
全部用户
指定用户
重要选择 指定用户 且授权列表为空时,所有用户的访问请求都会被拒绝。保存配置后,请前往管理指定用户添加允许访问的用户。
单击 保存。
配置保存后,页面中的 入站安全等级 会展示当前生效的入站访问方式。
管理指定用户
当入站访问方式为 用户身份 且用户范围为 指定用户 时,需要配置允许访问 Agent 的用户。
进入目标 Agent 的 API 访问 页面。
在用户授权区域,单击 添加用户。
从当前 Workspace 的用户列表中选择一个或多个用户。
单击 确定。
授权完成后,已授权用户列表会展示这些用户,可以按用户名或显示名称筛选。
如需撤销权限,在已授权用户列表找到目标用户,单击 删除,并确认操作。授权列表清空后,Agent 仍保持 用户身份 > 指定用户 配置,但所有用户的访问请求都会被拒绝。
如果授权来源为 Team,用户权限会随 Team 成员或 Agent 归属关系变化而更新。此类授权需在 Team 维护,不能在 Agent 权限列表单独删除。
使用固定 API Key 调用 Agent
在 Agent 的 API 访问 页面,确认入站访问方式为 固定 API Key。
单击 获取鉴权信息。
复制页面展示的 Header 名称和 API Key。
使用页面中的 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 的服务端环境。
创建接入应用
在左侧导航栏选择 身份与权限 > 应用接入。
创建接入应用,配置应用名称、用户来源和回调地址。
安全保存创建结果中的 Client ID 和 Client Secret。Client Secret 仅展示一次。
进入应用详情,复制元数据地址。
访问元数据地址,从 OpenID Configuration 中读取以下端点,不要自行拼接端点地址:
authorization_endpoint:用户授权端点。token_endpoint:令牌端点。
发起用户授权
为本次授权生成以下随机值:
STATE:用于关联授权请求和回调,防止跨站请求伪造。CODE_VERIFIER:PKCE 原始随机字符串,长度为 43~128 个字符,只能包含字母、数字及-、.、_、~。CODE_CHALLENGE:对CODE_VERIFIER的 ASCII 字节执行 SHA-256,再进行不带=padding 的 Base64 URL 编码得到的值,即BASE64URL(SHA256(ASCII(CODE_VERIFIER)))。
使用浏览器访问
authorization_endpoint,并携带以下参数。参数 取值或说明 response_type固定为 code。client_id创建接入应用后获得的 Client ID。 redirect_uri必须与接入应用中登记的回调地址完全一致。 scopeopenid agent:invoke agent:offline_accessstate本次授权生成的 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。从响应的locationHeader 复制登录地址,并用浏览器打开该地址,完成用户登录和授权。用户完成登录和授权后,浏览器会重定向到以下地址:
<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>校验回调中的
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 . 格式化响应。