Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-09-17

Credenciales y rotación

Las familias de secretos del workspace — claves emitidas, contraseña de inicio de sesión, credenciales recuperables del origen y secretos de firma — y qué significa cambiar, rotar y revocar en cada una.

En esta página (17)

Un mapa de qué secretos existen en tu workspace, cómo se guarda cada uno y qué significan cambiar, rotar y revocar para cada uno — porque no significan lo mismo.

No existe un principio único para "todas las credenciales"

Esta página ya afirmó que, para toda credencial, el valor en bruto aparece una vez, que perderlo significa generar otro y que el antiguo se rechaza de inmediato. Eso solo es verdad para una parte de la familia 1 de abajo — las claves emitidas. Una credencial que el producto necesita usar en tu origen de datos es recuperable por naturaleza, y "rechazar la antigua" depende de que alguien la revoque allá, no aquí.

Las familias#

FamiliaQué hace el sistema con el secretoEjemplos
1. VerificadoresSolo verifica un valor que tú presentas. El valor guardado es un hash; ni nosotros podemos volver al original.1a. clave de API de datos y service principal (claves emitidas por el producto) · 1b. contraseña de inicio de sesión
2. Credenciales recuperables del origenNecesita usar el valor para autenticarse en tu base de datos/API. El valor se cifra y se vuelve a leer en la ejecución.contraseña/token/clave de una conexión de datos
3. Secretos de firma y de cálculoNecesita el valor para firmar o calcular algo nuestro. Cifrado, recuperable, pero nunca vuelve a salir hacia ti.secreto de embed, semilla TOTP del MFA, clave de la cuenta de servicio del workspace

La diferencia no es estética: decide qué pasa cuando cambias el valor.

La contraseña de inicio de sesión

no es una clave emitida La familia 1 agrupa dos cosas por la forma de guardarlas (las dos son hash), pero se comportan de manera distinta a la hora de cambiarlas, y tratarlas juntas fue lo que produjo la página anterior. Una clave emitida nace en el producto, aparece una vez, es revocable y deja de valer en el mismo instante en que la revocas. Una contraseña de inicio de sesión identifica a una persona, no es revocable pieza por pieza y — con el diseño de sesión de hoy — cambiarla no cierra las sesiones ya abiertas. Por eso las dos mitades están separadas abajo.


Familia 1a — Claves EMITIDAS por el producto (API de datos y service principal)#

Cómo se guarda. La clave de API de datos (ing_live_…) y el service principal (sp_live_…) se convierten en un SHA-256 del valor en bruto, más un prefijo de 16 caracteres guardado en claro solo para que identifiques la clave en la lista.

Valor en bruto. Aparece una única vez, en la creación. No hay forma de volver a mostrarlo — la base de datos no tiene el original.

¿Lo perdiste? Genera otra y revoca la anterior. No existe recuperación.

Cambiar = rotar. Aquí las dos palabras coinciden: la credencial nace y muere dentro de ingestia.io; no existe copia de ella en otro sistema.

¿La antigua se rechaza de inmediato? Sí. Toda solicitud resuelve la clave consultando la base de datos por el hash y se detiene si hay revokedAt. No hay caché de claves resueltas ni ventana de gracia — la lectura va a la base de datos en cada llamada.

Alcance. El service principal lleva el rol en el envelope de la propia credencial y cae a viewer cuando el envelope es ilegible (fail-closed). Un token ing_live_… nunca se acepta como service principal, y viceversa: el prefijo se verifica antes de cualquier consulta.

  1. Clave de API (datos)

    En Configuración → Claves de API, genera una nueva clave, actualiza tus integradores y revoca la antigua. A partir de la revocación, las llamadas con la clave vieja responden 401 — sin espera.

  2. Service principal

    Genera un nuevo sp_live_… con el rol adecuado, apunta el IdP/integración hacia él y revoca el anterior. Revocar un SP de otro workspace se rechaza (la verificación es por dueño, no por id).


Familia 1b — Contraseña de inicio de sesión#

Cómo se guarda. Hash scrypt con sal, en el formato scrypt$N$sal$hash. El servidor solo verifica lo que escribes; el valor original no queda en ningún lugar.

Dónde se define. En el registro de la cuenta (correo + contraseña). Es el único punto del producto que graba la contraseña de inicio de sesión.

No existe autoservicio de cambio ni de restablecimiento de contraseña

