为流式传输SDK连接器配置身份验证
使用流式传输SDK构建的所有连接器都需要身份验证。 在提交或释放连接器之前，请配置一个受支持的身份验证机制：
配置与连接器的集成模型匹配的机制。
开始之前
确保您拥有：
- 已完成的流SDK连接器实施。
- 暂存或测试流摄取API端点。
- 测试Adobe组织和沙盒。
- 测试事件有效负载。
- 安全存储和轮换凭据的计划。
- 一种无需公开密钥即可捕获请求和响应详细信息的方法。
其他OAuth要求
如果您使用OAuth 2.0，请确保您拥有：
- 访问Adobe Developer Console。
- 连接器所需的API或产品配置文件。
- 所选凭据的客户端ID和客户端密码。
- 所需的范围。
- 连接器所需的OAuth流程和令牌端点。
有关适当的Adobe凭据类型和实施详细信息，请参阅：
其他HMAC要求
如果您使用HMAC，请确保您具有：
- 为webhook或连接器配置的共享密钥。
- 用于存储密码的安全位置。
- 可计算HMAC-SHA256签名的代码。
- 将发送到Adobe的确切序列化事件正文。
- 有效、无效、缺少和已轮换密码的测试过程。
配置OAuth 2.0
1. 创建或选择Adobe凭据
首先，您必须创建或选择连接器所需的Adobe Developer Console凭据。
配置：
- 凭据类型。
- 所需的Adobe API或产品配置文件。
- 所需的范围。
- 重定向或同意设置（如果适用于选定的OAuth流）。
不要使用连接器的集成模型不支持的凭据类型。
2. 安全地存储OAuth配置
安全地存储以下值：
- 客户端ID。
- 客户端密码。
- 所需的范围。
- 令牌端点。
- 任何连接器特定的租户、组织或环境值。
请勿将客户端密钥提交到源代码管理，或将其包含在日志、错误消息、屏幕截图或测试结果中。
3. 将OAuth配置添加到连接器
将OAuth配置值存储在连接器自己的配置或服务中。 流式传输SDK不会为此身份验证步骤定义连接规范字段，因为它控制您的连接器如何调用流式传输API，而不是Experience Platform如何连接到您的源。
连接器的配置必须包括：
- 身份验证类型。
- 客户端ID。
- 客户端密码。
- 范围。
- 令牌端点。
- 您的凭据类型所需的任何其他租户或组织值。
4. 获取访问令牌
实施为凭据类型记录的OAuth流程。
连接器必须：
- 使用配置的OAuth凭据进行身份验证。
- 请求流SDK集成所需的范围。
- 将访问令牌存储在内存或其他安全位置。
- 根据令牌生命周期刷新或重新获取令牌。
- 避免记录令牌或客户端密码。
5. 将访问令牌添加到请求
在连接器发送的请求中包含访问令牌作为持有者令牌：
Authorization: Bearer {ACCESS_TOKEN}
对所有请求使用HTTPS。
6. 处理令牌故障
连接器应检测并处理身份验证失败，包括：
- 缺少访问令牌。
- 访问令牌已过期。
- 客户端凭据无效。
- 范围不足。
- 已吊销或禁用的凭据。
令牌过期时，请使用文档记录的OAuth流程获取新令牌，并仅在操作可安全重试时重试。
配置基于HMAC的身份验证
1. 配置共享密钥
创建或获取连接器所需的共享密钥，并在连接器或webhook设置中对其进行配置。
密码必须是：
- 安全存储。
- 在运行时对签名代码可用。
- 从源代码控制和日志中排除。
- 已根据您的安全策略轮换。
2. 序列化事件
在计算签名之前序列化事件。
必须使用连接器在请求正文中发送的同一序列化消息计算签名。
serializedMessage = serialize(event)
请勿根据事件的一种表示形式计算签名，而发送另一种表示形式。 更改空格、属性顺序、转义、编码或行结尾可能会导致签名验证失败。
3. 计算HMAC-SHA256签名
使用以下方式计算HMAC-SHA256值：
- 密钥：配置的共享密钥。
- 消息：序列化的请求正文。
signature = HMAC-SHA256(secret, serializedMessage)
4. 添加HMAC标头
将计算的签名作为x-hmac-sha256标头添加到请求中：
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
例如，标头解析为一个与以下内容类似的值：
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
对于发送到Adobe的精确请求正文，标头值必须表示HMAC-SHA256计算。
5. 发送请求
将签名的请求通过HTTPS发送到流式引入API端点。
流式引入API在处理事件之前验证签名。 拒绝签名缺失或无效的请求。
6. 安全地旋转密码
旋转密码时，请遵循以下顺序：
- 在凭据管理系统中创建新密钥。
- 如果支持重叠密码，则在部署新密码时保持现有密码有效。
- 使用新密码更新连接器配置。
- 部署或保存配置。
- 发送测试请求并验证验证是否成功。
- 监视身份验证失败，然后在所有连接器实例使用新密钥后撤销旧密钥。
验证连接器
在成功和不成功的验证情况下测试连接器。
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| 测试 | 预期结果 |
| 使用有效的访问令牌请求 | 接受并处理该事件。 |
| 无访问令牌的请求 | 请求被拒绝。 |
| 使用过期访问令牌的请求 | 请求被拒绝，或连接器获取新令牌并根据其重试策略重试。 |
| 使用无效访问令牌的请求 | 请求被拒绝。 |
| 请求范围不足 | 请求被拒绝。 |
| 凭据轮换后请求 | 连接器已成功获取和使用新凭据。 |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| 测试 | 预期结果 |
| 具有有效签名和当前密码的请求 | 接受并处理该事件。 |
请求不包含x-hmac-sha256 |
请求被拒绝。 |
| 签名无效的请求 | 请求被拒绝。 |
| 使用错误密码签名的请求 | 请求被拒绝。 |
| 生成签名后修改了请求正文 | 请求被拒绝。 |
| 在轮换期间使用有效的先前密码签名的请求 | 结果遵循记录的密钥轮换行为。 |
| 使用已删除的密码签名的请求 | 请求被拒绝。 |
请为每个测试记录以下内容：
- 请求方法和端点。
- 请求标头，其中已密文密钥和令牌。
- 序列化请求正文。
- 使用的身份验证机制。
- 响应状态和正文。
- 时间戳和关联或跟踪标识符（如果可用）。
- 事件是否已成功摄取。
故障排除
OAuth身份验证失败
检查以下各项：
- 已为正确的Adobe组织和环境生成访问令牌。
- 客户端ID和客户端密钥属于配置的凭据。
- 请求的范围正确。
- 访问令牌未过期。
- 使用授权：持有者方案发送令牌。
- 连接器正在使用正确的令牌端点。
- 凭据有权访问所需的API或产品配置文件。
HMAC验证失败
检查以下各项：
x-hmac-sha256标头存在。- 标头名称和值的拼写正确。
- 连接器使用了正确的密码。
- 签名使用HMAC-SHA256计算。
- 签名是在准确的序列化请求正文中计算的。
- 在计算签名后，不会重新设置请求正文的格式。
- 必需的签名编码和信件大小写正确。
- 连接器在旋转过程中使用正确的当前密码或上一个密码。
- 密码可供运行时使用，且尚未被截断或更改。
提交要求
在提交或释放连接器之前，请确认以下事项：
- 您的连接器会对流摄取API的每个请求使用OAuth 2.0或基于HMAC的身份验证。
- 您已在中测试方案验证连接器并记录结果。
- 您的连接器会拒绝未经身份验证和身份验证不正确的请求。
- 您的密钥和令牌不会提交到源代码控制、日志、错误消息或屏幕截图。
后续步骤
配置身份验证并进行验证后，继续测试并提交源。 要了解如何记录源的身份验证要求，请参阅记录源（流SDK）。