Private Key JWT client authentication

With Private Key JWT, AgentCore Identity authenticates to a downstream identity provider’s token endpoint using a signed JWT client assertion, per RFC 7523, Section 2.2, instead of a client secret. The private key never leaves AWS Key Management Service (KMS). AgentCore Identity signs each assertion via kms:Sign. Your identity provider possesses the corresponding public key used to authenticate the client assertion and returns an access token.

This method eliminates shared secrets between AgentCore Identity and your authorization server, replacing them with asymmetric key pairs under your full control.

How Private Key JWT client authentication works

Private Key JWT is available on the custom OAuth 2.0 credential provider (CustomOauth2). It works for all grant flows: client credentials (M2M), token exchange with JWT authorization grant (OBO), and authorization code (user-delegated access).

Configuring Private Key JWT in AgentCore Identity

To configure the credential provider successfully, first verify your identity provider’s requirements for Private Key JWT client authentication: signing algorithm, public keys, and required JWT client assertion claims.

Signing Algorithm

Identify the signing algorithm that your identity provider requires for Private Key JWT client authentication. This corresponds to the signingAlgorithm field in privateKeyJwtConfig while creating or updating an OAuth 2.0 custom credential provider.

AWS KMS Asymmetric Key Configuration

Determine how your identity provider manages signing keys:

The signingAlgorithm you choose determines which KMS key specs are accepted:

AWS KMS key policy

To use an asymmetric KMS signing key for Private Key JWT, your key must allow AgentCore Identity to perform signing and key-description operations on your behalf. Append the following permissions to the key policy of your KMS key.

The kms:ViaService condition ensures the key can only be used when the request originates through Amazon Bedrock AgentCore Identity. Cross-account keys are supported when the key policy grants kms:DescribeKey and kms:Sign to the calling identity. Replace the Principal ARN with the root ARN of the account that will call AgentCore Identity.

{
  "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 keys are not supported. The KMS key must be in the same AWS Region as the credential provider.

Additional Claims in JWT Client Assertion

Check whether your identity provider requires additional claims in the JWT client assertion header or payload for Private Key JWT client authentication. If so, include them in the additionalHeaderClaims and additionalPayloadClaims fields within privateKeyJwtConfig.

Configuring OAuth client with custom provider using Private Key JWT authentication

To configure a credential provider with Private Key JWT client authentication, on the AWS console, see Add OAuth client using custom provider. You can also configure the credential provider using the AWS CLI.

CLI example: Private Key JWT for a Microsoft credential provider

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 example: Private Key JWT for an Okta credential provider with On-behalf-of Token Exchange

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"
          }
        }
      }
    }
  }'

Parameters for OAuth client with custom provider using Private Key JWT authentication