Ir al contenido

Ejecutar un servidor Connect

Control Center Connect ejecuta los inicios de sesión de proveedores (GitHub, Google Calendar, Linear, Slack) para los servidores que no han registrado apps propias. Esta guía te muestra cómo ejecutar tu propio Connect, de modo que las apps de proveedor, sus secretos y la lista de servidores que pueden usarlas se queden contigo.

Lo que Connect puede y no puede ver está en la referencia de Connect. Léela primero si estás decidiendo si ejecutar uno.

  • Una dirección HTTPS pública para Connect, como https://connect.example.com, detrás de un proxy que termine TLS. http sin cifrar solo se acepta en loopback
  • Docker, o un cc_server que puedas reiniciar con variables de entorno adicionales
  • Permiso para registrar apps en cada proveedor que quieras servir
  • Los servidores que lo van a usar, con sus propietarios a mano: cada uno tiene un id de instalación que añades a la lista de permitidos de Connect

Elige la URL ahora y consérvala. CONNECT_PUBLIC_URL forma parte de todo lo que hace Connect: las firmas de las peticiones, las credenciales selladas, las URL de redirección de los proveedores y el id de instalación de cada servidor están ligados a ella. Cambiarla más adelante implica volver a registrar las redirecciones y que todo el mundo vuelva a iniciar sesión.

Registra solo los proveedores que quieras servir. Un proveedor cuyas variables estén incompletas se deja fuera de la configuración de Connect, y los servidores lo ven como no disponible. <base> es, a continuación, tu CONNECT_PUBLIC_URL.

Proveedor Qué registrar Qué conservar
App de GitHub Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup con Redirect on update activado. Deja desactivado Request user authorization (OAuth) during installation: si está activado, GitHub ignora la Setup URL. Mantén activado Expire user authorization tokens Id de la app, slug, id de cliente, secreto de cliente, una clave privada
Google Un cliente OAuth de tipo Aplicación web con el URI de redirección <base>/oauth/google/callback, y la Google Calendar API habilitada Id de cliente, secreto de cliente
Linear Una aplicación OAuth con las callback URLs <base>/oauth/linear/callback y <base>/oauth/linear_app/callback Solo el id de cliente
Slack Redirect URLs <base>/oauth/slack_oidc/callback y <base>/oauth/slack/callback. Event Subscriptions en <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Slash commands en <base>/v1/hooks/slack/commands. Rotación de tokens activada Id de la app, id de cliente, secreto de cliente, signing secret

Concede a la GitHub App estos permisos de repositorio: Metadata de lectura, Contents de lectura y escritura, Pull requests de lectura y escritura, Issues de lectura y escritura, y Checks, Actions y Commit statuses de lectura. Añade Members de la organización con lectura para las solicitudes de revisión a equipos. Los webhooks pueden quedarse desactivados: los servidores sondean.

Connect necesita la clave privada de la GitHub App (Generar una clave privada en los ajustes de la App). Firma las peticiones de la App que buscan la instalación que cubre un repositorio (o, si el repositorio no tiene ninguna, la instalación del propietario) y emite un token de instalación de un solo repositorio, y cada uno solo después de que el propio inicio de sesión de la persona que pregunta demostrara el acceso a ese repositorio.

Todos los servidores de tu Connect comparten el bot de la App. Puede leer, comentar, etiquetar y reaccionar como el bot en cualquiera de ellos. La revisión de pull requests como bot solo se permite a los servidores que enumeres en CONNECT_GITHUB_REVIEW_BOT_INSTALLS (sus id de instalación, separados por comas); cualquier otro servidor publica las revisiones con el token propio del revisor. El push nunca se hace como bot. Para que un servidor propio revise como bot, añade su id de instalación ahí y reinicia. Guarda el archivo de clave como un secreto, igual que la clave de sellado. Linear no necesita ningún secreto: Connect devuelve el código al servidor, que completa el intercambio por sí mismo.

Connect solo responde a los servidores de su lista de permitidos. En cada servidor, apúntalo a tu Connect y luego lee su id de instalación:

  1. Ve a Ajustes → Servidor → Inicio de sesión único, abre la tarjeta Control Center Connect y elige Usar un servidor Connect propio
  2. Introduce tu URL y guarda. La tarjeta muestra el ID de instalación del servidor