La versión implementada no tiene pantalla de "cambiar mi contraseña" ni flujo de "olvidé mi contraseña". Esta página ya afirmó que "cada persona cambia la suya" — eso no corresponde al producto y se retiró. Cambiar la contraseña de una cuenta existente es, hoy, un caso de soporte, como la recuperación de MFA. Quien entra con Google o con SSO no tiene contraseña local: el cambio ocurre en el proveedor de identidad, no aquí.

¿La antigua deja de valer al instante? Para autenticar, sí: el inicio de sesión verifica el hash grabado, así que una contraseña sustituida no abre una sesión nueva. Pero las sesiones ya abiertas siguen valiendo: la sesión es un token firmado, guardado en el navegador de quien entró, y el servidor no mantiene una lista de sesiones para revocar. Por lo tanto, no hay "cerrar sesión en todos los dispositivos". Una sesión abierta termina cuando la persona sale o cuando el token vence.

¿Y el caché? No existe caché de contraseña. Dentro de una misma solicitud, la sesión se resuelve una única vez (memoización por solicitud) y nada de eso atraviesa solicitudes. Lo que sobrevive al cambio es el token ya emitido — consulta el párrafo de arriba —, no un caché del servidor.

La invitación de miembro no emite contraseña — emite un enlace de activación

Al registrar a alguien en Configuración → Usuarios, el producto no genera una contraseña provisional. Emite un token de activación de un solo uso, con vencimiento, guardado como hash; la persona recibe un enlace de activación y define su propia contraseña al aceptar. El token es una credencial de invitación, no de acceso: sirve una vez, para entrar al workspace, y después ya no vale.

Si el enlace vence o se pierde, la acción es reenviar la invitación (que emite un token nuevo e invalida el anterior). No existe "generar nueva contraseña".


Familia 2 — Credenciales de tus fuentes de datos#

Esta es la familia en la que "rotar" es ambiguo, y donde la confusión sale cara.

Cómo se guarda. Dos posibilidades, por conexión:

  • cifrada en la base de datos (AES-256-GCM) — el predeterminado de hoy; o
  • en la bóveda externa de credenciales, con la base de datos guardando solo una referencia. La referencia apunta a una versión numerada (nunca latest).

Valor en bruto. Tú lo escribes, el producto lo usa y la interfaz no lo devuelve después. Para cambiarlo, usa Reemplazar credencial — no existe "ver la contraseña actual". Pero atención: no volver a mostrarlo no es lo mismo que no ser recuperable. El procesamiento necesita autenticarse en tu base de datos, así que el valor se descifra en cada ejecución.

Cambiar el valor aquí NO completa la rotación

El texto que la propia pantalla muestra en cada cambio: "Cambiar el valor en la bóveda NO completa la rotación. La credencial anterior sigue VÁLIDA en el origen (base, proveedor, IAM) hasta que se invalide ALLÁ. Solo marca la rotación como completada después de revocar la credencial antigua en el origen — hasta entonces, considérala expuesta."

Por eso la conexión tiene un estado de rotación propio, con tres valores:

EstadoQué significa
Sin rotaciónLa versión en uso es la original registrada.
Valor cambiado en la bóvedaExiste una versión nueva, validada y promovida — pero nadie confirmó que la credencial anterior se invalidó en el origen. La rotación no terminó.
Completada en el origenAlguien con acceso al origen confirmó la revocación allá. Solo aquí terminó la rotación.

El ciclo de cambio, en el orden en que ocurre. Cada paso solo se ejecuta si el anterior salió bien, y el reporte de la pantalla muestra cada uno:

  1. garantizar el secreto en la bóveda (idempotente);
  2. crear la versión nueva;
  3. validar — leer la versión de vuelta y verificar que los campos grabados son exactamente los esperados. Sin esto, promover sería un voto de confianza;
  4. promover — la referencia pasa a apuntar a la versión nueva;
  5. invalidar el caché de la conexión;
  6. retirar la versión anterior — deshabilitada, no destruida (ventana de rollback y peritaje).

Si la validación (paso 3) falla, no se promueve nada: la versión nueva se deshabilita y la credencial anterior sigue en uso. El paso 6 es el único de "mejor esfuerzo": fallar al retirar no deshace una credencial nueva que ya es válida — y el reporte dice que la versión antigua siguió habilitada en la bóveda.

Caché. El valor resuelto queda en la memoria del proceso, con validez de 5 minutos, y la clave del caché incluye tenant + conexión + secreto + versión. Consecuencias prácticas:

  • promover una versión nueva cambia la clave, así que el valor antiguo no se sirve por error;
  • la rotación y la revocación invalidan el caché al instante en el proceso que ejecutó la operación;
  • en otros procesos (el ejecutor de los pipelines corre en otro lugar), el techo es la validez de 5 minutos;
  • el secreto nunca va a un caché externo (caché compartido, disco) ni a una clave sin la versión.

