AWS bedrock-agentcore documentation change
Summary
Updated the getting started guide for AgentCore identity with Cognito to use the AgentCore CLI for deployment, updated IAM policy attachment script to use AWS CLI and CloudFormation, and fixed variable placeholders in URLs.
Security assessment
The changes are procedural updates and corrections to the deployment process. They do not address a specific security vulnerability but rather update the documentation to reflect the current tooling and best practices. The document itself is about setting up OAuth 2.0 authentication, which is a security feature, but the changes are not adding new security documentation beyond what was already there.
Diff
diff --git a/bedrock-agentcore/latest/devguide/identity-getting-started-cognito.md b/bedrock-agentcore/latest/devguide/identity-getting-started-cognito.md index 0b77e2168..a7ec77c34 100644 --- a//bedrock-agentcore/latest/devguide/identity-getting-started-cognito.md +++ b//bedrock-agentcore/latest/devguide/identity-getting-started-cognito.md @@ -45,0 +46,2 @@ Before you begin, ensure you have: + * Node.js 18+ installed (for the AgentCore CLI) + @@ -62 +64 @@ Make a folder for this guide, create a Python virtual environment, and install t - pip install bedrock-agentcore boto3 strands-agents bedrock-agentcore-starter-toolkit pyjwt + pip install bedrock-agentcore boto3 strands-agents pyjwt @@ -71 +72,0 @@ Also create the `requirements.txt` file with the following content. This will be - bedrock-agentcore-starter-toolkit @@ -143,2 +144,2 @@ You may choose to save this script as create_cognito.sh and execute it from your - ISSUER_URL="https://cognito-idp.region.amazonaws.com/$USER_POOL_ID/.well-known/openid-configuration" - HOSTED_UI_URL="https://$DOMAIN_NAME.auth.region.amazoncognito.com" + ISSUER_URL="https://cognito-idp.$REGION.amazonaws.com/$USER_POOL_ID/.well-known/openid-configuration" + HOSTED_UI_URL="https://$DOMAIN_NAME.auth.$REGION.amazoncognito.com" @@ -172,0 +174,18 @@ This credential provider will be used by your agent's code to get access tokens +AgentCore CLI + + +If you have an AgentCore CLI project, you can add the credential provider using the CLI. The CLI will create the provider during deployment. + + + agentcore add credential \ + --name AgentCoreIdentityQuickStartProvider \ + --type oauth \ + --discovery-url "$ISSUER_URL" \ + --client-id "$CLIENT_ID" \ + --client-secret "$CLIENT_SECRET" + +The credential provider will be created when you run `agentcore deploy` in Step 4. Note the callback URL from the deploy output. + +AWS CLI + + @@ -311 +330 @@ Create a file named `agentcoreidentityquickstart.py`, and save this code. -For a sample local callback server implementation to handle [ session binding](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), refer to [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) +For a sample local callback server implementation to handle [ session binding](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), refer to [oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) @@ -315 +334,7 @@ For a sample local callback server implementation to handle [ session binding](h -We will host this agent on AgentCore Runtime. We can do this easily with the AgentCore SDK we installed earlier. +We will host this agent on AgentCore Runtime. We can do this easily with the AgentCore CLI. + +From your terminal, install the AgentCore CLI and create a new project: + + + npm install -g @aws/agentcore + agentcore create --name IdentityQuickstart --defaults @@ -317 +342,17 @@ We will host this agent on AgentCore Runtime. We can do this easily with the Age -From your terminal, run `agentcore configure -e agentcoreidentityquickstart.py` and `agentcore launch`. The deployment will work with the defaults set by `agentcore configure`, but you may customize them. Ensure that you select "No" for the `Configure OAuth authorizer instead` step. We want to use IAM authorization for this guide. +Copy your agent script into the project's agent directory, replacing the default agent: + + + cp agentcoreidentityquickstart.py IdentityQuickstart/app/IdentityQuickstart/main.py + +Also copy your requirements file into the agent directory to ensure all dependencies are included in the deployment: + + + cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/ + +Then deploy your project: + + + cd IdentityQuickstart + agentcore deploy + +The CLI synthesizes a AWS CDK stack and deploys your agent to AgentCore Runtime. This takes approximately 2–3 minutes. @@ -321 +362,3 @@ From your terminal, run `agentcore configure -e agentcoreidentityquickstart.py` -You will need to update the IAM policy of your agent that was created by or used with `agentcore configure`. This script will read your agent's configuration YAML and append the appropriate policy. You can copy and paste this script, or save it to a file and execute it. +The AgentCore CLI creates the agent's execution role during deployment, but the role does not automatically include permissions for token vault access. You need to attach an additional policy to allow the agent to retrieve OAuth 2.0 tokens at runtime. + +This script retrieves your account and region from the AWS CLI, finds the agent's execution role from the CloudFormation stack, and attaches the appropriate policy. You can copy and paste this script, or save it to a file and execute it. @@ -326,4 +369,9 @@ You will need to update the IAM policy of your agent that was created by or used - # Parse values from .bedrock_agentcore.yaml - EXECUTION_ROLE=$(grep "execution_role:" .bedrock_agentcore.yaml | head -1 | awk '{print $2}') - AWS_ACCOUNT=$(grep "account:" .bedrock_agentcore.yaml | head -1 | awk '{print $2}' | tr -d "'") - REGION=$(grep "region:" .bedrock_agentcore.yaml | awk '{print $2}') + # Get account and region from AWS CLI + AWS_ACCOUNT=$(aws sts get-caller-identity --query Account --output text) + REGION=$(aws configure get region) + + # Get execution role from CloudFormation stack outputs + EXECUTION_ROLE=$(aws cloudformation describe-stack-resources \ + --stack-name AgentCore-IdentityQuickstart-prod \ + --query "StackResources[?ResourceType=='AWS::IAM::Role'].PhysicalResourceId" \ + --output text | head -1) @@ -348,5 +396,5 @@ You will need to update the IAM policy of your agent that was created by or used - "Resource": ["arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/*", - "arn:aws:bedrock-agentcore:region:account-id:token-vault/default/oauth2credentialprovider/AgentCoreIdentityQuickStartProvider", - "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default", - "arn:aws:bedrock-agentcore:region:account-id:token-vault/default", - "arn:aws:secretsmanager:region:account-id:secret:bedrock-agentcore-identity!default/oauth2/AgentCoreIdentityQuickStartProvider*" + "Resource": ["arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default/workload-identity/*", + "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default/oauth2credentialprovider/AgentCoreIdentityQuickStartProvider", + "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default", + "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default", + "arn:aws:secretsmanager:$REGION:$AWS_ACCOUNT:secret:bedrock-agentcore-identity!default/oauth2/AgentCoreIdentityQuickStartProvider*" @@ -382 +430 @@ Now that this is all set up, you can invoke the agent. For this demo, we will us - agentcore invoke "TestPayload" --agent agentcoreidentityquickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed" + agentcore invoke "TestPayload" --runtime IdentityQuickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed" @@ -396 +444 @@ If you interrupt an invocation without completing authorization, you may need to -Should you encounter any errors or unexpected behaviors, the output of the agent is captured in Amazon CloudWatch logs. A log tailing command is provided after you run `agentcore launch`. +Should you encounter any errors or unexpected behaviors, the output of the agent is captured in Amazon CloudWatch logs. A log tailing command is provided after you run `agentcore deploy`. @@ -400 +448 @@ Should you encounter any errors or unexpected behaviors, the output of the agent -After you're done, you can delete the Amazon Cognito user pool, Amazon Elastic Container Registry repo, CodeBuild Project, IAM roles for the agent and CodeBuild project, and finally delete the agent, and credential provider. +After you're done, run `agentcore remove all` and then `agentcore deploy` from your project directory to tear down the deployed AgentCore Runtime resources. Then delete the Amazon Cognito user pool, detach and delete the IAM policy you created, and delete the credential provider.