# Exemplo de política Esta seção fornece exemplos abrangentes de políticas de autorização da Cedar para um sistema de gerenciamento de seguros. Esses exemplos demonstram vários recursos e padrões de autorização da linguagem Cedar que você pode adaptar para seus próprios aplicativos. **Topics** + [Ferramentas disponíveis](#available-tools) + [Políticas de autorização](#authorization-policies) + [Entendendo a semântica de autorização](#authorization-semantics) + [Cenários de teste](#test-scenarios) + [IAM-based exemplos de autorização](#iam-authorization-examples) ## Ferramentas disponíveis A API de seguros fornece cinco ferramentas para gerenciar apólices e sinistros de seguro: API de seguros \_\_\_get\_policy Recupere os detalhes da apólice de seguro. **Parâmetros:** + `policyId`(string, obrigatório) - O identificador da política API de seguro \_\_\_file\_claim Registre uma reclamação de seguro. **Parâmetros:** + `policyId`(string, obrigatório) - O identificador da política + `claimType`(string, obrigatório) - Tipo de reclamação (por exemplo, “saúde”, “propriedade”, “auto”) + `amount`(número, obrigatório) - Valor da reclamação + `description`(string, opcional) - Descrição da reivindicação API de seguros \_\_\_Atualizar\_Cobertura Atualize a cobertura da apólice. **Parâmetros:** + `policyId`(string, obrigatório) - O identificador da política + `coverageType`(string, obrigatório) - Tipo de cobertura (por exemplo, “responsabilidade”, “colisão”) + `newLimit`(número, obrigatório) - Novo limite de cobertura API de seguros \_\_\_get\_claim\_status Verifique o status da reclamação. **Parâmetros:** + `claimId`(string, obrigatório) - O identificador da solicitação API de seguro\_\_\_Calculate\_Premium Calcule o prêmio do seguro. **Parâmetros:** + `coverageType`(string, obrigatório) - Tipo de cobertura + `coverageAmount`(número, obrigatório) - Valor da cobertura + `riskFactors`(objeto, opcional) - Fatores de avaliação de risco ## Políticas de autorização As políticas a seguir demonstram vários recursos e padrões de autorização da linguagem Cedar. Cada política inclui descrição em linguagem natural, código Cedar e explicação detalhada. ### Política 1: Multi-action permissão Essa política demonstra como conceder acesso a várias ações relacionadas usando uma única declaração de política. **Linguagem natural:** permita que todos os diretores obtenham a apólice e obtenham o status da reclamação. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action in [ AgentCore::Action::"InsuranceAPI___get_policy", AgentCore::Action::"InsuranceAPI___get_claim_status" ], resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ); ``` **Explicação:** essa política demonstra permissões de várias ações usando o operador. `in` Em vez de escrever políticas separadas para cada operação de leitura, uma única política concede acesso a várias ações relacionadas. Isso é útil para agrupar operações semelhantes que compartilham os mesmos requisitos de autorização. ### Política 2: Scope-based autorização Essa política mostra como usar os escopos do OAuth para controlar o acesso a operações específicas. **Linguagem natural:** permita que diretores com escopo contendo “seguro:reclamação” apresentem reivindicações. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) when { principal.hasTag("scope") && principal.getTag("scope") like "*insurance:claim*" }; ``` **Explicação:** essa política demonstra a validação do escopo do OAuth usando tags. O `hasTag` método verifica se a tag existe e `getTag` recupera seu valor. O `like` operador com curingas (\*) realiza a correspondência de padrões, permitindo formatos de escopo flexíveis, como “seguro:reclamação”, “seguro:reclamação: escrita” ou “seguro administrativo: reclamação”. ### Política 3: Role-based autorização com a menos que Essa política demonstra o uso da `unless` cláusula para criar exceções às restrições. **Linguagem natural:** impeça que os diretores atualizem a cobertura, a menos que o diretor tenha a função de “ajustador sênior” ou “gerente”. **Política de cedro:** ``` forbid( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___update_coverage", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) unless { principal.hasTag("role") && (principal.getTag("role") == "senior-adjuster" || principal.getTag("role") == "manager") }; ``` **Explicação:** Essa política demonstra a `unless` cláusula, que inverte a lógica da condição. A proibição se aplica, a menos que o usuário tenha uma das funções especificadas. Isso é útil para criar exceções às restrições. A política também mostra a lógica OR para verificar vários valores aceitáveis. ### Política 4: igualdade de strings com lógica OR Essa política mostra como validar os parâmetros de entrada e usar a lógica OR para vários valores aceitáveis. **Linguagem natural:** permita que os diretores apresentem reivindicações quando o tipo de reclamação for saúde, propriedade ou automóvel. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) when { context.input has claimType && (context.input.claimType == "health" || context.input.claimType == "property" || context.input.claimType == "auto") }; ``` **Explicação:** essa política demonstra o acesso aos parâmetros de entrada da ferramenta por meio `context.input` de verificações de igualdade de cadeias de caracteres com a lógica OR. O `has` operador primeiro verifica se o campo existe antes de acessá-lo, evitando erros quando faltam campos opcionais. ### Política 5: Verificação da existência do campo Essa política demonstra como aplicar regras de negócios exigindo campos opcionais. **Linguagem natural:** impeça que os diretores apresentem reivindicações, a menos que uma descrição seja fornecida. **Política de cedro:** ``` forbid( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___file_claim", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) unless { context.input has description }; ``` **Explicação:** esta política demonstra a imposição de campos obrigatórios para parâmetros opcionais. O campo de descrição é opcional no esquema da ferramenta, mas essa política o torna obrigatório ao proibir solicitações que não o incluam. Isso mostra como as políticas podem adicionar regras de negócios além da validação do esquema. ### Política 6: Username-based autorização Essa política mostra como conceder acesso com base em identidades de usuário específicas. **Linguagem natural:** permita que diretores com o nome de usuário “Clare” atualizem a cobertura. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___update_coverage", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) when { principal.hasTag("username") && principal.getTag("username") == "Clare" }; ``` **Explicação:** essa política demonstra a autorização baseada em nome de usuário usando a correspondência exata de cadeias de caracteres. Combinado com a Política 3, isso cria uma autorização em duas partes: os usuários devem ter o nome de usuário “agente de seguros” E ter a função de “avaliador sênior” ou “gerente” para atualizar a cobertura. ### Política 7: Correspondência de padrões com similares Essa política demonstra a correspondência flexível de padrões usando curingas para controle de acesso baseado em categorias. **Linguagem natural:** permita que os diretores calculem o prêmio quando o tipo de cobertura contiver “automático”. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___calculate_premium", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) when { context.input has coverageType && context.input.coverageType like "*auto*" }; ``` **Explicação:** Essa política demonstra a correspondência flexível de padrões com o `like` operador. O caractere curinga \* corresponde a qualquer caractere, então “auto”, “responsabilidade automática”, “automático abrangente” ou “colisão automática” seriam todos iguais. Isso é útil quando você deseja combinar uma categoria de valores em vez de cadeias de caracteres exatas. ### Política 8: condições combinadas com AND Essa política mostra como combinar várias condições para criar regras de autorização complexas. **Linguagem natural:** permita que os diretores atualizem a cobertura quando o tipo de cobertura for responsabilidade civil ou colisão e um novo limite for fornecido. **Política de cedro:** ``` permit( principal is AgentCore::OAuthUser, action == AgentCore::Action::"InsuranceAPI___update_coverage", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance" ) when { context.input has coverageType && context.input has newLimit && (context.input.coverageType == "liability" || context.input.coverageType == "collision") }; ``` **Explicação:** Essa política demonstra a combinação de várias condições com a lógica AND. Todas as três condições devem ser verdadeiras: coverageType deve existir, newLimit deve existir e coverageType deve ser “responsabilidade” ou “colisão”. Isso funciona com a Política 6 para criar uma autorização em camadas: quem pode atualizar (Política 6) e o que pode ser atualizado (Política 8). ## Entendendo a semântica de autorização Essas políticas demonstram as principais semânticas de autorização do Cedar: ### Negação padrão Se nenhuma política permitir explicitamente uma ação, ela será negada. Por exemplo, um usuário sem o escopo “seguro:reclamação” não pode registrar reivindicações, mesmo que nenhuma apólice o proíba explicitamente. ### Proibir vitórias Se alguma política de proibição corresponder, a solicitação será negada, mesmo que as políticas de permissão também correspondam. A Política 5 (proibir sem descrição) substitui a Política 2 (permissão com escopo) quando a descrição está ausente. ### Estratificação de políticas Várias políticas podem ser aplicadas à mesma solicitação: + A apólice 6 permite que o agente de seguros atualize a cobertura + A política 3 proíbe atualizações, a menos que o usuário tenha uma função de ajustador sênior ou gerente + A Política 8 permite atualizações somente para tipos de responsabilidade ou colisão Para que uma solicitação seja bem-sucedida, ela deve satisfazer todos os três: ser agente de seguros (Política 6), ter função de avaliador sênior ou gerente (Política 3) e atualizar a responsabilidade ou colisão (Política 8). ## Cenários de teste Os cenários a seguir demonstram como as políticas funcionam juntas na prática: Cenário 1: política regular de visualização de usuários **Usuário:** username="john”, scope="insurance:view” **Ação: get\_policy** **Esperado:** PERMITIR (Política 1) Cenário 2: Usuário registrando reclamação de saúde com descrição **Usuário:** username="jane”, scope="insurance:claim” **Ação:** file\_claim com claimType="health”, description="Despesas médicas” **Esperado:** PERMITIR (Política 2, Política 4, Política 5 não proíbe) Cenário 3: usuário registrando uma reclamação sem descrição **Usuário:** username="jane”, scope="insurance:claim” **Ação:** file\_claim com claimType="health”, sem descrição **Esperado:** NEGAR (a Política 5 proíbe vitórias) Cenário 4: agente de seguros atualizando a cobertura **Usuário:** username="insurance-agent”, role="senior-adjuster” **Ação:** update\_coverage com coverageType="Liability” **Esperado:** PERMITIR (Política 6, Política 3 não proíbe, Política 8) Cenário 5: agente de seguros sem função sênior **Usuário:** username="insurance-agent”, role="agent” **Ação:** update\_coverage com coverageType="Liability” **Esperado:** NEGAR (a Política 3 proíbe vitórias) Cenário 6: cálculo do prêmio para cobertura automática **Usuário:** username="anyone”, scope="any” **Ação:** calculate\_premium com coverageType="responsabilidade automática” **Esperado:** PERMITIR (Política 7, o padrão corresponde a “auto”) ## IAM-based exemplos de autorização Quando seu AgentCore Gateway usa a autenticação AWS\_IAM em vez de OAuth, o principal nas políticas do Cedar é representado como. `AgentCore::IamEntity` Para a autenticação de chamadores por meio de funções assumidas, o ID da entidade Cedar usa o formato`arn:aws:sts:::assumed-role/`, permitindo a `principal ==` correspondência estável e `principal.id` a correspondência de padrões. ### Permissão básica de entidade do IAM Essa política permite que qualquer IAM-authenticated chamador use uma ferramenta específica: ``` permit( principal is AgentCore::IamEntity, action == AgentCore::Action::"OrderAPI___get_order", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ); ``` **Explicação:** Essa é a forma mais simples de política do IAM. Ele permite que qualquer chamador autenticado via AWS\_IAM chame a ferramenta get\_order. Use isso quando precisar apenas verificar se os chamadores IAM-authenticated não têm restrições adicionais. ### Role-based restrição com correspondência principal exata Restrinja o acesso à ferramenta aos chamadores usando uma função específica do IAM usando`principal ==`: ``` permit( principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/MyServiceRole", action == AgentCore::Action::"OrderAPI___process_order", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ); ``` **Explicação:** O ID da entidade Cedar para funções assumidas é`arn:aws:sts:::assumed-role/`. Isso permite uma `principal ==` correspondência estável, independentemente do nome da sessão usado durante a autenticação. ### Role-based restrição com correspondência de padrões Você também pode usar `principal.id like` para padrões de correspondência mais amplos: ``` permit( principal is AgentCore::IamEntity, action == AgentCore::Action::"OrderAPI___process_order", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ) when { principal.id like "arn:aws:sts::111122223333:assumed-role/MyServiceRole" }; ``` **Explicação:** Isso obtém o mesmo resultado, `principal ==` mas usa uma `when` cláusula. A correspondência de padrões é útil quando você precisa de uma correspondência mais ampla, como combinar qualquer função em uma conta (`principal.id like "arn:aws:sts::111122223333:assumed-role/*"`). ### Account-based restrição Restrinja o acesso à ferramenta a chamadores de AWS contas específicas: ``` permit( principal is AgentCore::IamEntity, action == AgentCore::Action::"OrderAPI___process_order", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ) when { principal.id like "*:111122223333:*" }; ``` **Explicação:** O padrão \*:111122223333: \* corresponde a qualquer ARN contendo esse ID da conta. Isso restringe o acesso somente aos chamadores da AWS conta especificada. ### Multi-agent federação Quando vários agentes com funções diferentes do IAM acessam o mesmo gateway, crie políticas separadas para controlar quais ferramentas cada agente pode usar: ``` // Agent A can only read orders permit( principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/AgentA-Role", action == AgentCore::Action::"OrderAPI___get_order", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ); // Agent B can read and process orders permit( principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/AgentB-Role", action in [ AgentCore::Action::"OrderAPI___get_order", AgentCore::Action::"OrderAPI___process_order" ], resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ); ``` **Explicação:** Esse padrão é útil para arquiteturas de vários agentes em que agentes diferentes têm funções diferentes do IAM e devem ter níveis diferentes de acesso à ferramenta. Cada política é usada `principal ==` com o ID da entidade da função específica. A `tools/list` resposta para cada agente inclui apenas as ferramentas que eles estão autorizados a usar. ### IAM com validação de entrada Combine a correspondência principal do IAM com a validação da entrada da ferramenta: ``` permit( principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/RefundProcessorRole", action == AgentCore::Action::"RefundAPI___process_refund", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/refund-gateway" ) when { context.input has amount && context.input.amount < 1000 }; ``` **Explicação:** Essa política combina a correspondência exata do principal com a validação da entrada. Somente os chamadores que suponham que sejam `RefundProcessorRole` da conta especificada podem processar reembolsos e somente quando o valor do reembolso for inferior a $1000. ### Proibir contas específicas Impeça que chamadores de AWS contas específicas acessem ferramentas confidenciais: ``` forbid( principal is AgentCore::IamEntity, action == AgentCore::Action::"AdminAPI___delete_resource", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/admin-gateway" ) when { principal.id like "*:444455556666:*" }; ``` **Explicação:** Essa política de proibição impede que todos os chamadores de uma conta de fornecedor terceirizado (444455556666) realizem exclusões administrativas. Devido à semântica de proibições, isso tem precedência sobre qualquer política de permissão. ### Proíba funções específicas de operações confidenciais Impeça que os chamadores que usam funções somente de leitura realizem operações de gravação: ``` forbid( principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/ReadOnlyAgentRole", action in [ AgentCore::Action::"OrderAPI___process_order", AgentCore::Action::"OrderAPI___cancel_order" ], resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway" ); ``` **Explicação:** Essa política de proibição impede que os chamadores que usam o realizem operações `ReadOnlyAgentRole` de gravação, independentemente de quaisquer políticas de permissão que, de outra forma, poderiam permiti-las.