Desde un terminal en el host del servidor, lo mismo es:

Ventana de terminal
cc_server connect enable --url https://connect.example.com
cc_server connect status

status muestra el id de instalación. Indica install_blocked hasta que termines el paso 5, lo cual es normal.

Un id de instalación se deriva por cada dirección de Connect, así que el mismo servidor tiene un id distinto para cada Connect con el que habla. Solo cambia cuando su propietario rota la clave.

Connect cifra cada credencial que devuelve con una clave de sellado. Crea una y guárdala como archivo secreto:

Ventana de terminal
docker run --rm ghcr.io/samuelalev/cc-connect:latest \
cc-connect-config seal-key > seal_keys
chmod 600 seal_keys

Perder la clave de sellado cierra la sesión de todo el mundo: sin ella no se puede abrir ningún sello.

Cada versión publica ghcr.io/samuelalev/cc-connect con procedencia de compilación. En producción, fija una etiqueta de versión.

Ventana de terminal
docker run -d --name cc-connect -p 8790:8790 \
-e CONNECT_PUBLIC_URL=https://connect.example.com \
-e CONNECT_ALLOWED_INSTALLS=<install id>,<install id> \
-e CONNECT_SEAL_KEYS_FILE=/run/secrets/seal_keys \
-v "$PWD/seal_keys:/run/secrets/seal_keys:ro" \
-e CONNECT_GITHUB_APP_ID=123456 \
-e CONNECT_GITHUB_APP_SLUG=acme-control-center \
-e CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd \
-e CONNECT_GITHUB_CLIENT_SECRET_FILE=/run/secrets/github \
-v "$PWD/github_secret:/run/secrets/github:ro" \
-e CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github_key \
-v "$PWD/github_app_key.pem:/run/secrets/github_key:ro" \
-v cc-connect-data:/data \
ghcr.io/samuelalev/cc-connect:latest

Apunta tu proxy inverso al puerto 8790, y define CONNECT_TRUST_PROXY con el número de proxies que hay delante de Connect para que su límite por dirección vea la dirección de cada cliente. La imagen se ejecuta como un usuario sin privilegios, guarda su estado en el volumen /data y tiene una comprobación de estado integrada (cc-connect --healthcheck, que consulta /healthz: el proceso responde). /readyz además comprueba que sus almacenes de estado y de vinculaciones responden y que Redis, cuando se usa, sigue con maxmemory-policy noeviction; apunta ahí la comprobación de preparación de un orquestador.

La página de consentimiento de inicio de sesión responde con un envío de formulario que Connect acepta solo desde su propia página: Sec-Fetch-Site, cuando se envía, debe ser same-origin, y Origin, cuando se envía, debe ser el origen de CONNECT_PUBLIC_URL; un envío sin ninguno de los dos se rechaza. Así que el proxy debe reenviar ambas cabeceras sin cambios, y CONNECT_PUBLIC_URL debe ser la dirección que usan de verdad los navegadores de las personas. Si continuar desde esa página muestra siempre «Este enlace ha caducado», y el registro muestra oauth.done_refused con el motivo origin o no_origin, una de las dos cosas está mal.

Connect se niega a arrancar (código de salida 78) cuando su configuración es abierta, insegura o está a medias, e indica qué variable es incorrecta. Una lista de permitidos ausente, una dirección http fuera de loopback, una clave de sellado mal formada o tener definidas a la vez NAME y NAME_FILE lo detienen.

Punto de control: en cada servidor, la tarjeta de Connect dice Funciona, y Dónde se ejecuta cada inicio de sesión indica Connect para cada proveedor que registraste. cc_server connect status muestra Health: ok y los mismos carriles.

Un servidor puede alojar Connect él mismo en lugar de usar un contenedor aparte. El servicio montado es el mismo que ejecuta la imagen.

  1. Pon las variables CONNECT_* en el archivo .env del servidor, como en el paso 5. El servidor se niega a arrancar si un secreto de Connect, incluido CONNECT_SENTRY_DSN, está exportado en su entorno
  2. Añade CC_SERVER_CONNECT_HOST=on
  3. Reinicia el servidor. Su registro muestra embedded Connect at <url>
