Conectar sus servidores y canalizaciones a Uniqkey Secrets Manager con la CLI de uniqkey

Uniqkey Secrets Manager almacena los secretos que utilizan sus sistemas: contraseñas de bases de datos, tokens de API, cadenas de conexión y certificados. Los administradores los gestionan en el Portal de administración. Los servidores, scripts y canalizaciones de CI/CD los leen y escriben con la herramienta de línea de comandos uniqkey (CLI) y una clave de API. Este artículo explica cómo crear una clave de API, instalar y configurar la CLI, usarla de forma segura y resolver los problemas más habituales.

Algunos términos utilizados:

• Una clave de API es la credencial que utiliza una máquina. Tiene dos partes: un identificador de clave de acceso (comienza por UKEY) y una clave secreta (comienza por uksm_), que funciona como la contraseña de la clave.
• Un secreto es un valor que almacena en Secrets Manager.
• Una ruta identifica un secreto, como un archivo: /production/database/password. Un prefijo es el inicio de una ruta, como /production, e incluye todo lo que se encuentra debajo.

Quién puede usarlo

• Secrets Manager debe estar activo para su organización. Si no ve Secrets Manager en el menú del Portal de administración, póngase en contacto con el soporte de Uniqkey.
• Las claves de API las crea un administrador de la organización. Las cuentas de soporte y los empleados normales no pueden abrir Secrets Manager.
• Una clave de API pertenece a la organización, no al administrador que la creó. Sigue funcionando si dicho administrador se marcha; por eso, cuando se marche un administrador que gestionaba claves, sustitúyalas.
• La CLI funciona en Windows, macOS y Linux (x64 y ARM). Es un único programa que no requiere instalar nada más.
• La máquina necesita HTTPS saliente (puerto 443) a secrets-manager.production.uniqkey.eu y a static.uniqkey.eu para instalar y actualizar.

Mantenga seguras sus claves de API y sus secretos

• Los secretos se cifran y descifran en la máquina que ejecuta la CLI. Uniqkey solo almacena valores cifrados y no puede leerlos. Uniqkey puede ver la ruta de un secreto, cuándo cambió y qué clave de API accedió a él; por tanto, nunca incluya información secreta en una ruta ni en el nombre de una clave de API.
• Quien tenga una clave de API puede descifrar todo lo que la clave pueda leer. Las restricciones de ruta son permisos que Uniqkey comprueba en cada solicitud, no un cifrado separado: existe una clave de cifrado por organización. Dé a cada clave el ámbito y las rutas mínimos que necesite y establezca una fecha de caducidad.
• Nunca pegue una clave secreta, un archivo de credenciales, un archivo .env o un registro sin ocultar en un ticket, correo electrónico o chat. El soporte de Uniqkey nunca los necesita.
• Si es posible que una clave de API se haya filtrado: desactívela o elimínela inmediatamente en la página Claves de API, cambie en su origen cada secreto que la clave pudiera leer (la base de datos o el servicio de terceros), guarde los valores nuevos y compruebe en el registro de auditoría qué hizo la clave. Los valores anteriores permanecen en el historial de versiones de cada secreto.

Paso 1: Crear una clave de API

1. Inicie sesión en el Portal de administración como administrador.
2. Abra Secrets Manager en el menú de la izquierda. Si el portal le pide confirmarlo en el teléfono, apruebe la solicitud en la aplicación de Uniqkey en el plazo de un minuto. Secrets Manager requiere que Trusted Portal esté permitido para su organización.
3. Abra Claves de API en el menú de la izquierda y haga clic en Crear clave de API.
4. Complete los campos:
   • Nombre: indique qué utilizará la clave, por ejemplo ci-deploy-production. El nombre aparece en el registro de auditoría de todo lo que haga la clave.
   • Ámbito: Solo lectura, Lectura y escritura o Administrador (acceso completo). La mayoría de las canalizaciones necesitan Solo lectura.
   • Restricciones de ruta: los prefijos que puede utilizar la clave, por ejemplo /production. Déjelo vacío solo si la clave realmente necesita todos los secretos.
   • Fecha de caducidad (opcional): recomendada. La fecha más temprana que puede elegir es mañana. La clave funciona hasta el final de ese día en la zona horaria de su navegador.
