# 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:

```mermaid
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:

```text
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.