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.
Requisitos previos
Sección titulada «Requisitos previos»- Una dirección HTTPS pública para Connect, como
https://connect.example.com, detrás de un proxy que termine TLS.httpsin cifrar solo se acepta en loopback - Docker, o un
cc_serverque 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
Paso 1: Elegir la dirección
Sección titulada «Paso 1: Elegir la dirección»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.
Paso 2: Registrar las apps de proveedor
Sección titulada «Paso 2: Registrar las apps de proveedor»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 |
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.
Paso 3: Recopilar los id de instalación
Sección titulada «Paso 3: Recopilar los id de instalación»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:
- Ve a Ajustes → Servidor → Inicio de sesión único, abre la tarjeta Control Center Connect y elige Usar un servidor Connect propio
- 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:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus 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.
Paso 4: Crear una clave de sellado
Sección titulada «Paso 4: Crear una clave de sellado»Connect cifra cada credencial que devuelve con una clave de sellado. Crea una y guárdala como archivo secreto:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysPerder la clave de sellado cierra la sesión de todo el mundo: sin ella no se puede abrir ningún sello.
Paso 5: Iniciar el contenedor
Sección titulada «Paso 5: Iniciar el contenedor»Cada versión publica ghcr.io/samuelalev/cc-connect con procedencia de
compilación. En producción, fija una etiqueta de versión.
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:latestApunta 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.
Montar Connect dentro de cc_server
Sección titulada «Montar Connect dentro de cc_server»Un servidor puede alojar Connect él mismo en lugar de usar un contenedor aparte. El servicio montado es el mismo que ejecuta la imagen.
- Pon las variables
CONNECT_*en el archivo.envdel servidor, como en el paso 5. El servidor se niega a arrancar si un secreto de Connect, incluidoCONNECT_SENTRY_DSN, está exportado en su entorno - Añade
CC_SERVER_CONNECT_HOST=on - Reinicia el servidor. Su registro muestra
embedded Connect at <url>
CC_SERVER_CONNECT_HOST=onCONNECT_ALLOWED_INSTALLS=<install id>CONNECT_SEAL_KEYS=<output of cc-connect-config seal-key>CONNECT_GITHUB_APP_ID=123456CONNECT_GITHUB_APP_SLUG=acme-control-centerCONNECT_GITHUB_CLIENT_ID=Iv23li0123456789abcdCONNECT_GITHUB_CLIENT_SECRET=<secret>CONNECT_GITHUB_APP_PRIVATE_KEY_FILE=/etc/cc/github_app_key.pemConnect se sirve entonces en <server>/connect:
CONNECT_PUBLIC_URLtoma 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_INSTALLSsigue 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.
Referencia de configuración
Sección titulada «Referencia de configuración»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.
Dirección y acceso
Sección titulada «Dirección y acceso»| 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 |
Carriles de proveedor
Sección titulada «Carriles de proveedor»| 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 |
Sellos, estado y almacenamiento
Sección titulada «Sellos, estado y almacenamiento»| 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 |
Configuración, registros y límites
Sección titulada «Configuración, registros y límites»| 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.
Ejecutar más de una instancia
Sección titulada «Ejecutar más de una instancia»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.
Rotar un secreto de proveedor
Sección titulada «Rotar un secreto de proveedor»No se cierra la sesión de nadie:
- Crea el secreto nuevo en el proveedor y conserva el antiguo
- Mueve el valor antiguo a
NAME_PREVIOUS, pon el nuevo enNAMEy aumentaCONNECT_<LANE>_SECRET_GENERATION. Los archivos montados se recogen en un plazo de 30 segundos - 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.
Cambiar una app
Sección titulada «Cambiar una app»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.
Bloquear un servidor
Sección titulada «Bloquear un servidor»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.
Solución de problemas
Sección titulada «Solución de problemas»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.