5. Haga clic en Crear. El cuadro de diálogo Copie ahora su clave de API muestra el identificador de clave de acceso y la clave secreta.
6. Copie ambos en el lugar donde la máquina guarda sus credenciales. La clave secreta solo se muestra una vez. Marque He almacenado esta clave de API en un lugar seguro para cerrar el cuadro de diálogo. Si pierde la clave secreta, elimine la clave de API y cree otra.

Gestionar las claves de API posteriormente:

• La página Claves de API muestra todas las claves con su ámbito, rutas, estado, caducidad (Caduca) y Último uso. Desde ahí puede desactivar, volver a activar o eliminar una clave. Ambas acciones tienen efecto inmediato.
• Una organización puede tener como máximo 50 claves de API.
• Las lecturas, los cambios y las solicitudes rechazadas se registran en el registro de auditoría de la organización, bajo el tema Secrets Manager, con el nombre de la clave de API. Leer un prefijo completo con export o run se registra como una entrada que enumera las rutas.
• Para rotar una clave de API: cree una clave nueva, actualice la máquina, compruebe que Último uso de la clave antigua deja de cambiar y, después, elimine la clave antigua.

Paso 2: Instalar la CLI

Windows (PowerShell):

irm https://static.uniqkey.eu/cli/install.ps1 | iex

macOS y Linux:

curl -fsSL https://static.uniqkey.eu/cli/install.sh | sh

El instalador descarga la versión correcta para la máquina y la comprueba con una suma de comprobación publicada antes de instalarla. En Windows, el programa está firmado por Uniqkey y el instalador lo añade a PATH: abra un terminal nuevo después. En macOS y Linux se instala en /usr/local/bin o en ~/.local/bin cuando esa carpeta no permite escribir; si el instalador le indica que añada esa carpeta a PATH, hágalo.

Compruebe la instalación:

uniqkey version

Para instalar una versión concreta, algo recomendado en CI para que las compilaciones no cambien por sí solas:

$env:UNIQKEY_VERSION = '1.0.1'; irm https://static.uniqkey.eu/cli/install.ps1 | iex

curl -fsSL https://static.uniqkey.eu/cli/install.sh | UNIQKEY_VERSION=1.0.1 sh

Actualización: vuelva a ejecutar el instalador. Eliminación: elimine el programa uniqkey y la carpeta .uniqkey de su perfil de usuario; esto también elimina las credenciales guardadas. Si su política de seguridad no permite ejecutar un script de instalación descargado, póngase en contacto con el soporte de Uniqkey para obtener una descarga directa y su suma de comprobación.

Paso 3: Configurar la CLI

En una estación de trabajo o servidor, ejecute:

uniqkey configure

Solicita tres datos. Pulse Intro en URL de API para conservar la dirección de producción y, después, pegue el identificador de clave de acceso y la clave secreta. La clave secreta se muestra en pantalla mientras la pega, así que hágalo donde nadie pueda ver su pantalla. Las respuestas se guardan en un archivo de credenciales:

• Windows: %USERPROFILE%\.uniqkey\credentials
• macOS y Linux: ~/.uniqkey/credentials

El archivo contiene la clave secreta en texto sin formato. Guárdelo en el perfil de usuario de la cuenta que ejecuta la CLI, no lo copie entre máquinas y nunca lo añada al control de código fuente ni a una imagen de contenedor. Mantenga las claves de API de producción únicamente en las máquinas que las necesiten, no en los portátiles de los desarrolladores.

