Panoramica di Ruolo di esecuzione del gateway Ruolo di gestione delle risorse Quando sono necessari gli aggiornamenti dei ruoli?Risoluzione dei problemi Esempio: creazione di entrambi i ruoli IAM Best practice

AgentCore Gateway e policy nelle autorizzazioni AgentCore IAM

Questa guida fornisce le autorizzazioni IAM richieste per l'utilizzo di Amazon Bedrock AgentCore Gateway with Policy AgentCore per il controllo granulare delle autorizzazioni tramite le policy Cedar.

Panoramica di

Quando si integra Amazon Bedrock AgentCore Gateway con Policy in AgentCore, sono necessari due ruoli IAM distinti:

Ruolo di esecuzione del gateway: il ruolo IAM che Amazon Bedrock AgentCore Gateway assume in fase di esecuzione per richiamare obiettivi e valutare le politiche Cedar
Ruolo di gestione delle risorse: il ruolo IAM utilizzato dagli amministratori per creare e gestire Amazon Bedrock AgentCore Gateway and Policy nelle risorse AgentCore

Entrambi i ruoli hanno scopi diversi e richiedono autorizzazioni specifiche. Il Gateway Execution Role richiede le autorizzazioni per eseguire le operazioni di Amazon Bedrock AgentCore Gateway, mentre il Resource Management Role richiede le autorizzazioni per configurare e gestire Amazon Bedrock AgentCore Gateway e Policy nelle risorse. AgentCore

Ruolo di esecuzione del gateway

Il ruolo di esecuzione del gateway viene assunto dal servizio Amazon Bedrock AgentCore Gateway durante l'elaborazione delle richieste. Questo ruolo richiede le autorizzazioni per:

Valuta le politiche di Cedar tramite Policy in AgentCore
Richiama obiettivi come le funzioni Lambda e gli endpoint API Gateway
Scrivi log e tracce su e CloudWatch X-Ray
Accesso ai segreti per le configurazioni di autenticazione

Importante

Il ruolo di esecuzione deve includere queste tre autorizzazioni per utilizzare Amazon Bedrock AgentCore Gateway with Policy in AgentCore:. bedrock-agentcore:AuthorizeAction - Valuta le politiche di Cedar per le decisioni di autorizzazione. bedrock-agentcore:PartiallyAuthorizeActions - Elenca gli strumenti che il chiamante è autorizzato a richiamare. bedrock-agentcore:GetPolicyEngine - Recupera la configurazione del motore delle politiche Senza queste autorizzazioni, il Gateway non può eseguire l'autorizzazione delle politiche. Ciò si manifesta in due modi: il collegamento di un Policy Engine a un Gateway esistente comporterà una e tutte le InternalServerException chiamate allo strumento verranno negate per impostazione predefinita anche se sono state configurate politiche di autorizzazione.

Policy di attendibilità

Il Gateway Execution Role deve considerare attendibile il responsabile del servizio. bedrock-agentcore.amazonaws.com

Importante

Sostituisci i seguenti segnaposto: * us-east-1 con la AWS regione * 123456789012 con l'ID dell'account AWS


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockAgentCoreAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

Policy di autorizzazione

Questa politica concede ad Amazon Bedrock AgentCore Gateway le autorizzazioni necessarie per valutare le politiche Cedar tramite Policy in. AgentCore Le autorizzazioni sono suddivise in due dichiarazioni secondo i principi del privilegio minimo.

Importante

Sostituisci questi segnaposto: * us-east-1 con la AWS regione * con l'ID AWS account * 123456789012 con l'ID gateway (oppure usa* per tutti i gateway) * <gateway-id> con l'ID del policy engine (o usa* <policy-engine-id> per tutti i motori di policy)


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
      ]
    }
  ]
}

Nota

