Pular para o conteúdo

Referência do Control Center Connect

O Control Center Connect executa os logins de provedores para os servidores que não registraram apps próprios. Um servidor usa o Connect hospedado do Control Center, um Connect que a organização dele executa (Executar um servidor Connect) ou nenhum. A escolha fica em Configurações → Servidor → Início de sessão único → Control Center Connect, em cc_server connect ou em CC_CONNECT_URL. Um espaço de trabalho segue essa escolha, a menos que um administrador escolha outra coisa para ele em Configurações → Espaço de trabalho → Integrações (Escolha por espaço de trabalho).

Cada provedor é uma faixa. Em Usar meus próprios apps (ou antes de alguém escolher), uma faixa roda no app próprio do servidor quando há um configurado por completo; caso contrário, fica indisponível. Com os apps do Control Center ou um Connect próprio, o Connect executa cada faixa que atende: os apps próprios do servidor continuam salvos, mas não são usados para logins, para a automação do servidor nem para o status que o servidor informa. Um espaço de trabalho que fez a própria escolha executa cada faixa por essa escolha.

Faixa O que um app próprio precisa Pelo Connect
github Id do app, chave privada, id de cliente e segredo de cliente As pessoas entram no GitHub App compartilhado
google Id de cliente e segredo de cliente As pessoas conectam o Google Calendar
linear Id de cliente As pessoas entram no Linear
linear_app Id de cliente Um administrador do espaço de trabalho conecta o ator de app do Linear
slack A conexão do próprio app do Slack de um espaço de trabalho Um administrador do espaço de trabalho conecta o Slack ao app do Slack compartilhado
klipy KLIPY_APP_KEY Busca de GIFs, pelo proxy do Connect

Um app próprio configurado só em parte transforma a faixa dele em um erro, nunca em uma passagem silenciosa para o Connect. Um espaço de trabalho em Usar meus próprios apps nunca passa pelos apps do servidor nem por nenhum Connect, em nenhum provedor. Trocar a escolha do Connect do servidor não desconecta ninguém de um espaço de trabalho que fez a própria escolha.

O Connect vê O Connect nunca vê
O id de instalação do servidor e as assinaturas das requisições Código-fonte, conteúdo de repositórios, diffs nem o texto das pull requests
A conta do provedor que entrou, durante o login Tickets, transcrições nem nada do banco de dados de um espaço de trabalho
A qual espaço de trabalho uma credencial pertence, como um id opaco dentro do selo Os segredos próprios de app do servidor: eles nunca saem do servidor
O repositório para o qual um token do GitHub de um único repositório é emitido Tokens de atualização em repouso: eles só existem dentro dos selos que o servidor guarda
A equipe do Slack vinculada ao servidor Segredos do Linear: o servidor troca o código do Linear sozinho
Os termos de busca de GIFs, quando faz proxy do Klipy Senhas, chaves de emparelhamento nem chaves de provedores de modelos
Referências de eventos do Slack (equipe, canal, id da mensagem) e o texto dos comandos slash O texto das mensagens do Slack: o Connect o descarta na chegada e o servidor lê a mensagem diretamente do Slack

O Connect guarda logins em andamento, nonces e caches por no máximo 10 minutos, e contadores de uso por hora por no máximo duas horas. Um token do GitHub de um único repositório emitido para uma pessoa continua registrado, selado ao login que o pediu, até expirar (no máximo 8 horas), para que o Connect possa entregá-lo de novo e revogá-lo na desconexão. Os únicos registros duradouros dele são os vínculos do Slack (a qual servidor cada equipe do Slack está vinculada) e os ids de instalação aposentados. Os erros trazem um código, nunca a resposta do provedor. Os logs registram os ids de instalação apenas como hashes com chave, e um token do GitHub apenas como o hashed_token que o log de auditoria da organização do GitHub mostra para ele, para que um proprietário da organização consiga relacionar os dois.

Modo Configuração Comportamento
Não definido Servidor novo Nenhuma faixa usa o Connect. O onboarding pede ao proprietário do servidor que escolha
hosted Usar os apps do Control Center https://connect.usectrl.dev, com uma configuração assinada offline. Os apps próprios do servidor não são usados
custom Usar um servidor Connect próprio Um Connect em uma URL HTTPS (http só em loopback), confiável a partir do primeiro uso. Os apps próprios do servidor não são usados
off Usar meus próprios apps Nenhuma faixa usa o Connect. Só os apps próprios fazem o login das pessoas