Ventana de terminal
CC_SERVER_CONNECT_HOST=on
CONNECT_ALLOWED_INSTALLS=<install id>
CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>
CONNECT_GITHUB_APP_ID=123456
CONNECT_GITHUB_APP_SLUG=acme-control-center
CONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcd
CONNECT_GITHUB_CLIENT_SECRET=<secret>
CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pem

Connect se sirve entonces en <server>/connect:

  • CONNECT_PUBLIC_URL toma por defecto el origen de la URL pública del servidor más /connect. Defínelo explícitamente detrás de un proxy. Su ruta tiene que ser exactamente /connect, y tiene que ser HTTPS salvo que sea loopback
  • Solo las variables CONNECT_* llegan al servicio montado, así que nunca toma prestadas las apps de proveedor propias del servidor
  • CONNECT_ALLOWED_INSTALLS sigue siendo obligatoria, también para el propio servidor que lo aloja
  • Un montaje mal configurado impide que el servidor arranque en lugar de servir un bróker abierto
  • El servidor de demostración nunca lo monta

Registra las redirecciones de los proveedores con https://<server>/connect y luego apunta los servidores (incluido el que lo aloja) a esa URL, como en el paso 3.

Cada ajuste es una variable de entorno. Cualquier secreto puede venir de un archivo montado: define NAME_FILE en lugar de NAME. Connect vuelve a leer el archivo como mucho cada 30 segundos y conserva el último valor válido. Los secretos marcados como doble también aceptan NAME_PREVIOUS (o NAME_PREVIOUS_FILE) durante una rotación.