Procesos en curso. La resolución ocurre al inicio de la ejecución. Una ejecución que ya empezó termina con el valor que resolvió; no se interrumpe por un cambio hecho a la mitad. La ejecución siguiente resuelve de nuevo y ya usa la credencial nueva — o falla, si la revocaste.

Revocación. Revocar marca la referencia como revocada y deshabilita la versión en la bóveda. Después de eso, toda resolución falla cerrada. Y, deliberadamente, la revocación no:

  • vuelve a la credencial cifrada en la base de datos (eso haría que la revocación pareciera aplicada sin estarlo);
  • reabre la versión anterior;
  • borra la versión (destruir es irreversible e impediría el peritaje).

Sin fallback silencioso. Cuando existe una referencia de bóveda, la bóveda es la única fuente. Bóveda no disponible o IAM denegado interrumpen la ejecución con un mensaje accionable y un código estable — nunca se resuelven hacia un secreto global, homónimo o de otro tenant. Una referencia de otro workspace o de otra conexión se rechaza antes de cualquier llamada de red.


Familia 3 — Secretos de firma y de cálculo#

Son nuestros, no de tu origen. El producto necesita el valor para firmar un token o calcular un código — y por eso están cifrados (AES-256-GCM), no hasheados.

Secreto de embed del panel

  • Guardado cifrado. El par es keyId (público, viaja en el token) + secret.
  • Rotar cambia los dos a la vez. Todo token ya emitido deja de valer al instante, porque la verificación compara el keyId del token con el keyId actual antes de mirar la firma.
  • Actualiza el secreto en tu servidor antes de rotar, o el panel incrustado se detiene junto con él.

Semilla del MFA (TOTP)

  • Guardada cifrada; el verificador recalcula los códigos de seis dígitos a partir de ella.
  • Limitación inventariada: el lector tolera una semilla heredada en texto plano (registros anteriores al cifrado). Si el descifrado falla, el valor guardado se usa tal cual. Por lo tanto, los registros antiguos pueden no estar cifrados todavía.
  • No existen códigos de recuperación de un solo uso en el producto hoy. Esta página ya los enumeró; no hay implementación correspondiente. Perder el dispositivo de MFA es un caso de soporte, no de autoservicio — consulta Soporte.

Clave de la cuenta de servicio del workspace

  • Se usa para acceder a los recursos en la nube del procesamiento; guardada cifrada o en la bóveda gestionada.
  • Rotar invalida la clave actual: las herramientas que usan la clave antigua se detienen. Descarga y distribuye la nueva antes de rotar.

Qué es cifrado y qué es verificador (tabla de verificación)#

Esta tabla describe la implementación actual, no una intención.

CredencialCómo se guardaPor qué
Contraseña de inicio de sesiónverificador (scrypt con sal)el servidor solo verifica lo que escribes. Definida en el registro; sin pantalla de cambio/restablecimiento hoy
Clave de API (datos)verificador (SHA-256) + prefijo visibletú presentas la clave; nosotros solo la verificamos. El prefijo identifica la clave en la lista
Service principalverificador (SHA-256) + prefijo + rol en el envelopeídem, con el rol viajando junto (fail-closed → viewer)
Credencial de tu fuentecifrada (AES-256-GCM) en la base de datos, o referencia a una versión en la bóveda de credencialesel procesamiento necesita autenticarse en tu base de datos/API. Un hash no autenticaría en ningún lado
Secreto de embedcifrado (AES-256-GCM)es la clave que firma los tokens del panel incrustado
Semilla del MFA (TOTP)cifrada (AES-256-GCM); la lectura tolera lo heredado en texto planoel verificador recalcula los códigos a partir de ella
Clave de la cuenta de serviciocifrada, o en bóveda gestionada cuando está disponiblese usa para acceder a los recursos en la nube del procesamiento

La clave de cifrado viene de una variable de entorno dedicada del servidor; en producción, su ausencia falla cerrada en lugar de caer en un valor de desarrollo.


Inventario rápido#

CredencialPrefijo/formaCrea/revocaAlcanceDónde se documenta
Clave de API (datos)ing_live_…solo el ownerworkspace (lee todos los marts publicados)Autenticación de la API
Service principalsp_live_…admin/ownerworkspace/org del SP, con rol en el envelopeSSO y SCIM
Secreto de embedkeyId público + secretacciones del workspaceun panel por token firmadoEmbed SDK
Credencial de fuentepor conector (contraseña/token/OAuth/clave)admin/owner (source.manage)una conexiónConectores
Inicio de sesión/MFAcontraseña (verificador) + semilla TOTP (cifrada)contraseña: solo en el registro (sin cambio por autoservicio) · MFA: cada persona activa el suyola propia identidadAutenticación y MFA