* Potrebbero essere necessarie autorizzazioni aggiuntive a seconda del tipo di integrazione di Amazon Bedrock AgentCore Gateway (ad esempio, funzioni Lambda, endpoint API Gateway). Queste autorizzazioni non sono incluse qui in quanto variano in base all'integrazione specifica. * Per la produzione: sostituisci i segnaposto con ID di risorsa specifici (ad esempio, policy-engine/my-policy-engine-id anzichépolicy-engine/<policy-engine-id>) per seguire i principi del privilegio minimo, oppure usa i caratteri jolly (*) per consentire l'accesso a tutte le risorse di quel tipo.

Ruolo di gestione delle risorse

Il ruolo di gestione delle risorse viene utilizzato dagli amministratori per creare e gestire Amazon Bedrock AgentCore Gateway and Policy nelle AgentCore risorse. Questo ruolo richiede le autorizzazioni per:

Creare, aggiornare ed eliminare i gateway e le destinazioni Gateway
Crea, aggiorna ed elimina le politiche Policy Engines e Cedar
Chiama il Gateway durante la creazione della policy (InvokeGateway) in modo che Policy in AgentCore possa convalidare le azioni in un'istruzione Cedar rispetto alle funzionalità del Gateway di destinazione
Passa il ruolo di esecuzione del gateway alle risorse di Amazon Bedrock AgentCore Gateway durante la creazione
Tagga le risorse per l'organizzazione e la gestione
Leggi le informazioni sui ruoli IAM per convalidare le configurazioni dei ruoli di esecuzione

Questo ruolo è separato dal Gateway Execution Role ed è necessario solo per configurare o modificare Amazon Bedrock AgentCore Gateway and Policy nelle AgentCore configurazioni.

Policy di autorizzazione

Importante

