Referencia de Control Center Connect
Control Center Connect ejecuta los inicios de sesión de proveedores para los
servidores que no registraron apps propias. Un servidor usa el Connect
alojado de Control Center, un Connect que gestiona su organización
(Ejecutar un servidor Connect)
o ninguno. La elección está en Ajustes → Servidor → Inicio de sesión único →
Control Center Connect, en cc_server connect o en CC_CONNECT_URL. Un espacio de trabajo sigue esa elección salvo que un administrador elija otra cosa para ese espacio de trabajo en Ajustes → Espacio de trabajo → Integraciones (Elección por espacio de trabajo).
Carriles
Sección titulada «Carriles»Cada proveedor es un carril. Con Usar mis propias apps (o antes de que alguien elija), un carril funciona con la app propia del servidor cuando hay una configurada por completo; si no, no está disponible. Con Control Center o un Connect propio, Connect ejecuta cada carril que sirve: las apps propias del servidor se quedan guardadas pero no se usan, ni para los inicios de sesión, ni para la automatización del servidor, ni para el estado que informa el servidor. Un espacio de trabajo que ha elegido su propia opción ejecuta cada carril según esa opción en su lugar.
| Carril | Qué necesita una app propia | A través de Connect |
|---|---|---|
github |
Id de la app, clave privada, id de cliente y secreto de cliente | Las personas inician sesión en la GitHub App compartida |
google |
Id de cliente y secreto de cliente | Las personas conectan Google Calendar |
linear |
Id de cliente | Las personas inician sesión en Linear |
linear_app |
Id de cliente | Un administrador del espacio de trabajo conecta el actor de app de Linear |
slack |
La conexión de la app de Slack propia de un espacio de trabajo | Un administrador del espacio de trabajo conecta Slack a la app de Slack compartida |
klipy |
KLIPY_APP_KEY |
Búsqueda de GIF, a través del proxy de Connect |
Una app propia configurada solo en parte convierte su carril en un error, nunca en un paso silencioso a Connect. Un espacio de trabajo con Usar mis propias apps nunca pasa por la app del servidor ni por ningún Connect, para ningún proveedor. Cambiar la elección de Connect del servidor no desconecta a nadie de un espacio de trabajo que ha elegido la suya.
Qué ve Connect y qué no ve nunca
Sección titulada «Qué ve Connect y qué no ve nunca»| Connect ve | Connect nunca ve |
|---|---|
| El id de instalación del servidor y las firmas de las solicitudes | Código fuente, contenido de repositorios, diffs ni el texto de las pull requests |
| La cuenta del proveedor que inició sesión, durante el inicio de sesión | Tickets, transcripciones ni nada de la base de datos de un espacio de trabajo |
| A qué espacio de trabajo pertenece una credencial, como un id opaco dentro del sello | Los secretos de las apps propias del servidor: nunca salen del servidor |
| El repositorio para el que se emite un token de GitHub de un solo repositorio | Tokens de renovación en reposo: solo existen dentro de los sellos que guarda el servidor |
| El equipo de Slack vinculado al servidor | Secretos de Linear: el servidor intercambia por sí mismo el código de Linear |
| Los términos de búsqueda de GIF, cuando hace de proxy de Klipy | Contraseñas, claves de emparejamiento ni claves de proveedores de modelos |
| Referencias de eventos de Slack (equipo, canal, id de mensaje) y el texto de los comandos slash | El texto de los mensajes de Slack: Connect lo descarta al llegar y el servidor lee el mensaje directamente de Slack |
Connect guarda los inicios de sesión en curso, los nonces y las cachés durante 10 minutos como máximo, y los contadores de uso por hora durante dos horas como máximo. Un token de GitHub de un solo repositorio emitido como persona queda registrado, sellado al inicio de sesión que lo pidió, hasta que caduca (como máximo 8 horas), para que Connect pueda volver a entregarlo y revocarlo al desconectar. Sus únicos registros duraderos son las vinculaciones de Slack (a qué servidor está vinculado cada equipo de Slack) y los id de instalación retirados. Los errores llevan un código, nunca la respuesta del proveedor. Los registros solo guardan los id de instalación como hashes con clave, y un token de GitHub solo como el hashed_token que muestra el registro de auditoría de la organización de GitHub, para que un propietario de la organización pueda relacionar ambos.
| Modo | Ajuste | Comportamiento |
|---|---|---|
| Sin definir | Servidor nuevo | Ningún carril usa Connect. La incorporación inicial pide al propietario del servidor que elija |
hosted |
Usar las apps de Control Center | https://connect.usectrl.dev, con una configuración firmada sin conexión. Las apps propias del servidor no se usan |
custom |
Usar un servidor Connect propio | Un Connect en una URL HTTPS (http solo en loopback), en el que se confía en el primer uso. Las apps propias del servidor no se usan |
off |
Usar mis propias apps | Ningún carril usa Connect. Solo las apps propias inician la sesión de las personas |
CC_CONNECT_URL en el entorno o el .env del servidor bloquea la elección:
hosted, off o una URL de Connect. Ajustes muestra entonces el bloqueo y no
puede cambiarla.
Esta compilación no incluye ninguna clave de configuración alojada, así que el
modo alojado indica hosted_unprovisioned y no sirve ningún carril. Las apps
propias y un Connect propio funcionan.
El Connect alojado corre en un solo contenedor. Su clave de sellado y la clave privada de la GitHub App compartida son variables de entorno allí, no claves en una bóveda que solo firme o descifre, como recomienda GitHub para la clave privada de una App. Es una brecha conocida de la configuración actual.
Un servidor lee la configuración de Connect como mucho cada 10 minutos y espera como máximo 5 segundos por cada llamada. Cuando Connect no está accesible, se sigue usando la última configuración válida y Ajustes la marca como obsoleta.
Elección por espacio de trabajo
Sección titulada «Elección por espacio de trabajo»Ajustes → Espacio de trabajo → Integraciones → Control Center Connect sustituye la elección del servidor para un espacio de trabajo. Todos los miembros la ven y ven dónde se ejecuta cada inicio de sesión; solo un administrador del espacio de trabajo la cambia.
| Elección | Comportamiento |
|---|---|
| Igual que este servidor | Lo predeterminado. El espacio de trabajo funciona con lo que haya elegido el propietario del servidor; la opción lo indica |
| Usar las apps de Control Center | El Connect alojado de Control Center, sea cual sea el que use el servidor |
| Usar mis propias apps | Solo las apps propias del espacio de trabajo: su app de GitHub, su cliente de Google, su aplicación de Linear, su clave de Klipy y su app de Slack. Un proveedor sin una de ellas está desactivado aquí; una configurada solo en parte es un error de configuración |
| Usar un servidor Connect propio | Un Connect en una dirección HTTPS que indica el espacio de trabajo. Las direcciones de una red privada o local se rechazan |
- Cualquier elección distinta de Igual que este servidor guarda los inicios de sesión de GitHub y Linear de cada persona en un espacio propio del espacio de trabajo, así que nunca se mezclan con los de todo el servidor
- Al cambiar, se pide confirmación antes: todas las personas del espacio de trabajo vuelven a iniciar sesión en GitHub, Linear y Google Calendar a través de las nuevas apps
- La conexión de la app de Slack propia de un espacio de trabajo funciona con cualquier elección; Añadir Control Center a Slack sigue la elección
CC_CONNECT_URLtambién impide que los espacios de trabajo tengan un Connect propio: pueden seguir al servidor o usar sus propias apps- El Connect propio de un espacio de trabajo se confía en el primer uso solo para ese espacio de trabajo: Confiar en las nuevas apps allí nunca cambia lo que confían el servidor ni otro espacio de trabajo
Identidad de instalación
Sección titulada «Identidad de instalación»| Elemento | Qué es |
|---|---|
| Clave de instalación | Una semilla de 32 bytes en el archivo de secretos del servidor (connect_install_key), separada de las claves de emparejamiento de dispositivos |
| Clave por Connect | Una clave Ed25519 derivada de la semilla y de la dirección del Connect. Cada solicitud a Connect se firma con ella (RFC 9421) |
| ID de instalación | 26 caracteres derivados de esa clave pública. Lo muestran Ajustes y cc_server connect status |
El mismo servidor tiene un id de instalación distinto para cada dirección de Connect. El id solo cambia cuando se rota la clave.
Credenciales selladas
Sección titulada «Credenciales selladas»Un inicio de sesión a través de Connect devuelve un sello de credencial: un blob cifrado que solo puede abrir el Connect que lo creó. Está ligado al proveedor, la dirección de Connect, el id de instalación, el espacio de trabajo, la cuenta del proveedor, la app y la generación del secreto.
- El servidor guarda el sello y el id de instalación para el que se selló. Los tokens de acceso se quedan en memoria
- Para renovar, el servidor devuelve el sello y recibe un token de acceso nuevo y un sello nuevo
- Un sello cuyo id de instalación o dirección de Connect ya no coinciden se elimina la próxima vez que se lee, y esa persona vuelve a iniciar sesión. Esto ocurre tras una rotación de clave, un cambio a otro Connect o un directorio de datos restaurado en otro servidor
- Un sello que Connect no puede abrir se rechaza con
access_denied
Instalaciones de GitHub
Sección titulada «Instalaciones de GitHub»Cualquier servidor puede usar una instalación de la GitHub App compartida. Connect no guarda ningún registro de qué servidor puede usarla.
- Instalar la app de GitHub en Ajustes → Espacio de trabajo → Integraciones abre la página de instalación de la app en GitHub. El servidor construye el enlace a partir del nombre de la app en la configuración de Connect
- Un token de un solo repositorio necesita la app instalada en la cuenta propietaria del repositorio y el acceso de la persona que ha iniciado sesión a ese repositorio. Es el token propio de esa persona, limitado a su rol, nunca más
- Una organización limita Control Center en GitHub: quitando la instalación, reduciendo sus repositorios o quitando a la persona
- Para las llamadas que solo puede hacer la persona, como listar sus instalaciones, Connect entrega al servidor el token de usuario de App propio de la persona, no un token de un solo repositorio. Iniciar sesión en un servidor equivale a confiarle ese token a ese servidor
- Una organización que impone una lista de IP permitidas de GitHub no puede usar el Connect alojado, cuyas direcciones no son fijas. En su lugar registra su propia GitHub App, en sus servidores o en un Connect que ella gestione
- Desconectar revoca solo ese inicio de sesión: Connect gasta su token de renovación una vez y borra lo que esa operación devuelve, borra su token de usuario y los tokens de un solo repositorio que Connect emitió para él. Una copia de su sello guardada en cualquier lugar deja de funcionar. Los inicios de sesión de la persona en otros servidores y espacios de trabajo siguen funcionando. Para quitar Control Center de una cuenta de GitHub por completo, revócalo en GitHub en Settings → Applications → Authorized GitHub Apps → Revoke
El bot compartido
Sección titulada «El bot compartido»Los tokens emitidos como bot de la App (as: app) muestran el mismo bot en GitHub para cada servidor que usa el mismo Connect: GitHub no puede distinguir esos servidores.
- Todo servidor puede dejar que el bot lea y comente:
read,reviewycomment(comentarios, etiquetas, asignados y reacciones en issues y pull requests) - Revisar una pull request como el bot (
bot, que escribe en pull requests) solo se permite a los servidores que el operador de Connect lista enCONNECT_GITHUB_REVIEW_BOT_INSTALLS. A cada otro servidor se le respondeneeds_requestery publica la revisión con el token propio de la persona responsable, que GitHub limita a esa persona: la revisión aparece con su nombre. Esto cubre la publicación de revisiones con IA, los comentarios de revisión y las solicitudes de revisores - Hacer push, crear una rama y abrir una pull request (
write) nunca se emiten como el bot compartido. Siempre usan el propio inicio de sesión de quien lo pidió - Aprobar una pull request nunca es automático, con ningún token
- Un servidor o un espacio de trabajo con su propia GitHub App conserva el bot para todo esto, incluidas las revisiones
Lo que deben saber los propietarios y miembros de la organización
Sección titulada «Lo que deben saber los propietarios y miembros de la organización»- Un servidor en el que alguien inicia sesión tiene su token de usuario de App: hasta 8 horas por token, renovado hasta que la persona se desconecta. Puede actuar como esa persona en todo repositorio en el que está instalada la App compartida y al que ella puede llegar. Connect puede dejar a un servidor fuera para siempre (una instalación retirada o denegada), pero un token ya entregado sigue válido hasta que caduca
- Instalar la GitHub App compartida en una organización da consentimiento para cada servidor de Control Center en el que cualquier miembro inicie sesión, no para un solo servidor
- El bot es compartido, como se indicó arriba: una organización no puede saber en GitHub qué servidor actuó como bot
- Una organización que quiera su propio límite registra su propia GitHub App y ejecuta su propio Connect (Ejecutar un servidor Connect), o configura la App en sus propios servidores
Confianza en la configuración
Sección titulada «Confianza en la configuración»| Connect | Cómo confía el servidor en su configuración |
|---|---|
| Alojado | Verifica una firma Ed25519 con claves compiladas en la versión. Rechaza una época inferior a la más alta que haya visto (rollback) |
| Propio | Fija en el primer uso el id de la app y el id de cliente de GitHub, los id de cliente de Google y Linear, y los id de app y de cliente de Slack. Un cambio pausa los inicios de sesión a través de Connect (pins_changed) hasta que el propietario del servidor presiona Confiar en las nuevas apps |
Operaciones
Sección titulada «Operaciones»Los ajustes de Connect del servidor son exclusivos del propietario del servidor.
| Operación | Qué hace |
|---|---|
connect.status |
Modo, URL, bloqueo, id de instalación, estado, época de la configuración y origen de cada carril |
connect.configure |
Establece hosted, custom (con url) u off |
connect.test |
Vuelve a obtener la configuración e informa del estado |
connect.confirmPins |
Acepta los identificadores cambiados de un Connect propio |
connect.rotateKey |
Emite una nueva clave de instalación y un nuevo id de instalación (force lo reemplaza incluso cuando un Connect no pudo retirar la anterior); consulta Rotar la clave de instalación |
La elección de un espacio de trabajo tiene sus propias operaciones, cada una con el nombre del espacio de trabajo:
| Operación | Quién | Qué hace |
|---|---|---|
workspaceConnect.status |
Cualquier miembro | La elección, a qué se resuelve, el estado y la fuente de cada proveedor. El id de instalación y los anclajes pendientes, solo para administradores |
workspaceConnect.set |
Administrador del espacio de trabajo | Define inherit, hosted, custom (con url) u own |
workspaceConnect.test |
Administrador del espacio de trabajo | Vuelve a obtener la configuración de Connect del espacio de trabajo e informa de su estado |
workspaceConnect.confirmPins |
Administrador del espacio de trabajo | Acepta los identificadores cambiados del Connect propio del espacio de trabajo |
Los inicios de sesión en sí usan oauth.lanes, oauth.begin, oauth.status,
oauth.complete, oauth.connections y oauth.disconnect. La persona es
siempre quien llama con la sesión iniciada.
Inicio de sesión a través de Connect
Sección titulada «Inicio de sesión a través de Connect»- El servidor pide a Connect que inicie el carril y recibe la URL de autorización del proveedor, que comprueba antes de mostrarla. GitHub siempre muestra su selector de cuenta
- La persona aprueba en el navegador. El proveedor vuelve a Connect
- Connect muestra qué podrá hacer el servidor que inició el inicio de sesión en nombre de la persona, y durante cuánto tiempo. Connect no puede saber quién ejecuta ese servidor, así que la página pide a la persona que continúe solo si ella inició el inicio de sesión, y que la cierre si alguien le envió el enlace. Cuando el navegador está en otra red que aquella desde la que se inició el inicio de sesión, la página lo indica: es normal en un servidor alojado o en otro dispositivo, y también es lo que parece el phishing. Cancelar termina el inicio de sesión: el código del proveedor nunca se usa. Cada página responde una sola vez; una respuesta que no venga de la página que Connect acaba de mostrar se rechaza
- Después de Continuar, Connect muestra un código de 8 caracteres y un enlace
control-center://oauth-done. Quien obtenga el código obtiene el acceso recién aprobado, así que solo debe ir allí donde se inició el inicio de sesión - La persona escribe el código en la aplicación, o sigue el enlace. El servidor reclama el inicio de sesión con el código y su propia prueba de la solicitud
Un inicio de sesión caduca a los 10 minutos. Cinco códigos erróneos lo terminan.
Un enlace que esta aplicación no inició se rechaza con
Inicio de sesión no iniciado aquí. Connect limita cuántos inicios de sesión puede iniciar una dirección de red, y con qué frecuencia se emiten tokens de GitHub por persona y servidor, por persona entre servidores, por dirección y para toda la app. Los inicios de sesión nuevos tienen un presupuesto propio, así que nunca retienen las renovaciones que otras personas necesitan. Al superar un límite, una llamada se rechaza con rate_limited, y el servidor vuelve a intentarlo más tarde sin cerrar la sesión de nadie. Un inicio de sesión que supera el límite de la persona se deshace en GitHub y se rechaza.
Rotar la clave de instalación
Sección titulada «Rotar la clave de instalación»Solo el propietario del servidor puede rotar la clave, con Rotar la clave en la tarjeta Control Center Connect de Ajustes → Servidor → Inicio de sesión único. No hay ningún comando para hacerlo. Al rotar:
- Cierra la sesión de todo el mundo en todos los carriles que pasan por Connect. Para cada servidor Connect con el que se usó la clave anterior, el servidor revoca los inicios de sesión de GitHub y Slack que guarda desde allí (un inicio de sesión de Google no tiene nada que revocar y caduca)
- Retira el id de instalación anterior en cada uno de esos servidores Connect, firmado con la clave anterior y probado con un sello de credencial que el servidor guarda de ese Connect. A partir de entonces, Connect rechaza toda solicitud hecha con la clave anterior, así que un sello o una copia de la clave anterior tomada de este servidor no sirve de nada, y los espacios de trabajo de Slack vinculados al id anterior quedan liberados para que puedan volver a conectarse. Los tokens ya entregados siguen válidos hasta que caducan (una hora para un token de bot, ocho horas para el de una persona). Un servidor Connect del que este servidor no guarda ningún sello no tiene nada que retirar y se omite
- Después da al servidor una nueva clave de instalación y un nuevo id de instalación
- Si un servidor Connect no puede alcanzarse, o se niega a retirar el id anterior, se detiene antes de cambiar las claves y muestra Connect no pudo retirar la clave anterior. Rotar de todos modos cambia las claves de todos modos; el id de instalación anterior entonces sigue siendo utilizable en ese Connect hasta que caduquen sus tokens, como máximo ocho horas para GitHub
- No afecta a los inicios de sesión con las apps propias del servidor
- Requiere agregar el nuevo id de instalación a la lista de permitidos de un Connect propio
Códigos de estado
Sección titulada «Códigos de estado»| Código | Significado |
|---|---|
hosted_unprovisioned |
Esta compilación no tiene clave de configuración alojada |
signature |
La configuración alojada no superó la comprobación de su firma |
rollback |
Connect sirvió una configuración más antigua que la que el servidor ya había visto |
unreachable |
El servidor no puede llegar a Connect |
install_blocked |
Connect no permite este id de instalación, o ya fue retirado |
pins_changed |
Un Connect propio anunció identificadores de app distintos |
protocol |
Connect respondió de una forma que este servidor no entiende |