Gestión de credenciales

Casi toda automatización necesita acceder a sistemas que piden usuario y contraseña: un ERP, un servidor de correo, una API, una base de datos. El problema es obvio: no debes escribir esas contraseñas dentro del playbook. Si lo haces, cualquiera con acceso al proyecto las ve, quedan en los logs y cambiarlas obliga a reeditar la automatización.

Las credenciales de Zoan Cloud resuelven esto. Guardan los datos sensibles cifrados dentro de un ambiente, y tus bots los obtienen en tiempo de ejecución por nombre, sin que el valor real aparezca nunca en el playbook ni en los registros.

Idea central

En el playbook escribes credential("erp-produccion"), no la contraseña. El valor real lo inyecta el agente de forma segura justo al ejecutar. Cambiar la contraseña es actualizar la credencial en el portal — el playbook no se toca.

Crear una credencial

1. Elige el ambiente arriba a la derecha y abre Centro › Recursos › Credenciales.
2. Haz clic en Nueva credencial.
3. Dale un nombre único y descriptivo (ej. erp-produccion, smtp-notificaciones, gmail-api). Este es el nombre con el que la referenciarás.
4. Agrega los datos que la credencial necesita (ver los dos formatos abajo).
5. Guarda.

Dos formatos de credencial

Valor único

Para un secreto simple, como un token o una sola contraseña. Lo recuperas con credential("nombre")["value"], o pasando credential("nombre") a un parámetro de tipo credencial.

Campo	Valor
valor	sk-prod-9f2a...

Múltiples campos (clave-valor)

Para sistemas que requieren varios datos juntos. Cada campo se recupera por su clave con ["campo"]. Por ejemplo, una conexión a base de datos:

Clave	Valor
host	db.miempresa.com
user	nexus_user
password	••••••••
database	produccion

Los valores no se vuelven a mostrar

Una vez guardados, los valores quedan cifrados y no se pueden ver desde el portal — solo reemplazar. Esto protege los secretos incluso de quien administra Zoan Cloud. Guarda el valor original en tu gestor de contraseñas si necesitas conservarlo.

Llave de service account (Google)

Para autenticación servidor-a-servidor (p. ej. una service account de Google), guarda el JSON completo de la llave —tal cual lo descargas de Google Cloud— como el valor único de una credencial. La actividad la referencia por nombre y construye la autenticación desde ese JSON.

Nunca pegues la llave dentro del playbook

La private_key de una service account es tan sensible como una contraseña. Guárdala solo como credencial cifrada y referénciala por nombre; jamás la pongas como parámetro literal de una actividad ni como ruta de archivo en el robot.

¿Credencial u conexión OAuth?

Si el acceso es a una cuenta de terceros vía OAuth (Google, Microsoft…), normalmente usarás una conexión OAuth en lugar de una credencial. La credencial con JSON de service account es la alternativa sin consentimiento de usuario (ideal para desatendido).

Las credenciales viven en un ambiente

Una credencial pertenece al ambiente donde la creas y solo es visible para los agentes de ese ambiente. Esto es intencional y muy útil:

• En Pruebas apuntas a un sistema de pruebas; en Producción, al real.
• El mismo playbook funciona en ambos sin cambios, porque referencia la credencial por nombre (erp), y cada ambiente resuelve su propio valor.

Globales y herencia

Una credencial puede ser global (menú Credenciales): se hereda en todos los ambientes automáticamente, y una credencial local con el mismo nombre la pisa en su ambiente. Es el mecanismo para compartir: lo común vive en global; lo específico se sobreescribe por ambiente. El tab de credenciales de cada ambiente muestra también las globales heredadas y si están pisadas.

Copiar entre ámbitos

Cada credencial tiene la acción Copiar a… (a global o a otro ambiente): el secreto se re-cifra en el servidor — nunca pasa por el navegador — y si el nombre ya existe en el destino, se rechaza. No existen “enlaces” entre ambientes a propósito: un enlace de pruebas al secreto de producción rompería el aislamiento que los ambientes garantizan.

Al copiar a otro ambiente, la credencial conserva su carpeta: en el destino queda en la carpeta con el mismo camino (por ejemplo Finanzas/Pagos) y, si no existe, se crea esa estructura (hace falta poder crear carpetas en la carpeta existente más profunda). Los vínculos con otras carpetas no se copian.

Playbook:  = credential("erp")
                  │
   ┌──────────────┴───────────────┐
Ambiente "Pruebas"          Ambiente "Producción"
 erp → erp-test.com         erp → erp.miempresa.com

