Referência de controle de acesso

As quatro camadas

Ordem	Camada	Uma negação aparece como
1	Isolamento entre organizações	404 — a linha é invisível
2	Permissões	403 com os códigos faltantes nomeados
3	Políticas ABAC	403 para um registro solicitado diretamente; descartado de uma lista
4	Mascaramento de campos	O valor vem mascarado, não o registro recusado

A camada 3 descartar em vez de gerar erro dentro de uma lista é deliberado: gerar erro revelaria que um registro existe e está sendo retido, o que é em si uma divulgação.

Condições de políticas ABAC

Condição	Casa com
Sujeito	Papéis, grupos ou identidade de quem consulta
Ação	O código de permissão sendo exercido
Ambiente	Contexto da requisição, como origem de rede
Expressão when	Uma condição sobre atributos de quem consulta
Tipo de entidade	O tipo do registro sendo lido
Atributo	Um valor no registro
Relacionamento	Se a entidade de quem consulta está relacionada ao registro
Consentimento	Se um consentimento ativo de dado tipo cobre o registro

As últimas quatro são avaliadas quando o registro é carregado, já que precisam do registro. As primeiras quatro são avaliadas na borda da requisição.

Exemplos práticos

Cada linha é uma única negação. Lembre-se de que a base é permitir, então uma política descreve o que não deve ser alcançável.

Restrição a expressar	Condição	Lê-se como
Equipe offshore não deve abrir prontuários	Tipo de entidade	Negar entity.read para o papel offshore-support quando o tipo for patient
Registros sinalizados para revisão de sanções são exclusivos de conformidade	Atributo	Negar entity.read quando compliance_status for under_review, exceto para compliance-officer
Um gerente de relacionamento vê apenas a própria carteira	Relacionamento	Negar entity.read para o papel relationship-manager a menos que a entidade do próprio solicitante esteja ligada ao registro por manages
Marketing só pode usar um cliente enquanto o consentimento valer	Consentimento	Negar entity.read para o papel marketing a menos que um consentimento marketing_contact ativo cubra o registro
Administração apenas pela rede corporativa	Ambiente	Negar user.update quando a requisição vier de fora da faixa corporativa

A condição de relacionamento exige que a identidade de quem consulta esteja ligada a uma entidade própria; sem esse vínculo não há a que se relacionar, e a condição nega.

Resolução

Regra	Comportamento
Uma negação sempre vence	Independentemente da ordem
Nenhuma regra correspondente	Permitido — a camada é uma sobreposição de negação
Regras inativas	Não avaliadas
Uma negação sem condições	Recusada ao salvar
Uma falha de avaliação num registro aninhado	Falha fechado — o registro é descartado

A ordenação é apresentacional. Nunca é entrada de decisão, então duas regras não podem ser feitas discordar reordenando-as.

Estratégias de mascaramento

Estratégia	Resultado	555-12-3456 vira	Configuração
full	Todo caractere substituído. Preserva o comprimento, nada mais.	***********	Nenhuma
partial	Mantém os últimos caracteres e substitui o restante.	*******3456	showLast
hash	Um hash unidirecional estável: valores iguais continuam iguais sem revelar nenhum deles.	a1b2c3… (64 caracteres hex)	Nenhuma
null	O valor é esvaziado e sinalizado como mascarado; o campo permanece.	null	Nenhuma
redact	Um marcador fixo.	[REDACTED]	Nenhuma

Só partial recebe configuração. showLast define quantos caracteres finais sobrevivem e assume 4 por padrão quando você não informa. Se o valor não for mais longo que showLast, ele é mascarado por inteiro em vez de exposto — assim um valor curto não vaza por uma regra escrita para um valor mais longo.

O mascaramento se aplica a três superfícies: valores de atributo de entidade, rótulos de exibição de entidade e valores de mudança em auditoria.

null se comporta de forma diferente em entradas de auditoria

Num atributo o campo permanece presente com o valor esvaziado, de modo que o leitor percebe que algo foi retido. Num valor de mudança em auditoria a chave é removida por completo. Use redact se quiser um marcador visível nas duas superfícies.

Campos de uma regra de mascaramento

Campo	Aceita	Padrão	Alterável	O que faz
entityTypeId	Um tipo de entidade, ou vazio	—	Não	Qual tipo a regra cobre. Obrigatório para regras de atributo. Para regras de rótulo e de auditoria, deixar vazio aplica a regra a todos os tipos do tenant.
targetKind	entity_attribute, entity_label, audit_change_value	entity_attribute	Não	Qual superfície de resposta a regra rege.
attributePath	1–255 caracteres	—	Não	Qual campo mascarar. Para uma regra de rótulo, a convenção é label.
maskingStrategy	Uma das cinco acima	—	Sim	Como o valor é obscurecido.
maskingConfig	Um objeto	{}	Sim	Configurações da estratégia. Só partial as lê.
appliesToRoles	Até 2.000 caracteres — nomes de papéis separados por vírgula	—	Sim	Para quem a regra mascara. Veja o aviso adiante.
exemptRoles	Até 2.000 caracteres — nomes de papéis separados por vírgula	—	Sim	Quem fica de fora. Quem tiver qualquer papel listado vê o valor em claro.
metadata	Um objeto	{}	Sim	Suas próprias anotações, armazenadas e devolvidas sem interpretação.

Os três primeiros são fixos depois de criados. Para mascarar outro campo, ou o mesmo campo em outra superfície, crie outra regra — não é possível reapontar uma regra existente.

Um appliesToRoles vazio mascara para todos

Deixar a lista de papéis em branco não significa "para ninguém". Significa todos os papéis, administradores inclusive.

Esse é o padrão seguro — uma regra escrita mas ainda não delimitada retém dados em vez de expô-los — mas é o oposto do que a maioria espera, e um campo em branco é fácil de enviar sem querer. Se a regra é para um público restrito, nomeie esses papéis explicitamente; se é para todos exceto alguns, deixe em branco e liste as exceções em exemptRoles.

As regras são únicas pela combinação de tipo, caminho, estratégia e as duas listas de papéis. Criar uma duplicata devolve conflito em vez de acrescentar silenciosamente uma segunda regra que mascararia o mesmo campo duas vezes.

Metadados do ator nunca são mascarados

Quem realizou uma ação nunca é redigido. Mascarar um valor sensível numa entrada de auditoria é correto; ocultar quem fez a mudança anularia a trilha de auditoria. Retire a permissão de auditoria em vez disso.

Integridade referencial

Uma política ABAC que nomeia um código de permissão, papel, grupo, tipo de relacionamento ou tipo de consentimento desconhecido é rejeitada ao salvar, com um 400. Uma regra que referencia algo inexistente nunca dispararia silenciosamente, o que parece cobertura e não é.

A seguir

• Componha papéis e vincule-os a grupos
• Restrinja o acesso a registros individuais
• Mascare campos sensíveis
• Códigos de permissão

---

Última verificação no commit d3c2586b (2026-08-03)