El archivo puede contener varios perfiles. Elija uno con --profile (o -p) colocado antes del comando, por ejemplo uniqkey -p build-server secret list, o establezca la variable de entorno UNIQKEY_PROFILE:

[default]
access_key_id = UKEYXXXXXXXXXXXXXXXX
secret_key = uksm_...

[build-server]
access_key_id = UKEYYYYYYYYYYYYYYYYY
secret_key = uksm_...

En las canalizaciones de CI/CD, no cree un archivo de credenciales. En su lugar, establezca estas variables de entorno desde el almacén de secretos de la canalización; tienen prioridad sobre el archivo:

La CLI utiliza la dirección de producción de forma predeterminada. Solo si Uniqkey le ha proporcionado una dirección diferente, establézcala en la solicitud URL de API de uniqkey configure o en la variable de entorno UNIQKEY_API_URL.

Información útil sobre el archivo de credenciales:

• Los nombres de las claves no distinguen entre mayúsculas y minúsculas, pero un nombre que la CLI no conozca genera un error, por lo que un error tipográfico nunca se ignora silenciosamente. Vuelva a crear el perfil con uniqkey configure si obtiene uno.
• Si crea el archivo en Windows PowerShell 5 con >, la CLI no podrá leerlo. Utilice uniqkey configure.
• uniqkey configure solo cambia el perfil que escribe y deja el resto del archivo tal como estaba.

Paso 4: Comprobar que funciona

uniqkey secret list

Si la clave de API puede leer secretos, verá sus rutas. Si no aparece nada, la clave todavía no tiene secretos dentro de sus rutas. Si obtiene un error, consulte «Solución de problemas».

Usar la CLI

Leer un secreto:

uniqkey secret get /production/database/password

Escribir un secreto. Canalice el valor en lugar de escribirlo como argumento para que no aparezca en el historial del shell:

# Windows (PowerShell): solicita el valor, que no aparece en el historial
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

# macOS y Linux
openssl rand -base64 32 | uniqkey secret set /production/api/session-key --overwrite

Notas:

• Se elimina un salto de línea al final de un valor canalizado, por lo que las canalizaciones de echo y PowerShell funcionan sin opciones especiales.
• Al sobrescribir se conservan la descripción, las etiquetas y el tipo, a menos que proporcione otros nuevos. Si alguien cambia el secreto mientras se ejecuta el comando, este se detiene con el código de salida 6 en lugar de sobrescribir el cambio. Vuelva a ejecutarlo.
• Las opciones como --profile y --output json van antes del comando (uniqkey --output json secret get /p); las opciones de un comando, como --overwrite, van después de la ruta.
• Las rutas distinguen entre mayúsculas y minúsculas.

Proporcionar secretos a un programa

uniqkey run es la forma más segura de proporcionar secretos a un programa: pasan directamente a su entorno y nunca se imprimen ni se escriben en el disco.

uniqkey run /production/api -- <your command>

• Cada secreto se convierte en una variable de entorno cuyo nombre se basa en la parte de la ruta que está debajo del prefijo, en mayúsculas y con los demás caracteres convertidos en _: bajo /production/api, /production/api/stripe-key se convierte en STRIPE_KEY.
• Si dos secretos generarían el mismo nombre o un nombre cambiaría la forma en que se inician los programas (como PATH), el comando se detiene antes de ejecutar nada. Cambie el nombre del secreto.
• Las variables UNIQKEY_ACCESS_KEY_ID y UNIQKEY_SECRET_KEY no se pasan al programa.
• run termina con el código de salida del programa que ejecutó.

Cargar secretos en un shell o archivo .env

uniqkey export imprime los secretos como declaraciones para un shell. El formato predeterminado es PowerShell en Windows y shell POSIX en macOS y Linux.

# Windows (PowerShell)
uniqkey export /production/api | Out-String | iex

# macOS y Linux (bash, zsh, sh); en Git Bash en Windows añada --format posix
eval "$(uniqkey export /production/api)"

