入站身份认证
为什么需要入站身份认证
智能体运行时作为一个独立隔离的托管运行环境，需要对外提供 API 接口以接收外部调用请求。然而，并非所有请求都应该被无条件接受——如果运行时不加验证地处理任何传入请求，将面临以下安全风险：
- 未授权访问：任何人只要知道运行时的访问地址，就可以调用智能体，消耗计算资源，甚至获取敏感数据。
- 身份不可追溯：无法区分请求来自哪个用户或系统，难以进行访问控制和审计。
- 恶意调用：攻击者可以伪造请求，对运行时进行 DDoS 攻击或数据窃取。
入站身份认证的核心目标是：对每一个到达智能体运行时的请求进行身份验证，确保请求来自可信的调用方，并根据调用方身份进行授权控制。
AgentArts 运行时的身份认证理念
在AI智能体场景中，身份认证面临比传统 Web 服务更复杂的挑战：智能体不仅需要被外部系统调用，还可能需要代表用户身份去访问其他云服务。因此，AgentArts运行时将身份认证分为两个维度：
- 入站认证：验证调用方的身份，确保只有授权的调用方能够访问智能体运行时的 API 接口。
- 出站认证：智能体运行时内部代表用户身份访问其他华为云服务时使用的凭据（通过运行时委托实现）。
入站认证作为运行时的“守门人”，对每个请求独立验证，要求所有访问尝试都必须提供显式的身份证明。无论是来自华为云内部系统的调用，还是来自外部第三方系统的调用，都必须通过入站认证后才能被智能体处理。这种"零信任"的安全模型确保了：
- 每个请求都经过验证：不存在"默认信任"的调用方
- 身份可追溯：通过认证凭据可追踪到具体的调用方
- 访问可控制：可根据不同认证方式配置不同的访问策略
- 合规可审计：所有认证请求都有记录，满足安全合规要求
支持的认证方式
AgentArts运行时入站身份认证支持以下三种方式：
| 认证方式 | 认证凭据 | 请求头格式 |
|---|---|---|
| IAM 认证（AK/SK 签名认证） | AK + SK通过签名算法生成签名 | Authorization: V11-HMAC-SHA256 Access={AK}, SignedHeaders=..., Signature=... |
| API Key认证 | API Key字符串 | Authorization: Bearer {API Key} |
| OAuth 2.0认证 | JWT Token | Authorization: Bearer {JWT Token} |
IAM 认证（AK/SK 签名认证）
IAM 认证基于华为云的AK/SK签名算法。调用方使用自己的 AK（Access Key）和 SK（Secret Access Key）对请求进行签名，将签名信息放入 Authorization 请求头中。运行时收到请求后，通过验证签名的正确性来确认调用方身份。
签名过程包含以下步骤：
- 构造规范请求：将 HTTP 方法、URI、查询参数、消息头、消息体等按照规范格式拼接成规范请求字符串，并计算其 SHA-256 哈希值。
- 创建待签字符串：将签名算法标识、请求时间、规范请求的哈希值拼接成待签字符串。
- 计算签名：使用 SK 作为密钥，通过 HMAC-SHA256 算法对待签字符串计算签名。
- 添加签名信息到请求头：将 AK、签名的消息头列表和签名值组装到 Authorization 请求头中。
完整的签名请求示例：
GET /v1/runtimes/my-runtime/invocations?input=hello HTTP/1.1 Host: agentarts.cn-southwest-2.myhuaweicloud.com Content-Type: application/json X-Sdk-Date: 20260909T033655Z Authorization: V11-HMAC-SHA256 Access=QTWA***KYUC, SignedHeaders=content-type;host;x-sdk-date, Signature=f12f84a5ecf9eff3206499c4a55b13d1adad745dc8624a2e31f15c6b381d5b80
支持的签名算法
智能体运行时数据面接口（即 /runtimes/{runtime_name}/invocations 等接口）支持以下签名算法：
| 签名算法 | 说明 |
|---|---|
| V11-HMAC-SHA256 | 基于 HMAC-SHA256 的签名算法，使用 SK 作为密钥对待签字符串进行哈希运算，支持 Region 级别的密钥派生 |
| SDK-ECDSA-P256-SHA256 | 基于椭圆曲线数字签名算法（ECDSA P-256）的签名算法，使用非对称密钥对进行签名 |
对于智能体运行时数据面接口，不支持对请求 body 体签名，仅对请求头和查询参数进行签名验证。其他 AgentArts 接口仍需对 body 体签名。
约束与限制
- AK/SK 签名认证方式仅支持消息体大小 12MB 以内
- AK/SK 既可以使用永久访问密钥，也可以使用临时访问密钥（STS），使用临时访问密钥时需额外携带 X-Security-Token 请求头
- API 网关会校验请求时间（X-Sdk-Date）与服务器时间的差值，超过 15 分钟的请求将被拒绝，请确保客户端时间同步
- 签名 SDK 仅提供签名功能，与各服务提供的 SDK 不同
API Key 认证
API Key 认证是一种轻量级的认证方式。调用方通过 AgentArts 智能体身份服务获取一个 API Key 字符串，在调用运行时接口时将其放入 Authorization 请求头中即可完成认证。
请求格式：
POST /v1/runtimes/my-runtime/invocations HTTP/1.1
Host: agentarts.cn-southwest-2.myhuaweicloud.com
Content-Type: application/json
Authorization: Bearer {你的API Key}
{"input": "你好"} API Key 获取方式
- 进入AgentArts智能体平台，在左侧菜单栏选择“托管与运行 > 智能体运行时”。
- 单击智能体运行时名称，进入智能体详情页面。
- 在“权限与访问控制”区域，访问URN。 图1 访问URN
- 进入AgentIdentity智能体身份服务，在基本信息页面获取API Key值并复制。 图2 获取API Key值
- 添加Authorization的请求头，对应的请求头的值为“Bearer 获取到的API Key”。
OAuth 2.0认证
OAuth 2.0认证依赖第三方身份凭据提供商（如 Okta、Cognito 等）签发的JWT（JSON Web Token）作为认证凭据。调用方先从身份提供商处获取JWT Token，然后将Token放入Authorization请求头中调用运行时接口。运行时收到请求后，会验证JWT Token的签名、有效期和声明信息，确认调用方身份。
请求格式：
POST /v1/runtimes/my-runtime/invocations HTTP/1.1
Host: agentarts.cn-southwest-2.myhuaweicloud.com
Content-Type: application/json
Authorization: Bearer {JWT Token}
{"input": "你好"} JWT Token获取
JWT Token 由第三方身份提供商签发，获取方式因提供商而异。以GitHub应用为例，可参考GitHub文档中“生成JSON Web令牌 (JWT)”章节获取JWT Token。
OAuth 2.0配置参数
在创建运行时时选择 OAuth 2.0 认证后，需要配置以下参数：
| 参数 | 说明 |
|---|---|
| Discovery URL | OAuth 发现服务器地址，需输入以 https:// 开头、/.well-known/openid-configuration 结尾的有效URL |
| 允许的受众 | 用于认证OAuth 2.0 指定的受众是否与Agent Identity运行时中指定的受众匹配或为其子集，最多100个 |
| 允许的客户端 | 用于认证OAuth 2.0指定的客户端标识符是否被允许访问，最多 100 个 |
| 允许的范围 | 仅当令牌包含此处配置的至少一个必须范围时才允许访问，最多100个 |
| 自定义声明 | 仅当令牌中的特定声明与预定义字符串值相匹配时才允许访问，最多100 个 |
适用场景
| 认证方式 | 适用场景 | 优势 | 劣势 |
|---|---|---|---|
| IAM 认证（AK/SK 签名认证） | 华为云内部系统调用、已接入华为云 IAM 的系统对接 | 安全性高，签名防篡改，凭据不直接传输，支持临时凭据 | 签名逻辑复杂，集成成本较高 |
| API Key 认证 | 快速测试验证、轻量级集成、原型开发 | 集成简单，仅需一个请求头，开发效率高 | 安全性相对较低，API Key 明文传输，不适合生产环境高安全场景 |
| OAuth 2.0 认证 | 对接外部系统、企业级应用集成、已有身份提供商的场景 | 支持标准化身份联邦，细粒度权限控制，支持用户委托授权 | 配置复杂，依赖外部身份提供商，需处理 Token 刷新 |
场景选择建议
场景一：华为云内部服务调用推荐使用IAM认证。调用方使用自身的华为云 AK/SK 对请求签名，凭据不直接在网络上传输，安全性最高。适合 已经对接过华为云IAM的服务调用智能体运行时的场景。
场景二：开发调试与快速验证推荐使用API Key认证。无需实现复杂的签名逻辑，只需在请求头中携带 API Key 即可快速调用运行时接口，适合开发调试和原型验证阶段。
场景三：企业系统对接 推荐使用OAuth 2.0认证。企业已有 IdP（如 Okta、Cognito）时，可通过 OAuth 2.0 联邦认证实现单点登录和统一身份管理，无需为每个系统单独管理 AK/SK 或 API Key。
场景四：第三方 SaaS 集成推荐使用OAuth 2.0认证。通过 OAuth 2.0 的授权码流程（3LO），用户可明确授权第三方应用访问智能体运行时，支持细粒度的范围控制和用户同意机制。
入站身份认证的配置方式
入站身份认证在创建智能体运行时配置，配置后不可修改。
配置步骤
- 登录AgentArts智能体平台。
- 在左侧导航栏选择“托管与运行 > 智能体运行时”。
- 单击“托管智能体”，进入运行时创建页面。
- 在“权限与访问控制 > 入站身份认证”中选择认证方式：
- IAM 认证：使用登录管理控制台时使用的IAM用户名进行认证。
- API Key 认证：通过接口的访问密钥进行身份验证和授权。输入 API Key 的名称后，系统会自动创建并绑定API Key。
- OAuth 2.0 认证：将OAuth 2.0配置为入站身份认证。选择后需配置Discovery URL、允许的受众、允许的客户端、允许的范围等参数。
- 认证方式创建后不可修改：智能体运行时在初次创建时选择认证方式后，后续编辑无法修改认证方式。如果认证方式选择错误，需要重新创建一个新的智能体运行时（可使用“复制”功能快速创建相同配置的运行时）。
- 认证方式需与调用方匹配：调用方必须使用与运行时配置一致的认证方式，否则请求将被拒绝。