CC_CONNECT_URL no ambiente ou no .env do servidor bloqueia a escolha: hosted, off ou uma URL do Connect. Configurações mostra então o bloqueio e não consegue alterá-la.

Esta build não inclui nenhuma chave de configuração hospedada, então o modo hospedado indica hosted_unprovisioned e não atende nenhuma faixa. Os apps próprios e um Connect próprio funcionam.

O Connect hospedado roda em um único contêiner. A chave de selagem dele e a chave privada do GitHub App compartilhado são variáveis de ambiente ali, não chaves em um cofre que apenas assina ou decifra, como o GitHub recomenda para a chave privada de um App. Essa é uma lacuna conhecida da configuração atual.

Um servidor lê a configuração do Connect no máximo a cada 10 minutos e espera no máximo 5 segundos por cada chamada. Quando o Connect está inacessível, a última configuração válida continua em uso e Configurações a marca como desatualizada.

Configurações → Espaço de trabalho → Integrações → Control Center Connect substitui a escolha do servidor para um espaço de trabalho. Todo membro vê a escolha e onde cada login é executado; só um administrador do espaço de trabalho a altera.

Escolha Comportamento
Igual a este servidor O padrão. O espaço de trabalho segue o que o proprietário do servidor escolheu; a opção mostra qual é
Usar os apps do Control Center O Connect hospedado do Control Center, qualquer que seja o que o servidor usa
Usar meus próprios apps Somente os apps próprios do espaço de trabalho: o GitHub App, o cliente do Google, o aplicativo do Linear, a chave do Klipy e o app do Slack. Um provedor sem um deles fica desligado aqui; um parcialmente configurado é um erro de configuração
Usar um servidor Connect próprio Um Connect em um endereço HTTPS que o espaço de trabalho informa. Endereços de rede privada ou local são recusados
  • Qualquer escolha diferente de Igual a este servidor mantém os logins no GitHub e no Linear de cada pessoa em um espaço próprio do espaço de trabalho, para que nunca se misturem com os logins do servidor como um todo
  • Trocar pede confirmação primeiro: todo mundo no espaço de trabalho entra de novo no GitHub, no Linear e no Google Calendar pelos novos apps
  • A conexão do próprio app do Slack de um espaço de trabalho funciona em todas as escolhas; Adicionar o Control Center ao Slack segue a escolha
  • CC_CONNECT_URL também impede que os espaços de trabalho tenham um Connect próprio: eles podem seguir o servidor ou usar os próprios apps
  • O Connect próprio de um espaço de trabalho é confiado no primeiro uso, somente para esse espaço de trabalho: Confiar nos novos apps ali nunca altera o que o servidor ou outro espaço de trabalho confia
Item O que é
Chave de instalação Uma semente de 32 bytes no arquivo de segredos do servidor (connect_install_key), separada das chaves de emparelhamento de dispositivos
Chave por Connect Uma chave Ed25519 derivada da semente e do endereço do Connect. Toda requisição ao Connect é assinada com ela (RFC 9421)
ID de instalação 26 caracteres derivados dessa chave pública. Mostrado em Configurações e por cc_server connect status

O mesmo servidor tem um id de instalação diferente para cada endereço do Connect. O id só muda quando a chave é trocada.

Um login pelo Connect devolve um selo de credencial: um blob cifrado que só o Connect que o criou consegue abrir. Ele fica vinculado ao provedor, ao endereço do Connect, ao id de instalação, ao espaço de trabalho, à conta do provedor, ao app e à geração do segredo.

  • O servidor guarda o selo e o id de instalação para o qual ele foi selado. Os tokens de acesso ficam na memória
  • Para renovar, o servidor envia o selo de volta e recebe um novo token de acesso e um novo selo
  • Um selo cujo id de instalação ou endereço do Connect não corresponde mais é excluído na próxima vez em que é lido, e essa pessoa entra de novo. Isso acontece depois de uma troca de chave, de uma mudança para outro Connect ou de um diretório de dados restaurado em outro servidor
  • Um selo que o Connect não consegue abrir é recusado com access_denied

