Cuentas de servicio y tokens de API

Por qué no debe utilizar una cuenta personal

Utilizar una cuenta de usuario personal para CI/CD o automatización crea varios problemas:

• El token está vinculado a un empleado: si se marcha, todas las integraciones dejan de funcionar
• Los permisos de una cuenta personal suelen ser más amplios de lo que necesita el script
• Las acciones aparecen en el registro de auditoría con el nombre de la persona, no con el de la canalización
• Revocar el acceso requiere eliminar o modificar la cuenta personal

Una cuenta de servicio dedicada separa la automatización de las identidades humanas, sigue el principio de mínimo privilegio y hace que el rastro de auditoría sea claro.

---

Paso 1: Crear un rol de cuenta de servicio

Antes de crear la cuenta, cree un rol que conceda únicamente lo que necesita la automatización.

1. Vaya a Configuración → Gestión de usuarios → Roles.
2. Haga clic en Crear rol y asígnele un nombre (p. ej., CI/CD service account o Rotation bot).
3. Active únicamente los siguientes permisos:
   • Usar API (necesario para la generación de tokens)
   • Sin acceso a la gestión de usuarios, la configuración del sistema, LDAP, SSO ni la gestión de tipos de bóvedas
4. Haga clic en Crear.

El acceso a los directorios (qué bóvedas y carpetas puede leer o escribir la cuenta de servicio) se configura por separado al crear la cuenta de servicio.

Un rol por tipo de canalización

Si tiene varios casos de uso de automatización (bot de despliegue, script de rotación, exportador de auditoría), cree roles separados con distintos conjuntos de permisos. Esto limita el alcance del daño si un token se ve comprometido.

---

Paso 2: Crear la cuenta de servicio

1. Vaya a Configuración → Gestión de usuarios → Usuarios.
2. Haga clic en Crear usuario.
3. Utilice un login claramente identificable, p. ej., svc-cicd-production o svc-rotation-bot.
4. Asigne el rol creado en el Paso 1 y los grupos, si es necesario.
5. Haga clic en Crear.

Si utiliza LDAP, cree una cuenta de servicio LDAP dedicada en su directorio y asígnela a Passwork. No reutilice una cuenta de servicio de AD que tenga otros derechos en el sistema.

---

Paso 3: Conceder acceso a las bóvedas

La cuenta de servicio debe añadirse explícitamente a las bóvedas y carpetas a las que necesita acceder.

1. Abra el perfil de la cuenta de servicio.
2. Establezca los niveles de acceso necesarios para las bóvedas correspondientes que figuran en la pestaña Derechos de acceso.

Caso de uso	Nivel de acceso mínimo
Canalización de CI/CD (leer secretos para el despliegue)	Solo lectura
Script de rotación (actualizar los valores de los secretos)	Leer y editar
Script de auditoría / informes	Solo lectura
Migración / importación masiva	Acceso completo en la bóveda de destino

Utilice el acceso a nivel de carpeta si la cuenta de servicio solo necesita un subconjunto de la bóveda.

---

Paso 4: Generar el par de tokens

1. Abra el perfil de la cuenta de servicio
2. Abra el menú Tokens de API en el panel del lado derecho y haga clic en Crear token de API.
3. Copie ambos tokens, el accessToken y el refreshToken, inmediatamente: se muestran solo una vez.

Almacene los tokens de forma segura

Nunca almacene tokens en el código fuente, en archivos .env incluidos en los repositorios ni en los registros de tareas de CI/CD. Utilice el almacenamiento de secretos cifrado de su plataforma de CI/CD (GitHub Secrets, GitLab CI/CD con variables enmascaradas, HashiCorp Vault, AWS Secrets Manager, etc.).

---

Ciclo de vida del par de tokens

La API de Passwork utiliza dos tokens con distintos tiempos de vida:

Token	Tiempo de vida típico	Propósito
accessToken	De minutos a horas	Se añade a cada solicitud de la API como Authorization: Bearer
refreshToken	De días a semanas	Se utiliza para obtener un nuevo par de tokens cuando el token de acceso caduca

Cuando accessToken caduca, la API devuelve HTTP 401 con el código accessTokenExpired. La integración entonces llama al endpoint de renovación y actualiza ambos tokens.

El conector de Python gestiona esto automáticamente. Para los scripts de shell que utilizan passwork-cli, la CLI también gestiona la renovación del token de forma transparente cuando se proporciona PASSWORK_REFRESH_TOKEN.

---

Estrategia de rotación de tokens

La rotación periódica del par de tokens de la cuenta de servicio reduce el riesgo derivado de la fuga de tokens.

Tiempos de vida de los tokens recomendados según el caso de uso:

Caso de uso	Tiempo de vida de accessToken	Tiempo de vida de refreshToken
Tarea de CI/CD (efímera)	15–60 minutos	1 día
Servicio siempre activo (supervisión, bot de rotación)	1–4 horas	30 días
Script manual/programado	1 hora	7 días

Rotación de tokens mediante la API:

Hay tres endpoints disponibles (consulte Rotación de tokens de API para la referencia completa):

Rotate full pair

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --header "Authorization: Bearer $PASSWORK_TOKEN" \
  --data "{\"refreshToken\": \"$PASSWORK_REFRESH_TOKEN\"}" | jq .

Rotate access token only

curl -s --request POST \
  --url "https://passwork.example.com/api/v1/sessions/refresh-access-token" \
  --header 'Content-Type: application/json' \
  --header 'X-Response-Format: raw' \
  --data "{\"accessToken\": \"$PASSWORK_TOKEN\"}" | jq .

---

La paradoja del almacenamiento de tokens

Passwork es el almacén de secretos, pero necesita una credencial para acceder a él. ¿Dónde se almacena el token de Passwork?

Enfoques recomendados:

Entorno	Dónde almacenar los tokens de Passwork
CI/CD (GitHub Actions, GitLab)	Almacenamiento de secretos cifrado de la plataforma (variables enmascaradas)
Cargas de trabajo de Kubernetes	Secret de Kubernetes, idealmente rellenado por un operador de secretos externo
Servicios de larga duración	Variable de entorno inyectada al inicio a través de un almacén de secretos de mayor confianza o de la gestión de configuración
Estaciones de trabajo de los desarrolladores	Archivo .env no incluido en el control de versiones, o llavero del sistema operativo

El principio clave: los tokens de Passwork son credenciales de arranque (bootstrap). Se sitúan un nivel por encima de los secretos que protegen. Necesitan una protección fuerte, no tan fuerte como la de una clave raíz de un proveedor en la nube, pero más fuerte que la contraseña de una base de datos de aplicaciones.

LLM version