Authenticate with Non-public Key JWT utilizing Amazon Bedrock AgentCore Id

Amazon Bedrock AgentCore Id now helps Non-public Key JWT consumer authentication for brokers. With Non-public Key JWT consumer authentication, your brokers can authenticate to a downstream id supplier’s token endpoint utilizing a signed JSON Internet Token (JWT) consumer assertion as an alternative of a shared OAuth 2.0 consumer secret. You may register a public key together with your id supplier, whereas the corresponding personal key stays in an AWS Key Administration Service (AWS KMS). To authenticate, AgentCore Id makes use of AWS KMS to signal the assertion and sends the signed assertion to the id supplier, which verifies it utilizing the general public key you registered.

This submit explains how Non-public Key JWT consumer authentication works in AgentCore Id and evaluations the supported grant flows. We then stroll by way of creating an AWS KMS signing key, registering its public key together with your id supplier, configuring a credential supplier on the AWS Administration Console, and reviewing instance AWS CloudTrail occasions that file your agent’s entry.

How does it work?

The next instance illustrates the request circulate. Think about a customer-support agent that should learn a buyer’s order historical past from an inside orders API protected by your id supplier.

Determine 1 – Instance request circulate for a machine-to-machine token request, from the agent’s name by way of to the downstream API

The next diagram illustrates the request circulate:

1. The agent calls GetResourceOauth2Token on AgentCore Id to request a token for the orders API.
2. AgentCore Id reads the consumer ID, KMS key ARN, and signing algorithm out of your credential supplier. It builds a short-lived JWT consumer assertion with the required payload claims (plus any extra header or payload claims you configured, reminiscent of a key identifier or a certificates thumbprint), and calls kms:Signal in opposition to your KMS uneven signing key utilizing the signing algorithm you configured (RS256, PS256, or ES256).
3. AWS KMS indicators the assertion and returns the signature to AgentCore Id. The personal key by no means leaves KMS.
4. AgentCore Id posts the signed assertion to your id supplier’s token endpoint with grant_type=client_credentials and client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
5. The id supplier verifies the signature in opposition to the general public key you registered and returns an entry token to AgentCore Id.
6. AgentCore Id returns the entry token to your agent.
7. The agent calls the orders API with the entry token.
8. The orders API returns the shopper’s order historical past.

Overview of supported grant flows

Non-public Key JWT authentication works for the three grant flows:

• Machine-to-machine (M2M): the agent acts as itself. There isn’t a human consumer within the image. The agent must entry a useful resource, for instance a background job syncing knowledge, or a service that any customer-support agent can learn no matter who triggered it. The token represents the appliance/agent id. Makes use of the client_credentials grant. The token’s topic is the consumer itself.
• On-behalf-of (OBO): the agent acts for a particular consumer, utilizing that consumer’s present token. A consumer has already signed in someplace and there’s an inbound consumer token. The agent must name a downstream API as that consumer, so their permissions and id carry by way of. AgentCore Id exchanges the inbound consumer token for a downstream token that represents the consumer, whereas nonetheless authenticating itself with the consumer assertion. You need to use RFC 8693 token trade or the RFC 7523 JWT authorization grant, relying on the id supplier.
• Person-delegated entry: the agent acts for a consumer, however the consumer grants consent interactively first. There isn’t a pre-existing token to trade. As a substitute, the consumer goes by way of an interactive login/consent (the authorization code / three-legged OAuth circulate), approving what the agent can do. After consent, the agent will get a token representing the consumer. Makes use of the authorization code grant.

Conditions

This submit assumes that you’ve got

1. An AWS account with AWS Administration Console entry to KMS, AgentCore and AWS CloudTrail.
2. A tenant in your id supplier, the place you’ll be able to register a public key for an software.
3. Discovery URL and Consumer ID that purchasers use to find and combine together with your id supplier.
4. Affirm the signing algorithm your id supplier requires for Non-public Key JWT consumer authentication. Affirm the identical algorithm and key spec is supported by each AWS KMS and AgentCore Id.
5. Permissions for every a part of the circulate:
   • Create and configure the KMS key – kms:CreateKey and kms:PutKeyPolicy.
   • Export the general public key to register together with your id supplier – kms:GetPublicKey. (In case your id supplier generates the important thing pair and offers you the personal key materials as an alternative, you additionally want kms:GetParametersForImport and kms:ImportKeyMaterial to import it into KMS.)
   • Create the credential supplier – bedrock-agentcore-control:CreateOauth2CredentialProvider.

Getting began

The next sections present tips on how to configure Non-public Key JWT because the consumer authentication methodology utilizing the AWS Administration Console.

Step 1: Create the KMS signing key and register the general public key