Lo que vale para todas#

Tres cosas — y solo tres — valen para todas las familias:

  • Alcance por workspace. Toda credencial resuelve solo el workspace/org que la emitió. Ninguna cruza clientes, y la verificación de dueño ocurre antes de cualquier lectura.
  • Menor privilegio. Un service principal viewer es denegado (403) en acciones por encima de su rol — consulta RBAC.
  • Nada de secretos en logs, errores, auditoría, exportaciones ni DAGs. Los valores no aparecen en mensajes de error ni en líneas de log; la definición del pipeline guarda la referencia de la conexión, nunca la credencial.

Cuándo rotar#

  • Sospecha de filtración (secreto en un log, URL compartida, captura de pantalla): trátalo como un incidente Crítico (Soporte). Para la familia 2, recuerda que el paso que elimina el riesgo es la revocación en el origen.
  • Salida de una persona con acceso al secreto.
  • Higiene periódica de las credenciales de integración.

Límites#

  • Clave de datos = nivel workspace (sin recorte por miembro). La clave por miembro con RLS está en el Roadmap.
  • La allowlist de orígenes del embed es global de la instancia hoy (por workspace = Roadmap) — consulta Embed.
  • Una única bóveda externa soportada — la del propio producto. Llevar las credenciales a una bóveda tuya es el adicional de Gestión de Credenciales, y no está incluido en el plan.
  • Sin códigos de recuperación de MFA (consulta la familia 3).
  • La rotación del refresh token de algunos conectores OAuth (Bling, Conta Azul, HubSpot) no se persiste — por eso la configuración de esos conectores se rechaza hoy. Consulta Conectores.

Errores comunes y cómo resolverlos#

SíntomaCausa probableQué hacer
La integración se detuvo con 401clave revocada/rotadaactualiza el integrador con la nueva clave
Todos los tokens de embed se detuvieronse rotó el secreto de embed (cambia keyId y secret)actualiza el secreto en tu servidor
El secreto "desapareció" después de crearlofamilia 1a: el valor en bruto de la clave emitida solo aparece 1 vezgenera otra clave y revoca la anterior
Cambié la contraseña y el origen todavía acepta la antiguacomportamiento esperado: cambiarla aquí no la revoca allárevócala en el origen y marca la rotación como completada
La ejecución falló con "credencial revocada"la referencia está revocada en la bóvedaregistra una credencial nueva; no hay vuelta al valor antiguo de la base de datos
La ejecución falló con "bóveda no disponible"bóveda de credenciales caída o acceso denegadofalla cerrada a propósito; nada se resolvió por aproximación
La ejecución en curso usó la credencial viejael secreto se resuelve al inicio de la ejecuciónesperado; la ejecución siguiente usa la nueva
La fuente falla después de un tiemporefresh token OAuth no persistidoreconecta la fuente; esos conectores están bloqueados hoy

Ejemplo#

A un script de Comércio Aurora (ficticia) se le filtró la clave ing_live_… en un log. Maria (owner) genera otra clave, actualiza el servidor de integración y revoca la antigua — toda llamada con la clave filtrada responde 401 al instante.

Si lo que se hubiera filtrado fuera la contraseña de la base de datos de origen, el procedimiento sería otro: cambiar el valor en la conexión resuelve qué contraseña usa ingestia.io, pero quien copió la contraseña antigua sigue entrando a la base de datos hasta que alguien la revoque en la base de datos. Solo entonces la rotación se marca como completada en el origen.

Resultado esperado#

  • Familia 1a: la clave nueva funciona y la antigua responde 401 de inmediato.
  • Familia 1b: una contraseña sustituida no abre una sesión nueva — pero la sesión que ya estaba abierta continúa hasta salir o vencer; no hay revocación de sesión.
  • Familia 2: la versión nueva es la que usa el producto; el origen solo está seguro después de la revocación allá, y la conexión registra ese estado.
  • Familia 3: el secreto nuevo firma/calcula, y lo que dependía del antiguo deja de valer al instante.
  • Ninguna credencial resuelve datos de otro workspace.

Relacionados#


Última revisión: 2026-09-17. Las familias, el ciclo de cambio, el caché, el comportamiento en ejecución y los límites de arriba se verificaron contra el código del producto, no contra un principio general.

Enlaces relacionados