agent_framework_oci/specs/en/SPEC-018-Security-and-Identity-Model.md

SPEC-018 — Security and Identity Model

Agent Platform OCI

Version: 1.0.0

---

Reading guide

each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.

The document structure is:

1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.

---

1. Concept

Security and Identity Model Defines como workloads autenticam, como Components autorizam actions, como segredos are protegidos and como Data sensíveis are tratados.

2. Modelos of Authentication

Modo	Uso
config_file	Development local with ~/.oci/config.
instance_principal	Execution em OCI Compute.
workload_identity	Execution em OKE/Kubernetes.
resource_principal	Recursos OCI gerenciados.
api_key	Endpoints compatíveis with OpenAI when aplicável.

3. Workload Identity

Flow:

flowchart LR
    Pod[Pod Kubernetes] --> SA[ServiceAccount]
    SA --> WI[Workload Identity]
    WI --> IAM[OCI IAM Policy]
    IAM --> Resource[OCI Resource]

4. Authorization

Escopos:

• Agent can chamar tool?
• tenant can use provider?
• canal can chamar agent_id?
• User can executar ação?
• tool mutável exige confirmação?

5. Secrets

Secrets No ficam no código.

sources:

• OCI Vault;
• Kubernetes Secrets;
• secret manager corporativo.

Examples:

LANGFUSE_SECRET_KEY
OCI_GENAI_API_KEY
ADB_PASSWORD
MCP_BACKEND_TOKEN

6. Proteção of Data

apply:

• máscara of PII;
• minimização of metadata;
• sanitização of payload;
• No logar secrets;
• retenção controlada;
• classificação of Data.

7. Security em MCP

MCP tools must ter:

• Authorization por Agent;
• allowlist;
• timeout;
• retry;
• idempotência declarada;
• confirmação for operações mutáveis.

8. Security em canais

Channel Gateway must:

• validate assinatura;
• validate origem;
• deduplicar;
• rate limit;
• remover tokens;
• normalizar payload;
• rejeitar anexos inválidos.

9. Auditoria

Registrar:

• User/canal;
• agent_id;
• tenant_id;
• tool Call;
• Model Used;
• Decision of guardrail;
• judge score;
• Error;
• trace_id.

10. Common errors

Error	Impact	Correction
Secret em .env versionado	Vazamento.	use Vault/Secrets.
Tool without Authorization	Acesso indevido.	Allowed agents por tool.
Payload bruto em logs	Exposição of Data.	Mascarar/minimizar.
Instance main local	Timeout/Authentication invalid.	use config_file local.

11. Acceptance criteria

• Modo of Authentication definido por ambiente.
• Secrets external ao código.
• MCP tools autorizadas por Agent.
• Channel Gateway valida origem.
• PII mascarada em logs.
• Events auditáveis emitidos.
• Workload Identity definido for OKE.
• Security review executado before Production.