Crea il tuo primo agente autenticato

Questo tutorial introduttivo ti illustra da zero la creazione di un agente autenticato completo utilizzando Amazon Bedrock AgentCore Identity e ti aiuterà a iniziare a implementare le funzionalità di identità nelle tue applicazioni per agenti. Imparerai come configurare il tuo ambiente di sviluppo, creare un'infrastruttura di autenticazione con Cognito, distribuire il tuo agente in AgentCore Runtime e testare l'intero flusso di lavoro di autenticazione.

Alla fine di questo tutorial, disporrai di un agente completamente distribuito in grado di autenticare gli utenti tramite i flussi OAuth2, ottenere token di accesso in modo sicuro e dimostrare l'intero ciclo di vita della gestione delle identità. Il tuo agente funzionerà su AgentCore Runtime con le autorizzazioni IAM appropriate, creando un ambiente di test lab in cui potrai dimostrare e testare le capacità di integrazione.

Prerequisiti

Prima di iniziare, assicurati di disporre dei seguenti elementi:

Questo tutorial richiede che tu disponga di un server di autorizzazione OAuth 2.0. Se non ne hai uno, Step 1 ne creerà uno per te utilizzando i pool di utenti di Amazon Cognito. Se disponi di un server di autorizzazione OAuth 2.0 con un ID client, un client secret e un utente configurato, puoi procedere al passaggio 2. Questo server di autorizzazione fungerà da fornitore di credenziali di risorse, rappresentando l'autorità che concede all'agente un token di accesso OAuth 2.0 in uscita.

Installa l'SDK e le dipendenze

Crea una cartella per questa guida, crea un ambiente virtuale Python e installa l'SDK e l' AgentCore SDK AWS Python (boto3).

mkdir agentcore-identity-quickstart
cd agentcore-identity-quickstart
python3 -m venv .venv
source .venv/bin/activate
pip install bedrock-agentcore boto3 strands-agents pyjwt

Crea anche il file con il seguente contenuto. requirements.txt Questo verrà utilizzato in seguito dallo strumento AgentCore di distribuzione.

bedrock-agentcore
boto3
pyjwt
strands-agents

Fase 1: Creare un pool di utenti Cognito (opzionale)

Questo tutorial richiede un server di autorizzazione OAuth 2.0. Se non ne hai uno disponibile per il test o se desideri mantenere il test separato dal server di autorizzazione, questo script utilizzerà AWS le tue credenziali per configurare un'istanza di Amazon Cognito da utilizzare come server di autorizzazione. Lo script creerà:

L'eliminazione del AgentCoreIdentityQuickStartPool pool di utenti di Cognito eliminerà anche il client_id e l'utente associati.

Puoi scegliere di salvare questo script come create_cognito.sh ed eseguirlo dalla riga di comando, oppure incollare lo script nella riga di comando.

#!/bin/bash

REGION=$(aws configure get region)

# Create user pool
USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name AgentCoreIdentityQuickStartPool \
  --query 'UserPool.Id' \
  --no-cli-pager \
  --output text)

# Create user pool domain
DOMAIN_NAME="agentcore-quickstart-$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 5)"
aws cognito-idp create-user-pool-domain \
  --domain $DOMAIN_NAME \
  --no-cli-pager \
  --user-pool-id $USER_POOL_ID > /dev/null

# Create user pool client with secret and hosted UI settings
CLIENT_RESPONSE=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name AgentCoreQuickStart \
  --generate-secret \
  --allowed-o-auth-flows "code" \
  --allowed-o-auth-scopes "openid" "profile" "email" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers "COGNITO" \
  --query 'UserPoolClient.{ClientId:ClientId,ClientSecret:ClientSecret}' \
  --output json)

CLIENT_ID=$(echo $CLIENT_RESPONSE | jq -r '.ClientId')
CLIENT_SECRET=$(echo $CLIENT_RESPONSE | jq -r '.ClientSecret')

# Generate random username and password
USERNAME="AgentCoreTestUser$(printf "%04d" $((RANDOM % 10000)))"
PASSWORD="$(LC_ALL=C tr -dc 'A-Za-z0-9!@#$%^&*()_+-=[]{}|;:,.<>?' < /dev/urandom | head -c 16)$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 1)"

# Create user with permanent password
aws cognito-idp admin-create-user \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --output text > /dev/null

aws cognito-idp admin-set-user-password \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --output text > /dev/null \
  --permanent

# Get region

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"

# Output results
echo "User Pool ID: $USER_POOL_ID"
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
echo "Issuer URL: $ISSUER_URL"
echo "Hosted UI URL: $HOSTED_UI_URL"
echo "Test User: $USERNAME"
echo "Test Password: $PASSWORD"

