concepts

path: secret-management/concepts.mdx title: Conceptos fundamentales slug: /secret-management/concepts pagination_next: secret-management/cli pagination_prev: secret-management/intro sidebar_position: 2 description: >- Conceptos básicos de la gestión de secretos en Passwork: qué cuenta como un secreto, qué tipos de campos puede utilizar y cómo clasificar los secretos. keywords:

Passwork
secrets
secret management
structure
folders
tags

El secreto como un registro en Passwork

Passwork no tiene una entidad dedicada de «secreto» — cualquier registro de contraseña puede funcionar como un secreto. Esto le brinda flexibilidad: la misma interfaz funciona tanto para contraseñas de usuarios finales como para secretos de infraestructura.

Dónde almacenar un secreto dentro de un registro

Tipo de campo	Qué almacenar	Ejemplo
Login	Credenciales de usuario	`svc_backend`
Contraseña	Secretos, contraseñas, claves	`xK9#mP2$vL7!nQ`
Campos personalizados	Secretos con nombre, tokens, claves	`AWS_SECRET_KEY`, `OAUTH_CLIENT_SECRET`, `REDIS_AUTH`
Descripción	Fragmentos de configuración, JSON, YAML	Cadenas de conexión, configuraciones JSON

Recomendación

Para la automatización, utilice campos personalizados con nombres descriptivos (MYSQL_ROOT_PASS, STRIPE_SECRET). Esto hace que la obtención mediante CLI/SDK sea sencilla y mantiene los registros autodocumentados.

Clasificación de secretos

Para organizar y localizar secretos de manera efectiva, utilice:

Etiquetas — agrupaciones lógicas: production, staging, development, db, cloud, k8s.
Título — describe el propósito del secreto
Jerarquía de carpetas — agrupa los secretos relacionados

Estructuración de secretos

Una estructura de carpetas bien diseñada es esencial para la automatización. Cuando los secretos siguen un patrón predecible, las herramientas CLI y SDK pueden localizarlos y recopilarlos sin configuración manual.

Enfoque de organización

Cree una bóveda dedicada o una carpeta raíz para los secretos de infraestructura. Dentro, organice por entorno y categoría:

infrastructure/
├── production/
│   ├── databases/
│   │   ├── mysql-primary
│   │   └── memcached-sessions
│   ├── cloud/
│   │   └── aws-credentials
│   └── k8s/
│       └── cluster-admin
├── staging/
│   ├── databases/
│   └── cloud/
└── development/
    └── local/

Cómo esto simplifica la automatización

Obtener todos los secretos de producción:

passwork-cli exec --folder-id <infrastructure/production ID>

Obtener solo los secretos de BD de producción:

passwork-cli exec --folder-id <infrastructure/production/databases ID>

Nomenclatura de registros

Elija nombres claros que transmitan el propósito:

Correcto: mysql-primary, memcached-sessions, twilio-auth-token
Evitar: secret1, temp-pass, asdf123

Una nomenclatura descriptiva le ayuda a:

encontrar secretos rápidamente en la interfaz de usuario o mediante búsqueda CLI;
comprender el propósito de un registro de un vistazo;
prevenir confusiones durante la rotación y las auditorías.

Control de acceso

Passwork ofrece permisos granulares tanto a nivel de bóveda como de carpeta:

Equipo de plataforma → acceso completo a infrastructure/production e infrastructure/staging.
Desarrolladores → acceso limitado a infrastructure/development.
Servicio CI/CD (cuenta de servicio) → acceso de solo lectura a infrastructure/production para despliegues.

Los permisos se heredan a lo largo de la jerarquía de carpetas, pero se pueden personalizar en cualquier nivel.

Cómo funciona la autenticación de la API

Cada integración de Passwork opera en nombre de un usuario específico. El acceso a la API requiere un par de tokens:

Token de acceso — autoriza las solicitudes de la API; tiene un tiempo de vida limitado.
Token de actualización — obtiene un nuevo token de acceso sin volver a introducir las credenciales.

Los tokens están vinculados a un usuario, y todas las operaciones de la API se ejecutan con los permisos de ese usuario. Esto significa:

La integración solo ve las bóvedas y carpetas a las que el usuario puede acceder.
Las operaciones de escritura requieren los derechos de usuario apropiados.
Todas las acciones aparecen en el registro de auditoría bajo el nombre de ese usuario.

Cuentas de servicio para integraciones

Para la automatización (CI/CD, scripts de rotación, servicios internos), recomendamos cuentas de servicio dedicadas en lugar de cuentas personales de empleados.

Beneficios:

Aislamiento de acceso — las cuentas de servicio acceden solo a las carpetas que necesitan.
Registro de auditoría claro — los registros muestran claramente las acciones activadas por la automatización.
Independencia del personal — los cambios de personal no interrumpen CI/CD.
Configuración de seguridad flexible — configure políticas separadas para las cuentas de servicio.

Recomendación

Agrupe las cuentas de servicio bajo un rol dedicado (por ejemplo, Service Accounts o CI/CD Integration). Para este rol, configure:

Tiempo de vida del token de API — tokens más cortos para trabajos de CI/CD, más largos para servicios permanentes.
Políticas de contraseñas — relaje los requisitos si la autenticación es solo por token.

Ejemplo de distribución de cuentas de servicio:

Cuenta	Propósito	Acceso
`deploy-prod-svc`	Despliegue en producción	solo lectura a `infrastructure/production`
`deploy-staging-svc`	Despliegue en staging	solo lectura a `infrastructure/staging`
`cred-rotator`	Rotación de secretos	lectura-escritura a `infrastructure/production`, `infrastructure/staging`
`health-checker`	Verificación de integridad	solo lectura a todos los secretos

Consideraciones de seguridad

El modelo «integración = usuario» proporciona varias ventajas de seguridad:

Mínimo privilegio — cada integración recibe solo el acceso que requiere. El CI/CD de despliegue no puede rotar secretos, y el bot de rotación no puede ver los datos del entorno de desarrollo.
Auditoría transparente — cada operación se registra con usuario, marca de tiempo y tipo de acción. Durante incidentes, puede rastrear exactamente qué integración accedió a un secreto y cuándo.
Respuesta rápida — si una integración se ve comprometida, revoque los tokens de esa cuenta de servicio específica sin afectar a las demás.
Responsabilidad clara — DevOps gestiona las cuentas de servicio de infraestructura mientras que los equipos de desarrollo gestionan las suyas propias.

Importante

Todas las operaciones con secretos (lectura, modificación, eliminación) se registran en el registro de auditoría de Passwork, incluyendo:

Quién realizó la operación (nombre de usuario o cuenta de servicio)
Cuándo (marca de tiempo)
Qué se hizo (tipo de operación, ID del registro)

El secreto como un registro en Passwork​

Dónde almacenar un secreto dentro de un registro​

Clasificación de secretos​

Estructuración de secretos​

Enfoque de organización​

Cómo esto simplifica la automatización​

Nomenclatura de registros​

Control de acceso​

Cómo funciona la autenticación de la API​

Cuentas de servicio para integraciones​

Consideraciones de seguridad​