Sostituisci questi segnaposto: * us-east-1 con la AWS regione * con l'ID dell'account 123456789012 AWS


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GatewayManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:DeleteGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:UpdateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:DeleteGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "PolicyEngineManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:UpdatePolicyEngine",
        "bedrock-agentcore:GetPolicyEngine",
        "bedrock-agentcore:DeletePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:DeletePolicy",
        "bedrock-agentcore:ListPolicies"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy/*"
      ]
    },
    {
      "Sid": "PolicyGeneration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartPolicyGeneration",
        "bedrock-agentcore:GetPolicyGeneration",
        "bedrock-agentcore:ListPolicyGenerations",
        "bedrock-agentcore:ListPolicyGenerationAssets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy-generation/*"
      ]
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*BedrockAgentCore*"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
        }
      }
    },
    {
      "Sid": "IAMReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*"
      ]
    },
    {
      "Sid": "PolicyScopeManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ManageResourceScopedPolicy",
        "bedrock-agentcore:ManageAdminPolicy"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}

Importante

bedrock-agentcore:InvokeGatewayè necessario per creare o aggiornare le politiche Cedar, non solo per richiamare il Gateway in fase di esecuzione. CreatePolicye UpdatePolicy convalida le azioni contenute nella dichiarazione Cedar nei confronti del Gateway, un'operazione autorizzata come InvokeGateway nel Gateway ARN. Senza di essa, la politica passerà a with. CREATE_FAILED Insufficient permissions to call gateway with ID <gateway-id>

Importante

ManageAdminPolicyLe azioni ManageResourceScopedPolicy and sono porte di sola autorizzazione che controllano i tipi di policy Cedar che gli amministratori possono creare: * ManageResourceScopedPolicy - Concede l'autorizzazione a creare policy Cedar che hanno come target ARN gateway specifici (ad esempio, le politiche applicabili agateway/my-gateway-123) * ManageAdminPolicy - Concede l'autorizzazione a creare policy Cedar con caratteri jolly (ad esempio, politiche che si applicano al gateway/*) Entrambe le autorizzazioni sono necessarie per la piena funzionalità di gestione delle policy. Non si tratta di operazioni API, ma piuttosto di controlli di autorizzazione che determinano l'ambito delle politiche Cedar che possono essere create tramite le API di gestione delle politiche.

Nota

Sebbene il campo Resource sia incluso per motivi di coerenza, queste azioni basate solo sulle autorizzazioni limitano principalmente la capacità a livello di azione piuttosto che a livello di risorsa.

Quando sono necessari gli aggiornamenti dei ruoli?

Determina se è necessario aggiungere una policy nelle AgentCore autorizzazioni al ruolo di esecuzione di Amazon Bedrock AgentCore Gateway in base a come è stato creato Amazon Bedrock AgentCore Gateway.

Scenario 1: gateway creato con AgentCore CLI

Stato: azione richiesta

La AgentCore CLI crea un ruolo di esecuzione del gateway con autorizzazioni mirate per la chiamata del target e l'autenticazione in uscita, ma non include Policy nelle autorizzazioni. AgentCore È necessario aggiungere manualmente le autorizzazioni e le AuthorizeAction GetPolicyEngine autorizzazioni documentate in questa guida al ruolo di esecuzione del gateway. PartiallyAuthorizeActions

Scenario 2: ruolo di esecuzione personalizzato

Stato: azione richiesta

I ruoli IAM personalizzati richiedono che la Policy in materia di AgentCore autorizzazioni documentata in questa guida venga aggiunta manualmente. Segui le politiche di autorizzazione nelle sezioni precedenti.

Scenario 3: Least-Privilege configurazione di produzione

Stato: azione richiesta

Per gli ambienti di produzione, definisci la Policy in termini di AgentCore autorizzazioni per ARN di risorse specifiche anziché utilizzare caratteri jolly. Sostituisci policy-engine/* e gateway/* con il motore di policy e gli ID gateway specifici nelle tue politiche di autorizzazione.

Risoluzione dei problemi

Questa sezione illustra i problemi più comuni relativi alla configurazione delle autorizzazioni IAM per Amazon Bedrock AgentCore Gateway with Policy in. AgentCore

InternalServerException Durante la valutazione delle politiche

Sintomo: Gateway ritorna InternalServerException - Policy evaluation failed quando si collega un Policy Engine a un Gateway esistente e tutte le chiamate allo strumento vengono negate per impostazione predefinita anche con le politiche di autorizzazione configurate.

Causa principale: al Gateway Execution Role manca la policy richiesta nelle autorizzazioni. AgentCore Senza queste autorizzazioni, il Gateway non può eseguire l'autorizzazione delle policy.

Soluzione: assicurati che il ruolo Gateway Execution includa queste tre autorizzazioni:


{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:PartiallyAuthorizeActions",
    "bedrock-agentcore:AuthorizeAction",
    "bedrock-agentcore:GetPolicyEngine"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:policy-engine/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:gateway/*"
  ]
}

Nota

Se colleghi un Policy Engine a un gateway esistente utilizzando la console Policy Engine, le autorizzazioni IAM potrebbero non essere aggiornate automaticamente. È necessario aggiungere manualmente queste autorizzazioni al ruolo del Service-Linked Gateway.

«Autorizzazioni insufficienti per chiamare il gateway» attivo CreatePolicy

Sintomo: CreatePolicy restituisce unpolicyId, ma la policy passa quindi a CREATE_FAILED conInsufficient permissions to call gateway with ID <gateway-id>, anche quando il Gateway Execution Role ha AuthorizeActionPartiallyAuthorizeActions, e. GetPolicyEngine

Causa principale: il divario risiede nel ruolo di gestione delle risorse che chiamaCreatePolicy, non nel ruolo Gateway Execution. La convalida delle policy richiama il Gateway (authorized asbedrock-agentcore:InvokeGateway); l'errore indica il nome del Gateway, ma la correzione riguarda il ruolo di creazione delle policy.

Soluzione: aggiungere bedrock-agentcore:InvokeGateway (con ambito al Gateway ARN) al ruolo di gestione delle risorse:


{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:InvokeGateway"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
  ]
}

Errori silenziosi in modalità LOG_ONLY

Sintomo: il Policy Engine sembra funzionare in modalità LOG_ONLY ma fallisce silenziosamente senza messaggi di errore appropriati.

Causa principale: la mancanza bedrock-agentcore:GetPolicyEngine dell'autorizzazione causa errori silenziosi che emergono solo quando si passa alla modalità ENFORCED.

Soluzione: includi sempre bedrock-agentcore:GetPolicyEngine nel Gateway Execution Role, anche quando si utilizza la modalità LOG_ONLY per i test.

Errore non trovato nel Policy Engine

Sintomo: Amazon Bedrock AgentCore Gateway restituisce errori che indicano che non riesce a trovare o accedere al modulo di gestione delle politiche.

Causa principale: la policy del Gateway Execution Role utilizza pattern ARN errati o manca la risorsa policy-engine.

Soluzione: assicuratevi che sia il policy-engine che gli ARN del gateway siano inclusi nell'array Resource:


"Resource": [
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
]

Nota

Entrambi PartiallyAuthorizeActions richiedono l'accesso AuthorizeAction SIA al policy-engine che alle risorse del gateway.

Suggerimenti per il debug

Abilita CloudWatch i log: configura la registrazione dettagliata per Amazon Bedrock AgentCore Gateway per acquisire i dettagli di valutazione delle politiche
Review X-Ray Traces: controlla le AWS X-Ray tracce per identificare dove i controlli di autorizzazione falliscono
Inizia con la modalità LOG_ONLY: utilizza inizialmente la modalità LOG_ONLY per testare le politiche Cedar senza bloccare le richieste
Verifica che tutte e quattro le autorizzazioni siano presenti: assicurati che AND siano AuthorizeAction tutte presenti PartiallyAuthorizeActions GetPolicyEngine
Passa alla modalità ENFORCED: solo dopo aver verificato che tutte le autorizzazioni funzionino in modalità LOG_ONLY, passa alla modalità ENFORCED

Esempio: creazione di entrambi i ruoli IAM

L'esempio seguente dimostra come creare entrambi i ruoli IAM richiesti utilizzando la AWS CLI.

Fase 1: Creare il ruolo di esecuzione del gateway


# Create the trust policy file
cat > gateway-trust-policy.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name MyGatewayExecutionRole \
  --assume-role-policy-document file://gateway-trust-policy.json

Fase 2: Associare le autorizzazioni al ruolo di esecuzione del gateway


# Create the permission policy file
cat > gateway-permissions.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
EOF

# Attach the policy to the role
aws iam put-role-policy \
  --role-name MyGatewayExecutionRole \
  --policy-name GatewayPolicyEnginePermissions \
  --policy-document file://gateway-permissions.json

Nota

Questo esempio mostra solo la Policy nelle AgentCore autorizzazioni. È necessario aggiungere autorizzazioni aggiuntive per gli obiettivi Amazon Bedrock AgentCore Gateway (Lambda, API Gateway, ecc.) in base ai requisiti di integrazione specifici.

Fase 3: Fasi successive

Dopo aver configurato il ruolo di esecuzione con la Policy richiesta nelle AgentCore autorizzazioni, procedi con la creazione e la configurazione delle risorse della Policy. Per una guida dettagliata, fare riferimento a:

Creazione di un motore di policy: consulta la sezione Creazione di un motore di policy
Scrittura delle politiche Cedar - Vedi il riferimento al linguaggio Cedar Policy

Best practice

Usa ruoli separati: mantieni ruoli distinti per l'esecuzione e la gestione delle risorse di Amazon Bedrock AgentCore Gateway
Applica Least Privilege: inizia con ARN di risorse specifici anziché con caratteri jolly in produzione
Esegui test con la modalità LOG_ONLY: verifica sempre l'integrazione del motore delle politiche in modalità LOG_ONLY prima di applicare le politiche
Abilita il monitoraggio: configura i CloudWatch log e la tracciabilità per la risoluzione dei problemi e l'osservabilità X-Ray
Politiche di controllo della versione: archivia le politiche Cedar nel controllo della versione insieme al codice dell'infrastruttura
Usa i tag delle risorse: applica i tag per organizzare e gestire Amazon Bedrock AgentCore Gateway e Policy nelle AgentCore risorse
Controlli di sicurezza regolari: rivedi periodicamente le politiche IAM per assicurarti che seguano i principi del privilegio minimo

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Concetti principali

Crea un motore di policy