Convención: mismo nombre en cada ambiente

Usa el mismo nombre lógico para la credencial en todos los ambientes (erp, no erp-prod y erp-test). Así el playbook es idéntico en todos lados y solo cambia el valor según dónde se ejecuta.

Credenciales en carpetas

Cada área puede guardar sus credenciales en su propia carpeta: las de Compras en Compras, las de Nómina en Nómina. Así cada equipo administra sus secretos, sus robots los usan sin configurar nada más y cada persona ve solo lo de las carpetas donde entra.

• Crear: en Centro › Recursos › Credenciales, elige la carpeta en el árbol de la izquierda y pulsa Nueva credencial; queda en esa carpeta. Lo que creas con la raíz seleccionada sirve para todo el ambiente.
• Ver: en una carpeta ves sus credenciales (y las de sus subcarpetas) y las que se le vincularon desde otras carpetas, marcadas con Vinculada desde …. En la raíz ves las de la raíz.
• Mover: con Mover a otra carpeta la llevas a otra; hace falta poder editarla en su carpeta actual y crear en la de destino.
• Nombres únicos en el ambiente: dos credenciales no pueden llamarse igual en el mismo ambiente, estén en la raíz o en carpetas (sin distinguir mayúsculas). Si el nombre ya existe, el aviso dice en qué carpeta está la otra.

Las credenciales que ya tenías siguen en la raíz y funcionan igual.

Quién puede hacer qué

Los permisos credential:list, credential:read, credential:create, credential:update y credential:delete gobiernan las credenciales y también las integraciones. Lo que una persona puede hacer con una credencial es la suma de sus roles que la cubren: los de la organización o la raíz del ambiente y los de la carpeta de la credencial. Para quien no entra a esa carpeta, la credencial no aparece.

Vincular desde otra carpeta

Cuando dos áreas usan el mismo sistema, el secreto se guarda una sola vez y se vincula a las carpetas que lo necesitan. Al cambiar la contraseña, todas usan la nueva.

1. Selecciona en el árbol la carpeta que va a usarla y pulsa Vincular desde otra carpeta.
2. Elige la credencial y confirma.

Para vincular necesitas credential:create en la carpeta destino y credential:read en la carpeta dueña. Desde el destino, con credential:read, se puede ver y probar; editarla, moverla o borrarla se hace con los permisos de su carpeta dueña.

• Un vínculo vale para esa carpeta, no para sus subcarpetas: vincula cada carpeta que la use.
• Las credenciales de la raíz ya las usan todas las carpetas, así que no se vinculan.
• Desvincular (con credential:delete en la carpeta destino) quita solo el vínculo; Eliminar la credencial la quita de todas las carpetas.

Revisa quién la usa antes de desvincular o mover

Desvincular o mover no se bloquea. Si un robot, flujo o asistente la necesitaba y deja de alcanzarla, falla con un error que dice cuál y desde qué carpeta, por ejemplo: «La credencial «sap-prod» no existe o no está disponible desde la carpeta «Compras». Créala en esa carpeta, vincúlala a ella («Vincular desde otra carpeta») o déjala en la raíz del ambiente.»

Carpetas con credenciales

Una carpeta que tiene credenciales no se puede eliminar; si solo guarda el historial de credenciales borradas, se archiva. Al archivar o eliminar una carpeta se quitan los vínculos hacia ella.

En la auditoría

La auditoría registra credential.created, credential.updated (un movimiento queda con la carpeta de origen y la de destino), credential.deleted, credential.linked, credential.unlinked y credential.unusable_from_folder (un robot pidió una credencial que está en una carpeta que no alcanza). Quien tiene audit:read ve todos los eventos; la carpeta sirve para filtrar.

Actualizar una credencial

Puedes agregar, modificar o reemplazar los valores de una credencial existente. Los cambios aplican desde la próxima ejecución que la use; las ejecuciones en curso no se ven afectadas. No necesitas volver a publicar ningún paquete.

Buenas prácticas de seguridad

• Nombres descriptivos y consistentes: erp-produccion, gmail-notificaciones.
• Una credencial por sistema y por ambiente: no reutilices la misma en producción y pruebas.
• Rota periódicamente los secretos actualizando solo el valor en el portal.
• Principio de mínimo privilegio: que la cuenta detrás de la credencial tenga solo los permisos que el bot necesita.

Siguientes pasos

• Uso de credenciales en automatizaciones — cómo referenciarlas desde un playbook.
• Ambientes — cómo separar producción y pruebas.