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 registraron 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 agregas 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 solicitudes, 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 |
|---|---|---|
| GitHub App | 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. Agrega 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 App de GitHub (Generar una clave privada en los ajustes de la App). Firma las solicitudes de la App que encuentran 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, cada uno solo después de que el inicio de sesión propio de la persona demostró el acceso a ese repositorio.
Cada servidor de tu Connect comparte el bot de la App. Puede leer, comentar, etiquetar y reaccionar como el bot en cualquiera de ellos. Revisar pull requests como el bot solo se permite a los servidores que listes en CONNECT_GITHUB_REVIEW_BOT_INSTALLS (sus ids de instalación, separados por comas); cada otro servidor publica revisiones con el token propio del revisor. Nunca se hace push como el bot. Para que un servidor propio revise como el bot, agrega su id de instalación ahí y reinicia. Guarda la clave como un secreto, igual que la clave de sellado. Linear no necesita 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 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 a él 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. Por eso el proxy debe pasar ambos encabezados sin cambios, y CONNECT_PUBLIC_URL debe ser la dirección que usan realmente los navegadores de las personas. Si continuar en esa página muestra siempre «Este enlace ha caducado», y el registro muestra oauth.done_refused con motivo origin o no_origin, una de esas 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 cuando un secreto de Connect, incluidoCONNECT_SENTRY_DSN, está exportado en su entorno - Agrega
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 autorizada a usar este Connect 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 |
Ids de instalación que pueden hacer que el bot de la App revise 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). Solo se usa para los límites por dirección, la sugerencia de red de la página de inicio de sesión y la dirección registrada. Detrás de un proxy, 0 cuenta 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 solicitudes nuevos 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 solo Connect: un segundo 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 https de Sentry al que se informan las líneas de error: el tipo de error, los marcos de pila, la ruta y el id de solicitud, nunca un mensaje, cuerpo ni encabezado | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
El entorno de Sentry |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
Las devuelve /v1/version |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
Solicitudes por instalación |
CONNECT_RATE_IP_PER_MINUTE |
300 |
Solicitudes por dirección (una dirección IPv6 cuenta por /64) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
Solicitudes 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 otras solicitudes |
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 iniciados 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 y tokens de repositorio) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
4 × 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, en todos los 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 una cuenta de GitHub puede tener antes de que Connect registre una advertencia |
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 la respuesta rate_limited. Los servidores reintentan más tarde y nunca cierran la sesión de nadie por eso.
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 las instancias vean las mismas vinculaciones de Slack y los mismos ids de instalación retirados. Un CONNECT_DATA_DIR compartido no funciona: el primer Connect lo bloquea. Los límites por instalación, por dirección y de solicitudes de la 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, retiros 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 presiona 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»Agrega 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 sello de credencial que este Connect creó para él, así que solo un servidor que haya iniciado sesión a alguien puede retirar un id. Connect conserva los ids retirados para siempre, así que la clave antigua y cada sello hecho con ella dejan de funcionar, y libera los equipos de Slack vinculados al id antiguo. Los tokens ya entregados caducan por sí solos: en 8 horas como máximo los de una persona, y en 1 hora los de un bot. Connect guarda como máximo 100 000 ids retirados; más allá de eso, una rotación se rechaza y el registro lo indica a nivel de error.
Solución de problemas
Sección titulada «Solución de problemas»Un servidor dice que Connect lo bloqueó
Sección titulada «Un servidor dice que Connect lo bloqueó»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 con un proveedor fallan
Sección titulada «Todos los inicios de sesión con un proveedor fallan»Puede faltar 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.