Variable Predeterminado Significado
CONNECT_PUBLIC_URL obligatoria La URL pública canónica. HTTPS, o http solo en loopback. Una ruta indica un montaje. Sin query ni fragmento
CONNECT_ALLOWED_INSTALLS obligatoria Id de instalación separados por comas. * solo se acepta junto con CONNECT_SIGNED_CONFIG_FILE
CONNECT_DENY_INSTALLS Id de instalación rechazados aunque estén permitidos
CONNECT_GITHUB_ALLOWED_OWNERS Id numéricos de propietarios de GitHub. Si se define, solo se emiten tokens de repositorio para los repositorios que les pertenecen. No limita quién inicia sesión: una persona a la que este Connect le permite usarlo sigue recibiendo su propio token de usuario de la App. Para servir a una sola organización, mantén la App privada para ella
CONNECT_GITHUB_REVIEW_BOT_INSTALLS Id de instalación que pueden tener el bot de la App revisando pull requests. Vacía por defecto; * se rechaza, y cada id también debe estar permitido
CONNECT_HOST, CONNECT_PORT 0.0.0.0, 8790 Dirección y puerto de escucha
CONNECT_TRUST_PROXY 0 Saltos de proxy de confianza en X-Forwarded-For (de 0 a 8). Se usa solo para los límites por dirección, la pista de red de la página de inicio de sesión y la dirección registrada. Detrás de un proxy, 0 cuenta a cada cliente como el proxy, y el registro lo indica una vez
Variable Predeterminado Significado
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID La GitHub App
CONNECT_GITHUB_CLIENT_SECRET Secreto, doble
CONNECT_GITHUB_APP_PRIVATE_KEY Secreto. La clave privada de la App (PEM)
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET El cliente de Google. El secreto es doble
CONNECT_LINEAR_CLIENT_ID La aplicación de Linear. Sin secreto
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID La app de Slack
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET Secretos, dobles
CONNECT_KLIPY_APP_KEY Clave de búsqueda de GIF de Klipy. Secreto, doble
CONNECT_KLIPY_MODE proxy proxy mantiene la clave en Connect; key se la entrega a los servidores
CONNECT_<LANE>_SECRET_GENERATION 1 GitHub, Google y Slack: la generación que se registra en los sellos nuevos
CONNECT_<LANE>_MIN_SEAL_GENERATION 1 GitHub, Google y Slack: los sellos más antiguos tienen que volver a iniciar sesión
CONNECT_<LANE>_ACCEPTS_NEW true Todos los carriles: false detiene los inicios de sesión nuevos mientras los existentes se siguen renovando
Variable Predeterminado Significado
CONNECT_SEAL_BACKEND local local o gcp-kms
CONNECT_SEAL_KEYS Secreto, obligatorio para local. Entradas kid:key separadas por comas, la más reciente primero; las más antiguas siguen descifrando
CONNECT_KMS_KEY projects/…/locations/…/keyRings/…/cryptoKeys/…, obligatoria para gcp-kms
CONNECT_STATE memory memory para una instancia, redis para varias. Una tienda de memoria llena rechaza inicios de sesión y peticiones nuevas en lugar de olvidar una entrada activa
CONNECT_REDIS_URL Secreto. redis:// o rediss://. Redis 6.2 o posterior con maxmemory-policy noeviction, ambos comprobados al arrancar
CONNECT_REDIS_CA_FILE Paquete de CA para rediss://
CONNECT_BINDINGS file Dónde viven las vinculaciones de equipos de Slack: file o firestore
CONNECT_DATA_DIR data (/data en la imagen) Contiene bindings.json. Lo bloquea un Connect: un segundo Connect en el mismo directorio no arranca
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE base de datos (default) Para CONNECT_BINDINGS=firestore. Connect no arranca cuando Firestore no responde
Variable Predeterminado Significado
CONNECT_SIGNED_CONFIG_FILE Una configuración firmada sin conexión, servida tal cual. La usa el Connect alojado de Control Center
CONNECT_CONFIG_PUBLIC_KEYS Claves con las que se debe verificar la configuración firmada
CONNECT_CONFIG_EPOCH 1 La época de la configuración que genera un Connect autoalojado
CONNECT_LOG_HMAC_KEY aleatoria por proceso Secreto. Defínela para que las etiquetas que sustituyen a los id de instalación sean estables entre reinicios e instancias
CONNECT_SENTRY_DSN Secreto. Un DSN de Sentry https al que se informan las líneas de error: el tipo de error, los marcos de pila, la ruta y el id de la petición, nunca un mensaje, cuerpo ni cabecera
CONNECT_SENTRY_ENVIRONMENT self-hosted El entorno de Sentry
CONNECT_VERSION, CONNECT_IMAGE_DIGEST Las devuelve /v1/version
CONNECT_RATE_INSTALL_PER_MINUTE 600 Peticiones por instalación
CONNECT_RATE_IP_PER_MINUTE 300 Peticiones por dirección (una dirección IPv6 cuenta por /64)
CONNECT_RATE_GLOBAL_PER_SECOND 500 Peticiones para toda la instancia
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE 600 Entregas de eventos y comandos de Slack por dirección, contadas aparte de las demás peticiones
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND 100 Entregas de eventos y comandos de Slack para toda la instancia
CONNECT_RATE_SLACK_TEAM_PER_MINUTE 600 Eventos de Slack por equipo
CONNECT_RATE_KLIPY_PER_MINUTE 120 Búsquedas de GIF por instalación
CONNECT_RATE_KLIPY_IP_PER_MINUTE 240 Búsquedas de GIF por dirección, entre servidores
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES 60 Inicios de sesión empezados por dirección
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR 30 Tokens de GitHub emitidos por cuenta de GitHub en un servidor (inicios de sesión, renovaciones, tokens de repositorio)
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR 4 veces lo anterior (120) Lo mismo por cuenta de GitHub en todos los servidores
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR 600 Tokens de GitHub emitidos por dirección
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR 500 Nuevos inicios de sesión de GitHub para toda la app
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR 120 Tokens de bot por servidor
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR 240 Tokens de bot por cuenta de GitHub que pregunta, entre servidores
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR 3000 Tokens de bot para toda la app
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR 1500 Renovaciones y tokens de repositorio para toda la app. Los nuevos inicios de sesión tienen su propio límite, arriba
CONNECT_GITHUB_TOKEN_CAP_WARN 10 Tokens de repositorio vivos que puede tener una cuenta de GitHub antes de que Connect registre un aviso
CONNECT_RATE_RETIRE_IP_PER_HOUR 10 Ids de instalación retirados por dirección (por /48 en IPv6)

Una llamada que supera un límite recibe rate_limited. Los servidores reintentan más tarde y nunca cierran la sesión de nadie por ello.