Begin by creating an uneven KMS key that AgentCore Id will use to signal the JWT consumer assertion. On this instance, we create the important thing in KMS and export the corresponding public key to the Id supplier. Nevertheless, in case your id supplier generates the important thing pair and offers you the personal key materials as an alternative, you’ll be able to import it to KMS.

1. Open the AWS KMS console in the identical AWS Area as your credential supplier.
2. Select Buyer managed keys, then select Create key.
3. For Key kind, select Uneven.
4. For Key utilization, select Signal and confirm.
5. For Key spec, select a spec suitable together with your signing algorithm. This instance makes use of ECC_NIST_P256 with the ES256 signing algorithm.
6. Select Subsequent, enter an Alias, and proceed by way of the important thing administrator and key utilization permission steps.
7. On the Edit key coverage step, add the next assertion to the important thing coverage to grant AgentCore Id permission to make use of the important thing, changing 111122223333 together with your AWS account ID and with AgentCore area in use. The kms:ViaService situation verifies the important thing can solely be used when the request originates by way of AgentCore Id:

   {
     "Id": "BedrockAgentCoreIdentityPrivateKeyJwtAccess",
     "Model": "2012-10-17",
     "Assertion": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::111122223333:root"
         },
         "Action": [
           "kms:Sign",
           "kms:DescribeKey"
         ],
         "Useful resource": "*",
         "Situation": {
           "StringEquals": {
             "aws:ResourceAccount": "${aws:PrincipalAccount}"
           },
           "StringLike": {
             "kms:ViaService": "bedrock-agentcore-identity..amazonaws.com"
           }
         }
       }
     ]
   }

8. Select End. On the important thing’s element web page, observe the important thing ARN. You present it if you create the credential supplier.
9. Subsequent, export the general public key and register it together with your id supplier:
   1. On the important thing’s element web page, select the Public key tab and obtain the general public key. KMS supplies a DER-encoded public key.
   2. Convert the general public key into the format your supplier requires (for instance, an X.509 certificates for Microsoft Entra ID or a JSON Internet Key for Okta) and register it in your software.

Step 2: Add an OAuth consumer

1. Open the Amazon Bedrock AgentCore console.
2. Within the left navigation pane, beneath Construct, select Id.
3. Within the Outbound Auth part, select Add Outbound Auth, after which select Add OAuth consumer.

Determine 2 – Including an OAuth consumer from the AgentCore Id console

Step 3: Select Non-public key JWT because the consumer authentication methodology

On the Add OAuth Consumer web page, within the Supplier configurations part:

1. For Configuration kind, select Discovery URL so AgentCore Id can retrieve your supplier’s configuration routinely. (Select Guide config in case your supplier doesn’t publish a discovery endpoint.)
2. For Consumer authentication methodology, select Non-public key JWT.

Determine 3 – Choosing Non-public key JWT because the consumer authentication methodology

Step 4: Present the invention URL, consumer ID, KMS key and signing algorithm

1. For Discovery URL, enter the URL the place your supplier publishes its OpenID Join configuration (ending in .well-known/openid-configuration).
2. For Consumer ID, enter the consumer identifier registered at your id supplier.
3. For KMS key, select the ARN of your uneven KMS signing key. The important thing should have been created with SIGN_VERIFY as utilization and be in the identical Area for it to point out up within the checklist.

Be aware: You may as well use a key from one other account in the identical Area by coming into that key’s ARN. Cross-account entry requires further permissions in each accounts. See Permitting customers in different accounts to make use of a KMS key.

4. For Signing algorithm, select the algorithm your id supplier requires for Non-public Key JWT. It have to be suitable together with your KMS key spec:

Determine 4 – Offering the invention URL, consumer ID, uneven KMS key and signing algorithm

Step 5: (Elective) Add claims, then create the consumer

In case your id supplier requires extra claims within the JWT consumer assertion, add them right here:

1. Below Header claims – optionally available, select Add header declare so as to add provider-specific header claims, reminiscent of a key identifier. The reserved keys alg and typ can’t be set.
2. Below Payload claims – optionally available, select Add payload declare so as to add provider-specific payload claims. The reserved keys iss, sub, jti, exp, iat, and nbf can’t be set.
3. Select Add OAuth Consumer.
4. Confirm that the credential supplier was created by checking that it seems within the Outbound Auth checklist.

Determine 5 – Including optionally available header and payload claims earlier than creating the consumer

Instance CloudTrail logs for the agent entry

When an agent makes use of the credential supplier to fetch a token, the operations are recorded on AWS CloudTrail so you’ll be able to audit every entry. You will notice occasion names reminiscent of:

• GetWorkloadAccessToken (occasion supply bedrock-agentcore.amazonaws.com) – the agent obtains its workload id token. The requestParameters file the workloadName, the assets block identifies the workload id, and the returned token is redacted:

  {
     "eventSource":"bedrock-agentcore.amazonaws.com",
     "eventName":"GetWorkloadAccessToken",
     "requestParameters":{
        "workloadName":"my-agent-workload"
     },
     "responseElements":{
        "workloadAccessToken":"HIDDEN_DUE_TO_SECURITY_REASONS"
     },
     "assets":[
        {
           "accountId":"111122223333",
           "type":"AWS::BedrockAgentCore::WorkloadIdentity",
           "ARN":"arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-agent-workload"
        }
     ]
  }

• GetResourceOauth2Token (occasion supply bedrock-agentcore.amazonaws.com) – the agent requests an entry token for the downstream useful resource. The requestParameters present which credential supplier, scopes, and grant circulate had been used, and the inbound token is redacted.

  {
     "eventSource":"bedrock-agentcore.amazonaws.com",
     "eventName":"GetResourceOauth2Token",
     "requestParameters":{
        "workloadIdentityToken":"HIDDEN_DUE_TO_SECURITY_REASONS",
        "resourceCredentialProviderName":"my-private-key-jwt-provider",
        "scopes":[
           "https://graph.microsoft.com/.default"
        ],
        "oauth2Flow":"M2M"
     },
     "assets":[
        {
           "accountId":"111122223333",
           "type":"AWS::BedrockAgentCore::OAuth2CredentialProvider",
           "ARN":"arn:aws:bedrock-agentcore:us-east-1:111122223333:token-vault/default/oauth2credentialprovider/my-private-key-jwt-provider"
        }
     ]
  }

• Signal (occasion supply kms.amazonaws.com) – AgentCore Id indicators the JWT consumer assertion together with your KMS key. That is the occasion that reveals Non-public Key JWT working: userIdentity.invokedBy, sourceIPAddress, and userAgent are all bedrock-agentcore.amazonaws.com, confirming that AgentCore Id referred to as kms:Signal in your behalf. Be aware that the Signal occasion information the KMS signing algorithm title, not the JWT algorithm title you configured.

  {
     "eventSource":"kms.amazonaws.com",
     "eventName":"Signal",
     "userIdentity":{
        "invokedBy":"bedrock-agentcore.amazonaws.com"
     },
     "sourceIPAddress":"bedrock-agentcore.amazonaws.com",
     "userAgent":"bedrock-agentcore.amazonaws.com",
     "requestParameters":{
        "signingAlgorithm":"RSASSA_PKCS1_V1_5_SHA_256",
        "keyId":"arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "messageType":"DIGEST"
     },
     "responseElements":null,
     "readOnly":true,
     "managementEvent":true,
     "assets":[
        {
           "accountId":"111122223333",
           "type":"AWS::KMS::Key",
           "ARN":"arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
     ]
  }

Clear up

To keep away from incurring ongoing expenses and to take away assets you now not want, clear up the credential supplier and the KMS signing key you created on this walkthrough.

Take away the OAuth credential supplier

1. Open the Amazon Bedrock AgentCore console.
2. Within the left navigation pane, beneath Construct, select Id.
3. Within the Outbound Auth part, find the credential supplier you created.
4. Choose the supplier, select Delete, and ensure the deletion.

Schedule deletion of the KMS key

Deleting a KMS secret is irreversible and everlasting. As soon as the hot button is deleted, any knowledge or signatures that depend upon it may possibly now not be produced, so KMS requires you to schedule deletion with a ready interval moderately than deleting instantly. Earlier than you schedule deletion, verify the hot button is now not referenced by any credential supplier or id supplier registration. If you’re not sure whether or not the hot button is nonetheless in use, take into account disabling the important thing as an alternative, which stops it from getting used whereas protecting it recoverable.

1. Open the AWS KMS console within the Area the place you created the important thing.
2. Select Buyer managed keys, then choose the uneven signing key you created.
3. Select Key actions, then select Schedule key deletion.
4. Enter a ready interval between 7 and 30 days. Throughout this window the hot button is disabled however can nonetheless be recovered by canceling the scheduled deletion.
5. Affirm that you simply wish to schedule the important thing for deletion.

After the ready interval elapses, KMS completely deletes the important thing. Bear in mind to additionally take away or rotate the corresponding public key you registered together with your id supplier, so it now not trusts the retired key.

Conclusion

Through the use of Non-public Key JWT consumer authentication in AgentCore Id, you can provide your brokers a secret-less, auditable method to authenticate to id suppliers. The signing key stays on AWS KMS, each signing operation is recorded on AWS CloudTrail, and the identical credential supplier extends throughout M2M, on-behalf-of, and user-delegated flows. For end-to-end samples, together with Entra and Okta identity-provider registration and each M2M and OBO flows, see the Amazon Bedrock AgentCore samples on GitHub.

Concerning the authors