本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 私钥 JWT 客户端认证
使用私钥 JWT， AgentCore 根据 RFC 7523 第 2.2 节，使用签名的 JWT 客户端断言向下游身份提供商的令牌端点进行身份验证，而不是客户端密钥。私钥永远不会离开 Amazon 密钥管理服务 (KMS)。 AgentCore 通过`kms:Sign`身份对每个断言进行签名. 您的身份提供商拥有相应的公钥，用于对客户端断言进行身份验证并返回访问令牌。
这种方法消除了 I AgentCore dentity 和您的授权服务器之间的共享密钥，将其替换为完全由您控制的非对称密钥对。
## 私钥 JWT 客户端身份验证的工作原理
+ 您可以使用您的`clientId`、非对称 KMS 签名密钥的 ARN 以及身份提供商对私钥 JWT 客户端身份验证所需的相同签名算法来配置自定义 OAuth 2.0 凭证提供商。
+ 当 AgentCore Identity 需要用于机器对机器 (M2M)、代理 (OBO) 或授权代码流的令牌时，它会生成一个短暂的 JWT 客户端断言。该断言包含您的身份提供商要求的声明。
+ AgentCore 然后，身份使用提供的非对称签名 Amazon 密钥 ARN 使用 KMS 对断言进行签名。
+ 签名的断言会像一样`client_assertion`发送到令牌端点。`client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
+ 授权服务器根据您注册的公钥验证断言并颁发所请求的令牌。
私钥 JWT 可在自定义 OAuth 2.0 凭证提供商 () 上使用。`CustomOauth2`它适用于所有授权流程：客户端凭证 (M2M)、与 JWT 授权授权 (OBO) 的代币交换以及授权码（用户委托访问权限）。
## 在 Identity 中 AgentCore 配置私钥 JWT
要成功配置凭证提供商，请首先验证您的身份提供商对私钥 JWT 客户端身份验证的要求：签名算法、公钥和所需的 JWT 客户端断言声明。
### 签名算法
确定您的身份提供商进行私钥 JWT 客户端身份验证所需的签名算法。这与创建或更新 OAuth 2.0 自定义凭证提供商`privateKeyJwtConfig`时中的`signingAlgorithm`字段相对应。
+ 在 Ident AgentCore ity 中创建凭证提供者时，指定与签名算法相同的算法。
+ 此签名算法还将用于选择可接受的 KMS 密钥规范，详情如下。
### Amazon KMS 非对称密钥配置
确定您的身份提供商如何管理签名密钥：
+ 如果您的身份提供商接受上传的公钥，请`SIGN_VERIFY`使用创建非对称 KMS 密钥对。选择支持您的签名算法的密钥规范（参见下表）。密钥必须与凭证提供商位于同一区域。在 Identity 上 AgentCore 创建凭证提供商时指定 KMS 密钥 ARN。
创建后，使用 [ kms: GetPublicKey API ](https://docs.amazonaws.cn/kms/latest/APIReference/API_GetPublicKey.html) 生成相应的公钥。`kms:GetPublicKey`返回 DER-encoded X.509 公钥或 SPKI。一些身份提供商要求这些特定格式的公钥。例如，微软 Entra 需要 X.509 证书对象，Okta 需要 JSON Web 密钥，而 Ping Identity 同时支持两者。将公钥转换为身份提供商所需的格式，然后将其上传到您的身份提供商。
+ 如果您的身份提供商创建了密钥对并提供了私钥材料，请将其导入到 KMS 密钥中并`SIGN_VERIFY`使用该密钥。选择与签名算法兼容的密钥规范（参见下表）。有关说明，请参阅[导入 KMS 密钥的密 Amazon 钥材料](https://docs.amazonaws.cn/kms/latest/developerguide/importing-keys.html)。在 Identity 上 AgentCore 创建凭证提供商时指定 KMS 密钥 ARN。
`signingAlgorithm`您选择的决定了接受哪些 KMS 密钥规范：
| 签名算法 | 接受的 KMS 密钥规格 |
| --- | --- |
| `RS256` | `RSA_2048`, `RSA_3072`, `RSA_4096` |
| `PS256` | `RSA_2048`, `RSA_3072`, `RSA_4096` |
| `ES256` | `ECC_NIST_P256` |
#### Amazon KMS 密钥策略
要对私钥 JWT 使用非对称 KMS 签名密钥，您的密钥必须允许 I AgentCore dentity 代表您执行签名和密钥描述操作。将以下权限附加到您的 KMS [ 密钥](https://docs.amazonaws.cn/kms/latest/developerguide/key-policies.html)的密钥策略中。
该`kms:ViaService`条件确保密钥只能在请求通过亚马逊 Bedrock AgentCore Identity 发起时使用。 Cross-account 当密钥策略向呼叫身份授予密钥时`kms:DescribeKey`，`kms:Sign`将支持密钥。将 `Principal` ARN 替换为将调用 AgentCore Identity 的账户的根 ARN。
```
{
"Id": "identity-service-cmk-policy",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BedrockAgentCoreIdentityPrivateKeyJwtAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": [
"kms:Sign",
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "${aws:PrincipalAccount}"
},
"StringLike": {
"kms:ViaService": "bedrock-agentcore-identity.*.amazonaws.com"
}
}
}
]
}
```
Cross-Region 不支持密钥。KMS 密钥必须与凭证提供商位于同一 Amazon 区域。
### JWT 客户断言中的其他索赔
检查您的身份提供商是否需要在 JWT 客户端断言标头或载荷中进行额外声明以进行私钥 JWT 客户端身份验证。如果是，请将它们包括在中的`additionalHeaderClaims`和`additionalPayloadClaims`字段中`privateKeyJwtConfig`。
+ 因为`additionalHeaderClaims`，我们不允许索赔`alg`或`typ`.
+ 因为`additionalPayloadClaims`，我们不允许索赔`iss``sub`、`jti``exp`、`iat`、或`nbf`。我们将允许覆盖`aud`索赔（默认为您的身份提供商的令牌端点）。
### 使用私钥 JWT 身份验证使用自定义提供商配置 OAuth 客户端
要使用私钥 JWT 客户端身份验证配置凭据提供商，请在 Amazon 控制台上使用自定义提供商[添加 OAuth 客户端。](identity-add-oauth-client-custom.md)您也可以使用 C Amazon LI 配置凭证提供商。
#### CLI 示例：微软凭证提供商的私钥 JWT
```
aws bedrock-agentcore-control create-oauth2-credential-provider \
--cli-input-json '{
"name": "microsoft-private-key-jwt",
"credentialProviderVendor": "CustomOauth2",
"oauth2ProviderConfigInput": {
"customOauth2ProviderConfig": {
"oauthDiscovery": {
"discoveryUrl": "https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration"
},
"clientId": "your-client-id",
"clientAuthenticationMethod": "PRIVATE_KEY_JWT",
"privateKeyJwtConfig": {
"privateKeySource": {
"kmsKeySource": {
"kmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/your-key-id"
}
},
"signingAlgorithm": "PS256",
"additionalHeaderClaims": {
"x5t#S256": "Base64url-encoded SHA-256 thumbprint of the DER encoding of the X.509 public key certificate uploaded to Microsoft Entra"
},
"additionalPayloadClaims": {
"aud": "https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token"
}
}
}
}
}'
```
#### CLI 示例：使用代币交换的 Okta 凭证提供商的私钥 JWT On-behalf-of
```
aws bedrock-agentcore-control create-oauth2-credential-provider \
--cli-input-json '{
"name": "okta-private-key-jwt",
"credentialProviderVendor": "CustomOauth2",
"oauth2ProviderConfigInput": {
"customOauth2ProviderConfig": {
"oauthDiscovery": {
"discoveryUrl": "https://your-app.okta.com/oauth2/default/.well-known/openid-configuration"
},
"clientId": "your-client-id",
"clientAuthenticationMethod": "PRIVATE_KEY_JWT",
"privateKeyJwtConfig": {
"privateKeySource": {
"kmsKeySource": {
"kmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/your-key-id"
}
},
"signingAlgorithm": "RS256"
},
"onBehalfOfTokenExchangeConfig": {
"grantType": "TOKEN_EXCHANGE",
"tokenExchangeGrantTypeConfig": {
"actorTokenContent": "NONE"
}
}
}
}
}'
```
#### 使用私钥 JWT 身份验证的带有自定义提供商的 OAuth 客户端的参数
| 参数 | 必需 | 描述 |
| --- | --- | --- |
| `clientAuthenticationMethod` | 是 | 设置为 `PRIVATE_KEY_JWT`。 |
| `clientId` | 是 | 在您的身份提供商处注册的客户标识符。 |
| `privateKeyJwtConfig.privateKeySource.kmsKeySource.kmsKeyArn` | 是 | 非对称 KMS 签名密钥的完整 ARN。必须与凭证提供者位于同一区域。 Cross-account 支持的。 |
| `privateKeyJwtConfig.signingAlgorithm` | 是 | 对 JWT 进行签名的算法。其中之一:`RS256`,`PS256`, `ES256`。 |
| `privateKeyJwtConfig.additionalHeaderClaims` | 否 | 其他 JWT 标头声明（地图，最多 10 个条目）。使用它传递与在身份提供商处注册的密钥相匹配的`kid`或`x5t#S256`。无法覆盖`alg`或`typ`。 |
| `privateKeyJwtConfig.additionalPayloadClaims` | 否 | 其他 JWT 有效载荷声明（地图，最多 10 个条目）。无法覆盖`iss``sub`、`jti`、`exp`、`iat`、或`nbf`。使用它来添加特定于提供商的声明或覆盖`aud`（默认情况下为令牌端点）。 |
| `clientSecret` | 非必需 | 使用私钥 JWT 时省略。 |