A instalação do GitHub App compartilhado pode ser usada a partir de qualquer servidor. O Connect não guarda registro de quais servidores podem usá-la.

  • Instalar o app do GitHub em Configurações → Espaço de trabalho → Integrações abre a página de instalação do app no GitHub. O servidor monta o link com o nome do app na configuração do Connect
  • Um token de um único repositório exige que o app esteja instalado no dono do repositório e que a pessoa conectada tenha acesso a esse repositório. É um token da própria pessoa, limitado ao papel dela, nunca mais que isso
  • Uma organização limita o Control Center no GitHub: removendo a instalação, reduzindo os repositórios ou removendo a pessoa
  • Para chamadas que só a pessoa pode fazer, como listar as instalações dela, o Connect entrega ao servidor o token de usuário do App da própria pessoa, não um token de um único repositório. Entrar em um servidor é confiar a ele esse token
  • Uma organização que impõe uma lista de permissões de IP do GitHub não consegue usar o Connect hospedado, cujos endereços não são fixos. Ela registra um GitHub App próprio, em seus servidores ou em um Connect que executa
  • Desconectar revoga somente aquele login: o Connect gasta o token de atualização uma vez e apaga o que ele devolve, apaga o token de usuário dela e os tokens de um único repositório que o Connect emitiu para ela. Uma cópia do selo guardada em qualquer lugar deixa de funcionar. Os logins da pessoa em outros servidores e espaços de trabalho continuam funcionando. Para remover o Control Center de uma conta do GitHub por completo, revogue-o no GitHub em Settings → Applications → Authorized GitHub Apps → Revoke

Tokens emitidos como bot do App (as: app) mostram o mesmo bot no GitHub para todo servidor que usa o mesmo Connect: o GitHub não consegue distinguir esses servidores.

  • Todo servidor pode fazer o bot ler e comentar: read, review e comment (comentários, rótulos, responsáveis e reações em issues e pull requests)
  • Revisar uma pull request como o bot (bot, que escreve em pull requests) é permitido somente para servidores que o operador do Connect lista em CONNECT_GITHUB_REVIEW_BOT_INSTALLS. Todo outro servidor recebe needs_requester e publica a revisão com o token da própria pessoa responsável, que o GitHub limita a ela: a revisão aparece com o nome dela. Isso cobre a publicação de revisões de IA, os comentários de revisão e os pedidos de revisores
  • Fazer push, criar um branch e abrir uma pull request (write) nunca são emitidos como o bot compartilhado. Sempre usam o próprio login de quem pediu
  • Aprovar uma pull request nunca é automatizado, em nenhum token
  • Um servidor ou espaço de trabalho com o próprio GitHub App mantém o bot para tudo isso, inclusive as revisões

O que proprietários e membros da organização devem saber

Seção intitulada “O que proprietários e membros da organização devem saber”
  • Um servidor em que alguém entra guarda o token de usuário do App dessa pessoa: até 8 horas por token, renovado até a pessoa desconectar. Ele pode agir como ela em todo repositório em que o App compartilhado está instalado e que ela consegue alcançar. O Connect pode cortar um servidor de vez (uma instalação aposentada ou negada), mas um token já entregue continua válido até expirar
  • Instalar o GitHub App compartilhado em uma organização dá consentimento para cada servidor do Control Center em que um membro entra, não para um único servidor
  • O bot é compartilhado, como acima: uma organização não consegue saber no GitHub qual servidor agiu como o bot
  • Uma organização que quer uma fronteira própria registra um GitHub App próprio e executa o próprio Connect (Executar um servidor Connect), ou configura o App nos próprios servidores
Connect Como o servidor confia na configuração dele
Hospedado Verifica uma assinatura Ed25519 com chaves compiladas na build. Recusa uma época menor que a maior que já viu (rollback)
Próprio Fixa no primeiro uso o id do app e o id de cliente do GitHub, os ids de cliente do Google e do Linear e os ids de app e de cliente do Slack. Uma mudança pausa os logins pelo Connect (pins_changed) até o proprietário do servidor clicar em Confiar nos novos apps

As configurações do Connect do servidor são exclusivas do proprietário do servidor.

Operação O que faz
connect.status Modo, URL, bloqueio, id de instalação, estado, época da configuração e origem de cada faixa
connect.configure Define hosted, custom (com url) ou off
connect.test Busca a configuração de novo e informa o estado
connect.confirmPins Aceita os identificadores alterados de um Connect próprio
connect.rotateKey Emite uma nova chave de instalação e um novo id de instalação (force a substitui mesmo quando um Connect não conseguiu aposentar a antiga); veja Trocar a chave de instalação

A escolha própria de um espaço de trabalho tem as próprias operações, cada uma informando o espaço de trabalho:

Operação Quem O que faz
workspaceConnect.status Qualquer membro A escolha, no que ela resolve, a saúde e a origem de cada provedor. Id de instalação e pins pendentes só para administradores
workspaceConnect.set Administrador do espaço de trabalho Define inherit, hosted, custom (com url) ou own
workspaceConnect.test Administrador do espaço de trabalho Busca de novo a configuração do Connect do espaço de trabalho e informa a saúde
workspaceConnect.confirmPins Administrador do espaço de trabalho Aceita os identificadores alterados do Connect próprio do espaço de trabalho

Os logins em si usam oauth.lanes, oauth.begin, oauth.status, oauth.complete, oauth.connections e oauth.disconnect. A pessoa é sempre quem faz a chamada com o login feito.

  1. O servidor pede ao Connect que inicie a faixa e recebe a URL de autorização do provedor, que ele verifica antes de mostrá-la. O GitHub sempre mostra o seletor de contas
  2. A pessoa aprova no navegador. O provedor volta para o Connect
  3. O Connect mostra o que o servidor que iniciou o login poderá fazer como a pessoa, e por quanto tempo. O Connect não consegue saber quem executa esse servidor, então a página pede que a pessoa continue somente se ela mesma iniciou o login, e que a feche se alguém lhe enviou o link. Quando o navegador está em outra rede que aquela em que o login foi iniciado, a página informa isso: é normal para um servidor hospedado ou outro dispositivo, e é também o que um phishing parece. Cancelar encerra o login: o código do provedor nunca é usado. Cada página responde uma única vez; uma resposta que não veio da página que o Connect acabou de mostrar é recusada
  4. Depois de Continuar, o Connect mostra um código de 8 caracteres e um link control-center://oauth-done. Quem obtiver o código ganha o acesso que acabou de ser aprovado, então ele só deve ser levado para onde o login foi iniciado
  5. A pessoa digita o código no app, ou segue o link. O servidor reivindica o login com o código e a própria prova da requisição

Um login expira depois de 10 minutos. Cinco códigos errados o encerram. Um link que este app não iniciou é recusado com Login não iniciado aqui. O Connect limita quantos logins um endereço de rede pode iniciar, e com que frequência tokens do GitHub são emitidos por pessoa e servidor, por pessoa entre servidores, por endereço e para o app inteiro. Novos logins têm um orçamento próprio, então nunca travam as renovações de que outras pessoas precisam. Ao passar de um limite, uma chamada é recusada com rate_limited, e o servidor tenta de novo depois, sem desconectar ninguém. Um login além do limite da pessoa é desfeito no GitHub e recusado.

Somente o proprietário do servidor pode trocar a chave, com Trocar a chave no cartão Control Center Connect em Configurações → Servidor → Início de sessão único. Não há comando para isso. Ao trocar a chave:

  • Desconecta todo mundo de todas as faixas que passam pelo Connect. Para cada servidor Connect com o qual a chave antiga foi usada, o servidor revoga os logins no GitHub e no Slack que mantém a partir dele (um login no Google não tem nada a revogar e simplesmente expira)
  • Aposenta o id de instalação antigo em cada um desses servidores Connect, assinado com a chave antiga e comprovado com um selo de credencial que o servidor guarda desse Connect. A partir daí, o Connect recusa toda requisição feita com a chave antiga, então um selo ou uma cópia da chave antiga tirada deste servidor fica inútil, e os espaços de trabalho do Slack vinculados ao id antigo são liberados para se conectarem de novo. Tokens já entregues continuam válidos até expirar (uma hora para um token de bot, oito horas para o de uma pessoa). Um servidor Connect do qual este servidor não guarda nenhum selo não tem nada a aposentar e é ignorado
  • Depois, dá ao servidor uma nova chave de instalação e um novo id de instalação
  • Se um servidor Connect não puder ser alcançado, ou recusar a aposentadoria do id antigo, para antes de trocar as chaves e mostra O Connect não conseguiu aposentar a chave antiga. Rotacionar mesmo assim troca as chaves de qualquer modo; o id de instalação antigo continua utilizável naquele Connect até que os tokens dele expirem, no máximo 8 horas para o GitHub
  • Não afeta os logins pelos apps próprios do servidor
  • Exige adicionar o novo id de instalação à lista de permitidos de um Connect próprio
Código Significado
hosted_unprovisioned Esta build não tem chave de configuração hospedada
signature A configuração hospedada não passou na verificação de assinatura
rollback O Connect serviu uma configuração mais antiga do que a que o servidor já viu
unreachable O servidor não consegue alcançar o Connect
install_blocked O Connect não permite este id de instalação, ou ele foi aposentado
pins_changed Um Connect próprio anunciou identificadores de app diferentes
protocol O Connect respondeu de uma forma que este servidor não entende