153 lines
2.9 KiB
Markdown
153 lines
2.9 KiB
Markdown
# 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.
|