echo ""
echo "# Copy and paste these exports to set environment variables for later use:"
echo "export USER_POOL_ID='$USER_POOL_ID'"
echo "export CLIENT_ID='$CLIENT_ID'"
echo "export CLIENT_SECRET='$CLIENT_SECRET'"
echo "export ISSUER_URL='$ISSUER_URL'"
echo "export HOSTED_UI_URL='$HOSTED_UI_URL'"
echo "export COGNITO_USERNAME='$USERNAME'"
echo "export COGNITO_PASSWORD='$PASSWORD'"

Fase 2: Creare un fornitore di credenziali

I fornitori di credenziali sono il modo in cui il tuo agente accede ai servizi esterni. Crea un provider di credenziali e configuralo con un client OAuth 2.0 per il tuo server di autorizzazione.

Se utilizzi il tuo server di autorizzazione, imposta le variabili di ambiente e ISSUER_URL immetti CLIENT_ID i valori CLIENT_SECRET appropriati dal tuo server di autorizzazione. Se stai utilizzando lo script precedente per creare un server di autorizzazione per te con Cognito, copia le istruzioni EXPORT dall'output nel tuo terminale per impostare le variabili di ambiente.

Questo fornitore di credenziali verrà utilizzato dal codice del tuo agente per ottenere i token di accesso che agiranno per conto dell'utente.

Passaggio 2.5: Aggiungi l'URL di callback al tuo server di autorizzazione OAuth 2.0

Per evitare reindirizzamenti non autorizzati, aggiungi l'URL di callback recuperato da CreateOauth2CredentialProvidero al tuo server di autorizzazione OAuth 2.0. GetOauth2CredentialProvider

Se stai utilizzando lo script precedente per creare un server di autorizzazione con Cognito, copia le istruzioni EXPORT dall'output nel tuo terminale per impostare le variabili di ambiente e aggiorna il client del pool di utenti Cognito con l'URL di callback del provider di credenziali OAuth2.

#!/bin/bash
aws cognito-idp update-user-pool-client \
    --user-pool-id $USER_POOL_ID \
    --client-id $CLIENT_ID \
    --client-name AgentCoreQuickStart \
    --allowed-o-auth-flows "code" \
    --allowed-o-auth-scopes "openid" "profile" "email" \
    --allowed-o-auth-flows-user-pool-client \
    --supported-identity-providers "COGNITO" \
    --callback-urls "$OAUTH2_CALLBACK_URL"

Passaggio 3: Crea un agente di esempio che avvia un flusso OAuth 2.0

In questo passaggio, creeremo un agente che avvia un flusso di autorizzazione OAuth 2.0 per far sì che i token agiscano per conto dell'utente. Per semplicità, l'agente non effettuerà chiamate effettive a servizi esterni per conto di un utente, ma ci dimostrerà di aver ottenuto il consenso ad agire per conto del nostro utente di prova.

Codice dell'agente

Crea un file denominato agentcoreidentityquickstart.py e salva questo codice.

"""
AgentCore Identity Outbound Token Agent

This agent demonstrates the USER_FEDERATION OAuth 2.0 flow.

It handles the OAuth 2.0 user consent flow and inspects the resulting OAuth 2.0 access token.
"""

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.identity import requires_access_token
import asyncio
import jwt
import logging

app = BedrockAgentCoreApp()

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def decode_jwt(token):
    try:
        decoded = jwt.decode(token, options={"verify_signature": False})
        return decoded
    except Exception as e:
        return {"error": f"Error decoding JWT: {str(e)}"}

class StreamingQueue:
    def __init__(self):
        self.finished = False
        self.queue = asyncio.Queue()

    async def put(self, item):
        await self.queue.put(item)

    async def finish(self):
        self.finished = True
        await self.queue.put(None)

    async def stream(self):
        while True:
            item = await self.queue.get()
            if item is None and self.finished:
                break
            yield item

queue = StreamingQueue()

async def handle_auth_url(url):
    await queue.put(f"Authorization URL, please copy to your preferred browser: {url}")

@requires_access_token(
    provider_name="AgentCoreIdentityQuickStartProvider",
    scopes=["openid"],
    auth_flow="USER_FEDERATION",
    on_auth_url=handle_auth_url, # streams authorization URL to client
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding',
)
async def introspect_with_decorator(*, access_token: str):
    """Introspect token using decorator"""
    logger.info("Inside introspect_with_decorator - decorator succeeded")
    await queue.put({
        "message": "Successfully received an access token to act on behalf of your user!",
        "token_claims": decode_jwt(access_token),
        "token_length": len(access_token),
        "token_preview": f"{access_token[:50]}...{access_token[-10:]}"
    })
    await queue.finish()

