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.

Ferramentas disponíveis

A API de seguros fornece cinco ferramentas para gerenciar apólices e sinistros de seguro:

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:

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:

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 formatoarn:aws:sts::<account>:assumed-role/<role-name>, 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 usandoprincipal ==:

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::<account>:assumed-role/<role-name>. 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.