# 入站身份认证
#### 为什么需要入站身份认证
智能体运行时作为一个独立隔离的托管运行环境，需要对外提供 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 请求头中。运行时收到请求后，通过验证签名的正确性来确认调用方身份。
签名过程包含以下步骤：
1. **构造规范请求**：将 HTTP 方法、URI、查询参数、消息头、消息体等按照规范格式拼接成规范请求字符串，并计算其 SHA-256 哈希值。
2. **创建待签字符串**：将签名算法标识、请求时间、规范请求的哈希值拼接成待签字符串。
3. **计算签名**：使用 SK 作为密钥，通过 HMAC-SHA256 算法对待签字符串计算签名。
4. **添加签名信息到请求头**：将 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）的签名算法，使用非对称密钥对进行签名                   |
   
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
对于智能体运行时数据面接口，不支持对请求 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 获取方式**
1. 进入AgentArts智能体平台，在左侧菜单栏选择"托管与运行 \> 智能体运行时"。
2. 单击智能体运行时名称，进入智能体详情页面。
3. 在"权限与访问控制"区域，访问URN。 
   图1访问URN   
   ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002640931650.png "点击放大")
   
   
4. 进入AgentIdentity智能体身份服务，在基本信息页面获取API Key值并复制。 
   图2获取API Key值   
   ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002640932060.png "点击放大")
   
   
5. 添加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)](https://docs.github.com/zh/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)"章节获取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），用户可明确授权第三方应用访问智能体运行时，支持细粒度的范围控制和用户同意机制。
#### 入站身份认证的配置方式
入站身份认证在创建智能体运行时配置，配置后不可修改。
**配置步骤**
1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。
2. 在左侧导航栏选择"托管与运行 \> 智能体运行时"。

3. 单击"托管智能体"，进入运行时创建页面。
4. 在"权限与访问控制 \> 入站身份认证"中选择认证方式： 
   - IAM 认证：使用登录管理控制台时使用的IAM用户名进行认证。
   
   - API Key 认证：通过接口的访问密钥进行身份验证和授权。输入 API Key 的名称后，系统会自动创建并绑定API Key。
   
   - OAuth 2.0 认证：将OAuth 2.0配置为入站身份认证。选择后需配置Discovery URL、允许的受众、允许的客户端、允许的范围等参数。
   
   
   
   
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
- 认证方式创建后不可修改：智能体运行时在初次创建时选择认证方式后，后续编辑无法修改认证方式。如果认证方式选择错误，需要重新创建一个新的智能体运行时（可使用"复制"功能快速创建相同配置的运行时）。
- 认证方式需与调用方匹配：调用方必须使用与运行时配置一致的认证方式，否则请求将被拒绝。