@app.entrypoint
async def agent_invocation(payload, context):
    """Handler that uses only the decorator approach"""
    logger.info("Agent invocation started")

    # Start the agent task and immediately begin streaming
    task = asyncio.create_task(introspect_with_decorator())

    # Stream items as they come in
    async for item in queue.stream():
        yield item

    # Wait for task completion
    await task

if __name__ == "__main__":
    app.run()

Fase 4: Distribuire l'agente su Runtime AgentCore

Ospiteremo questo agente su AgentCore Runtime. Possiamo farlo facilmente con la AgentCore CLI.

Dal tuo terminale, installa la AgentCore CLI e crea un nuovo progetto:

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --defaults

Copia lo script dell'agente nella directory degli agenti del progetto, sostituendo l'agente predefinito:

cp agentcoreidentityquickstart.py IdentityQuickstart/app/IdentityQuickstart/main.py

Copia anche il file dei requisiti nella directory dell'agente per assicurarti che tutte le dipendenze siano incluse nella distribuzione:

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

Quindi distribuisci il tuo progetto:

cd IdentityQuickstart
agentcore deploy

La CLI sintetizza uno stack AWS CDK e distribuisce l'agente in Runtime. AgentCore Questa operazione richiede circa 2-3 minuti.

Aggiorna la policy IAM dell'agente per poter accedere al token, al vault e al client secret

La AgentCore CLI crea il ruolo di esecuzione dell'agente durante la distribuzione, ma il ruolo non include automaticamente le autorizzazioni per l'accesso al token vault. È necessario allegare una policy aggiuntiva per consentire all'agente di recuperare i token OAuth 2.0 in fase di esecuzione.

Questo script recupera l'account e la regione dalla AWS CLI, trova il ruolo di esecuzione dell'agente dallo stack e allega CloudFormation la policy appropriata. È possibile copiare e incollare questo script oppure salvarlo in un file ed eseguirlo.

#!/bin/bash

# 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)

echo "Parsed values:"
echo "Execution Role: $EXECUTION_ROLE"
echo "Account: $AWS_ACCOUNT"
echo "Region: $REGION"

# Create the policy document with proper variable substitution
cat > agentcore-identity-policy.json << EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessTokenVault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetResourceOauth2Token",
        "secretsmanager:GetSecretValue"
      ],
      "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*"
      ]
    }
  ]
}
EOF

# Create the policy
POLICY_ARN=$(aws iam create-policy \
    --policy-name AgentCoreIdentityQuickStartPolicy$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 4) \
    --policy-document file://agentcore-identity-policy.json \
    --query 'Policy.Arn' \
    --output text)

# Extract role name from ARN and attach policy
ROLE_NAME=$(echo $EXECUTION_ROLE | awk -F'/' '{print $NF}')
aws iam attach-role-policy \
    --role-name $ROLE_NAME \
    --policy-arn $POLICY_ARN

echo "Policy created and attached: $POLICY_ARN"

# Cleanup
rm agentcore-identity-policy.json

Fase 5: Richiamare l'agente

Ora che tutto è impostato, puoi richiamare l'agente. Per questa demo, useremo il agentcore invoke comando e le nostre credenziali IAM. Dovremo passare --session-id gli argomenti --user-id and quando utilizziamo l'autenticazione IAM.

agentcore invoke "TestPayload" --runtime IdentityQuickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed"

L'agente restituirà quindi un URL al tuo agentcore invoke comando. Copia e incolla l'URL nel tuo browser preferito, quindi verrai reindirizzato alla pagina di accesso del tuo server di autorizzazione. Il --user-id parametro è l'ID utente che stai presentando a AgentCore Identity. Il --session-id parametro è l'ID di sessione, che deve contenere almeno 33 caratteri.

Inserisci il nome utente e la password dell'utente sul server di autorizzazione quando richiesto nel browser oppure utilizza il metodo di autenticazione preferito che hai configurato. Se hai utilizzato lo script del Passaggio 1 per creare un'istanza di Cognito, puoi recuperarlo dalla cronologia del tuo terminale.

Il browser dovrebbe reindirizzare all'URL di callback OAuth2 configurato, che gestisce il flusso di associazione della sessione. Assicurati che il tuo server di callback OAuth2 fornisca risposte chiare in caso di successo e di errore per indicare lo stato dell'autorizzazione.

Debug

In caso di errori o comportamenti imprevisti, l'output dell'agente viene registrato nei CloudWatch log di Amazon. Un comando di log tailing viene fornito dopo l'esecuzione. agentcore deploy

Eliminazione

Al termine, esegui agentcore remove all e poi agentcore deploy dalla directory del progetto per eliminare le risorse di Runtime distribuite AgentCore . Quindi elimina il pool di utenti di Amazon Cognito, scollega ed elimina la policy IAM che hai creato ed elimina il provider di credenziali.

Best practice di sicurezza

Quando lavori con informazioni sull'identità: