Conceptos centrales

Secreto como registro en Passwork

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

Dónde almacenar un secreto dentro de un registro

Tipo de campo	Qué almacenar	Ejemplo
Iniciar sesión	Credenciales de nombre de usuario	svc_backend
Contraseña	Secretos, contraseñas, claves	xK9#mP2$vL7!nQ
Campos personalizados	Secretos, tokens y claves con nombre	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 recuperación de CLI/SDK sea sencilla y mantiene los registros autodocumentados.

Secretos de clasificación

Para organizar y localizar secretos de forma eficaz, utilice:

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

Secretos estructurantes

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

Enfoque organizativo

Cree una bóveda o carpeta raíz dedicada para los secretos de infraestructura. En el interior, organiza por ambiente 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

Recupera todos los secretos de producción:

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

Recuperar solo secretos de bases de datos de producción:

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

Nombrar registros

Elija nombres claros que transmitan un propósito:

• Bueno: mysql-primary, memcached-sessions, twilio-auth-token
• Evite: secret1, temp-pass, asdf123

Los nombres descriptivos te ayudan a:

• encuentre secretos rápidamente en la interfaz de usuario o mediante la búsqueda CLI;
• entender el propósito de un registro de un vistazo;
• evitar 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 y infrastructure/staging.
• Desarrolladores → acceso limitado a infrastructure/development.
• Servicio CI/CD (cuenta de servicio) → acceso de solo lectura a infrastructure/production para implementaciones.

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

Cómo funciona la autenticación API

Las llamadas Passwork API se ejecutan como una cuenta registrada: ya sea una persona (usuario interactivo) o una cuenta de servicio: un tipo de cuenta dedicada para scripts, CI/CD y otras automatizaciones. En ambos casos utilizas un par de tokens:

• Token de acceso: autoriza solicitudes API; vida limitada.
• Refresh token: obtiene un nuevo token de acceso sin emitir un par nuevo desde cero (donde se aplica el reingreso de credenciales).

La renovación del par de tokens a través de HTTP (rotación completa o solo acceso/solo actualización) se trata en API rotación de tokens. Los tokens se emiten para la cuenta elegida; cada llamada API se ejecuta con los permisos de esa cuenta y se registra en el registro de auditoría bajo esa identidad. Esto significa:

• La integración solo ve bóvedas y carpetas a las que puede acceder la cuenta.
• Se permiten escrituras solo cuando esa cuenta tiene derechos.
• El registro de auditoría muestra qué cuenta realizó la acción (incluidas las cuentas de servicio).

Cuentas de servicio para integraciones

Para la automatización (CI/CD, secuencias de comandos 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.
• Borrar pista de auditoría: los registros muestran claramente las acciones activadas por la automatización.
• Independencia del personal: los cambios de personal no interrumpen la CI/CD.
• Configuraciones de seguridad flexibles: configure políticas independientes para cuentas de servicio.

Recomendación

Cuentas de servicios grupales con una rol dedicada (p. ej., Service Accounts o CI/CD Integration). Para este rol, configure:

• API vida útil del token: tokens más cortos para trabajos de CI/CD y más largos para servicios siempre activos.
• Políticas de contraseña: relaja los requisitos si la autenticación es solo mediante token.

Diseño de cuenta de servicio de muestra:

Cuenta	Propósito	Acceso
deploy-prod-svc	Despliegue de producción	de sólo lectura a infrastructure/production
deploy-staging-svc	Implementación provisional	de sólo lectura a infrastructure/staging
cred-rotator	Rotación secreta	lectura-escritura en infrastructure/production, infrastructure/staging
health-checker	Comprobación de integridad	sólo lectura para todos los secretos

Consideraciones de seguridad

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

1. Mínimo privilegio: cada integración recibe solo el acceso que necesita. El CI/CD de implementación no puede rotar secretos y el robot de rotación no puede ver los datos del entorno de desarrollo.

2. Auditoría transparente: cada operación se registra con usuario, marca de tiempo y tipo de acción. Durante los incidentes, puede rastrear exactamente qué integración accedió a un secreto y cuándo.

3. Respuesta rápida: si una integración se ve comprometida, revoque los tokens para esa cuenta de servicio específica sin afectar a los demás.

4. Responsabilidad clara: DevOps administra las cuentas de servicios de infraestructura mientras los equipos de desarrollo manejan las suyas propias.

Importante

Todas las operaciones secretas (leer, modificar, eliminar) 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 de registro)