# Archivo .env de Docker Compose (macOS y Linux)
(umask 077; uniqkey export /production/api --format dotenv > .env)

• export imprime los secretos en texto sin formato. Úselo solo cuando el resultado se consuma inmediatamente y prefiera run.
• Un archivo .env contiene en texto sin formato todos los secretos bajo el prefijo. Manténgalo fuera del control de código fuente (añádalo a .gitignore), haga que solo usted pueda leerlo y elimínelo cuando termine. En Windows, créelo desde cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), porque Windows PowerShell 5 escribe el resultado de > en un formato que Docker Compose no puede leer.
• El formato .env es para herramientas que leen archivos .env, como Docker Compose. No es un script de shell: nunca lo cargue con source ni con . .env, porque un valor que contenga comillas, $ o comillas invertidas podría ejecutar comandos.
• En PowerShell, los caracteres acentuados, los emojis y los saltos de línea llegan sin cambios, incluso en máquinas restringidas. Un secreto vacío elimina la variable en lugar de establecerla como vacía.
• Si el prefijo no coincide con ningún secreto, la CLI muestra una advertencia y no genera resultados; en PowerShell, el paso iex muestra entonces un error sobre una cadena vacía. Compruebe el prefijo y las rutas de la clave de API.

Usarlo en CI/CD

1. Almacene el identificador de clave de acceso y la clave secreta como variables secretas en la canalización y asígnelas a UNIQKEY_ACCESS_KEY_ID y UNIQKEY_SECRET_KEY.
2. Instale una versión fijada de la CLI con los comandos del paso 2.
3. Ejecute el paso mediante uniqkey run /production/api -- <your deploy command>.

La canalización oculta en sus registros las dos variables de clave de API, pero no conoce los valores que la CLI obtiene durante la ejecución. Prefiera run, que mantiene esos valores fuera del registro. Si imprime o usa export para mostrar valores, ocúltelos explícitamente en el sistema de CI y no utilice set -x, env ni registros de depuración alrededor de esos pasos. No ejecute uniqkey configure en una canalización.

Kubernetes

Para Kubernetes, la CLI incluye un pequeño proxy, uniqkey serve, que lee el External Secrets Operator. Descifra dentro del clúster, por lo que las aplicaciones reciben un secreto normal de Kubernetes. Utilice una clave de API de Solo lectura limitada a los prefijos que necesite el clúster, ejecute el proxy con un certificado TLS y use una NetworkPolicy para que solo el External Secrets Operator pueda acceder a él. Los secretos de Kubernetes resultantes se almacenan en texto sin formato en el clúster, a menos que habilite el cifrado en reposo. Póngase en contacto con el soporte de Uniqkey para obtener los manifiestos de implementación.

Códigos de salida

Cada comando termina con un código que un script puede comprobar. Los mensajes de error se envían a la salida de errores y comienzan por uniqkey:; los valores se envían a la salida normal. uniqkey run termina con el código del programa que ejecutó.

Límites

Cada comando de la CLI desbloquea primero el cifrado de la organización, lo que cuenta para el límite por IP. Todas las máquinas que acceden a Uniqkey mediante la misma dirección IP pública (por ejemplo, detrás de una misma NAT o proxy) la comparten; por tanto, una canalización que ejecute uniqkey secret get muchas veces por minuto puede alcanzar el límite aunque cada clave de API esté muy por debajo de su propio límite. Lea un prefijo completo con un solo run o export en lugar de realizar muchas llamadas a secret get.

Solución de problemas

Al ponerse en contacto con el soporte, incluya el nombre de su organización, el resultado de uniqkey version, el sistema operativo, el comando exacto sin ningún valor secreto, el mensaje de error completo, el código de salida (echo $? en bash, $LASTEXITCODE en PowerShell), el nombre de la clave de API (nunca la clave secreta) y la hora a la que ocurrió.