Una instancia con CONNECT_STATE=memory basta para la mayoría de las organizaciones. Varias instancias detrás de una misma dirección necesitan CONNECT_STATE=redis y CONNECT_BINDINGS=firestore, para que un inicio de sesión empezado en una instancia pueda terminar en otra y todas vean las mismas vinculaciones de Slack y los mismos id de instalación retirados. Un CONNECT_DATA_DIR compartido no funciona: el primer Connect lo bloquea. Los límites de peticiones por instalación, por dirección y por instancia son por instancia; los límites de inicios de sesión, tokens de GitHub, tokens de bot, búsquedas de GIF por dirección, retiradas y equipos de Slack se comparten a través del almacén de estado.

No se cierra la sesión de nadie:

  1. Crea el secreto nuevo en el proveedor y conserva el antiguo
  2. Mueve el valor antiguo a NAME_PREVIOUS, pon el nuevo en NAME y aumenta CONNECT_<LANE>_SECRET_GENERATION. Los archivos montados se recogen en un plazo de 30 segundos
  3. Espera a que se renueven los inicios de sesión; después, elimina el secreto antiguo en el proveedor y quita NAME_PREVIOUS

Para rotar una clave de sellado, pon una entrada nueva de cc-connect-config seal-key la primera en CONNECT_SEAL_KEYS y conserva la entrada antigua hasta que se hayan renovado sus sellos.

Los servidores recuerdan los id de app y de cliente que anunció tu Connect la primera vez que lo usaron. Si sustituyes una app, la tarjeta de Connect de cada servidor muestra Las apps de Connect cambiaron, y los inicios de sesión a través de Connect se pausan hasta que su propietario pulsa Confiar en las nuevas apps. Avisa a los propietarios de los servidores antes del cambio, para que sepan que el aviso viene de ti.

Añade su id de instalación a CONNECT_DENY_INSTALLS y reinicia. Su propietario ve «Connect bloqueó el ID de instalación de este servidor. Contacta con quien gestiona tu servidor Connect.» y todos los inicios de sesión a través de Connect en ese servidor se detienen.

Un servidor también retira su propio id de instalación antiguo cuando su propietario rota la clave. Demuestra que el id es suyo con un único sello de credencial que este Connect creó para él, así que solo puede retirar un id un servidor que haya iniciado sesión a alguien. Connect conserva los ids retirados para siempre, así que la clave antigua y cada sello hecho con ella dejan de funcionar, y libera los espacios de trabajo de Slack vinculados al id antiguo. Los tokens ya entregados caducan por sí solos: en un plazo de 8 horas los de una persona, y 1 hora los de un bot. Connect guarda como máximo 100 000 ids retirados; a partir de ahí, una rotación se rechaza y el registro lo indica con nivel de error.

Un servidor dice que Connect lo ha bloqueado

Sección titulada «Un servidor dice que Connect lo ha bloqueado»

Su id de instalación no está en CONNECT_ALLOWED_INSTALLS, está en CONNECT_DENY_INSTALLS, o lo retiró una rotación de clave. El id cambia cuando su propietario rota la clave; pide el nuevo.

Todos los inicios de sesión de un proveedor fallan

Sección titulada «Todos los inicios de sesión de un proveedor fallan»

Puede que falte una de sus variables, así que Connect dejó fuera el carril. Revisa el registro de arranque y las tablas anteriores. GitHub necesita los cinco: id de la app, slug, id de cliente, secreto de cliente y clave privada; Google necesita tanto el id de cliente como el secreto.

Los inicios de sesión fallan con una discrepancia de redirección

Sección titulada «Los inicios de sesión fallan con una discrepancia de redirección»

La redirección registrada en el proveedor no coincide exactamente con CONNECT_PUBLIC_URL. Compara el esquema, el host, el puerto y, en un Connect montado, la ruta /connect.

Todo el mundo tuvo que volver a iniciar sesión

Sección titulada «Todo el mundo tuvo que volver a iniciar sesión»

La clave de sellado cambió o se perdió, un servidor rotó su clave o los datos de un servidor se restauraron en otra máquina. Una credencial sellada solo se abre para la instalación y el Connect que la crearon.