Referência do Control Center Connect
O Control Center Connect executa os inícios de sessão dos fornecedores para os
servidores que não registaram as suas próprias apps. Um servidor usa o Connect
alojado do Control Center, um Connect que a respetiva organização executa
(Executar um servidor Connect),
ou nenhum. A escolha encontra-se em Definiçõ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 Definições →
Espaço de trabalho → Integrações (Escolha por espaço de trabalho).
Cada fornecedor é uma faixa. Em Usar as minhas próprias apps (ou antes de alguém escolher), uma faixa funciona com a app do próprio servidor quando esta está totalmente configurada, caso contrário fica indisponível. Com as apps do Control Center ou um Connect próprio, o Connect executa cada faixa que serve: as apps próprias do servidor continuam guardadas, mas não são usadas para inícios de sessão, para a automação do servidor nem para o estado que o servidor comunica. Um espaço de trabalho que fez a sua própria escolha executa cada faixa por essa escolha.
| Faixa | O que a app própria precisa | Através do Connect |
|---|---|---|
github |
Id da app, chave privada, id de cliente e segredo de cliente | As pessoas iniciam sessão na GitHub App partilhada |
google |
Id de cliente e segredo de cliente | As pessoas ligam o Google Calendar |
linear |
Id de cliente | As pessoas iniciam sessão no Linear |
linear_app |
Id de cliente | Um administrador do espaço de trabalho liga o ator de app do Linear |
slack |
A ligação de um espaço de trabalho à sua própria app do Slack | Um administrador do espaço de trabalho liga o Slack à app do Slack partilhada |
klipy |
KLIPY_APP_KEY |
Pesquisa de GIFs, através do proxy do Connect |
Uma app própria apenas parcialmente configurada transforma a respetiva faixa num erro, nunca numa passagem silenciosa para o Connect. Um espaço de trabalho em Usar as minhas próprias apps nunca passa pelas apps do servidor nem por nenhum Connect, em nenhum fornecedor. Mudar a escolha do Connect do servidor não termina a sessão de ninguém num espaço de trabalho que fez a sua própria escolha.
O que o Connect vê e o que nunca vê
Secção intitulada “O que o Connect vê e o que nunca vê”| O Connect vê | O Connect nunca vê |
|---|---|
| O id de instalação do servidor e as assinaturas dos pedidos | Código-fonte, conteúdo de repositórios, diffs ou texto de pull requests |
| A conta do fornecedor que iniciou sessão, durante o início de sessão | Tickets, transcrições ou qualquer coisa da base de dados de um espaço de trabalho |
| A que espaço de trabalho pertence uma credencial, como um id opaco dentro do selo | Os segredos próprios das apps do servidor: nunca saem do servidor |
| O repositório para o qual é emitido um token do GitHub de um único repositório | Tokens de atualização em repouso: só existem dentro dos selos que o servidor guarda |
| A equipa do Slack associada ao servidor | Segredos do Linear: o servidor troca ele próprio o código do Linear |
| Os termos de pesquisa de GIFs, quando faz de proxy do Klipy | Palavras-passe, chaves de emparelhamento ou chaves de fornecedores de modelos |
| Referências de eventos do Slack (equipa, canal, id da mensagem) e o texto dos comandos slash | O texto das mensagens do Slack: o Connect descarta-o à chegada e o servidor lê ele próprio a mensagem a partir do Slack |
O Connect guarda inícios de sessão em preparação, nonces e caches durante no máximo 10 minutos, e contadores horários de utilização durante no máximo duas horas. Um token do GitHub de um único repositório emitido como pessoa fica registado, selado ao início de sessão que o pediu, até expirar (no máximo 8 horas), para que o Connect o possa voltar a entregar e revogá-lo ao desligar. Os seus únicos registos duradouros são as associações do Slack (a que servidor está associada cada equipa do Slack) e os ids de instalação retirados. Os erros trazem um código, nunca a resposta do fornecedor. Os registos guardam os ids de instalação apenas como hashes com chave, e um token do GitHub apenas como o hashed_token que o registo de auditoria da organização do GitHub mostra para ele, para que um proprietário da organização consiga relacionar os dois.
| Modo | Definiçã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. As apps próprias do servidor não são usadas |
custom |
Usar um servidor Connect próprio | Um Connect num URL HTTPS (http apenas em loopback), considerado fidedigno na primeira utilização. As apps próprias do servidor não são usadas |
off |
Usar as minhas próprias apps | Nenhuma faixa usa o Connect. Só as apps próprias iniciam a sessão das pessoas |
CC_CONNECT_URL no ambiente do servidor ou no .env bloqueia a escolha:
hosted, off ou um URL do Connect. As Definições mostram então o bloqueio e
não o podem alterar.
Esta compilação não inclui nenhuma chave de configuração alojada, pelo que o
modo alojado comunica hosted_unprovisioned e não serve nenhuma faixa. As apps
próprias e um Connect próprio funcionam.
O Connect alojado corre num único contentor. A chave de selagem e a chave privada da GitHub App partilhada são variáveis de ambiente aí, e não chaves num cofre que apenas assina ou decifra, como o GitHub recomenda para a chave privada de uma 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 as Definições marcam-na como desatualizada.
Escolha por espaço de trabalho
Secção intitulada “Escolha por espaço de trabalho”Definições → Espaço de trabalho → Integrações → Control Center Connect substitui a escolha do servidor para um espaço de trabalho. Todos os membros veem a escolha e onde cada início de sessão é executado; só um administrador do espaço de trabalho a altera.
| Escolha | Comportamento |
|---|---|
| Igual a este servidor | A predefinição. O espaço de trabalho segue o que o proprietário do servidor escolheu; a opção indica qual é |
| Usar os apps do Control Center | O Connect alojado do Control Center, seja qual for o que o servidor usa |
| Usar as minhas próprias apps | Só as apps próprias do espaço de trabalho: a GitHub App, o cliente Google, a aplicação do Linear, a chave do Klipy e a app do Slack. Um fornecedor sem uma delas fica desligado aqui; uma parcialmente configurada é um erro de configuração |
| Usar um servidor Connect próprio | Um Connect num endereço HTTPS que o espaço de trabalho indica. Endereços de rede privada ou local são recusados |
- Qualquer escolha diferente de Igual a este servidor mantém os inícios de sessão no GitHub e no Linear de cada pessoa num espaço próprio do espaço de trabalho, para que nunca se misturem com os do servidor no seu todo
- Mudar pede confirmação primeiro: todos no espaço de trabalho voltam a iniciar sessão no GitHub, no Linear e no Google Calendar pelas novas apps
- A ligação da app do Slack própria de um espaço de trabalho funciona em todas as escolhas; Adicionar o Control Center ao Slack segue a escolha
CC_CONNECT_URLtambém impede que os espaços de trabalho tenham um Connect próprio: podem seguir o servidor ou usar as próprias apps- O Connect próprio de um espaço de trabalho é considerado fidedigno na primeira utilização, só para esse espaço de trabalho: Confiar nas novas apps ali nunca altera o que o servidor ou outro espaço de trabalho considera fidedigno
Identidade de instalação
Secção intitulada “Identidade de instalação”| Elemento | O que é |
|---|---|
| Chave de instalação | Uma semente de 32 bytes no ficheiro 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. Cada pedido ao Connect é assinado com ela (RFC 9421) |
| ID de instalação | 26 caracteres derivados dessa chave pública. Mostrado nas Definiçõ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.
Credenciais seladas
Secção intitulada “Credenciais seladas”Um início de sessão através do Connect devolve um selo de credencial: um blob cifrado que só o Connect que o criou consegue abrir. Fica vinculado ao fornecedor, ao endereço do Connect, ao id de instalação, ao espaço de trabalho, à conta do fornecedor, à app e à geração do segredo.
- O servidor guarda o selo e o id de instalação para o qual foi selado. Os tokens de acesso ficam em memória
- Para renovar, o servidor envia de volta o selo e recebe um novo token de acesso e um novo selo
- Um selo cujo id de instalação ou endereço do Connect já não corresponda é eliminado da próxima vez que for lido, e essa pessoa volta a iniciar sessão. Isto acontece depois de uma troca de chave, de uma mudança para outro Connect ou de um diretório de dados restaurado num servidor diferente
- Um selo que o Connect não consiga abrir é recusado com
access_denied
Instalações do GitHub
Secção intitulada “Instalações do GitHub”A instalação da GitHub App partilhada pode ser usada a partir de qualquer servidor. O Connect não guarda registo de quais servidores a podem usar.
- Instalar o app do GitHub em Definições → Espaço de trabalho → Integrações abre a página de instalação da app no GitHub. O servidor constrói a ligação a partir do nome da app na configuração do Connect
- Um token de um único repositório exige que a app esteja instalada no proprietário do repositório e que a pessoa com sessão iniciada tenha acesso a esse repositório. É um token da própria pessoa, limitado ao seu papel, nunca mais do 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 suas instalações, o Connect entrega ao servidor o token de utilizador da App da própria pessoa, e não um token de um único repositório. Iniciar sessão num servidor é confiar a esse servidor esse token
- Uma organização que impõe uma lista de permissões de IPs do GitHub não pode usar o Connect alojado, cujos endereços não são fixos. Regista a sua própria GitHub App, nos seus servidores ou num Connect que executa
- Desligar revoga apenas esse início de sessão: o Connect gasta o seu token de atualização uma vez e elimina o que isso devolve, elimina o seu token de utilizador e os tokens de um único repositório que o Connect emitiu para ele. Uma cópia do seu selo guardada seja onde for deixa de funcionar. Os inícios de sessão da pessoa noutros servidores e espaços de trabalho continuam a funcionar. Para remover o Control Center de uma conta do GitHub por completo, revogue-o no GitHub em Settings → Applications → Authorized GitHub Apps → Revoke
O bot partilhado
Secção intitulada “O bot partilhado”Os tokens emitidos como o bot da App (as: app) mostram o mesmo bot no GitHub para cada servidor que usa o mesmo Connect: o GitHub não consegue distinguir esses servidores.
- Todos os servidores podem ter o bot a ler e a comentar:
read,reviewecomment(comentários, etiquetas, responsáveis e reações em issues e pull requests) - Rever uma pull request como o bot (
bot, que escreve pull requests) só é permitido aos servidores que o operador do Connect lista emCONNECT_GITHUB_REVIEW_BOT_INSTALLS. Todos os outros servidores recebemneeds_requestere publicam a revisão com o token próprio da pessoa responsável, que o GitHub limita a essa pessoa: a revisão aparece com o nome dela. Isto abrange a publicação de revisões por IA, os comentários de revisão e os pedidos de revisores - Fazer push, criar um ramo e abrir uma pull request (
write) nunca são emitidos como o bot partilhado. Usam sempre o próprio início de sessão de quem pediu - Aprovar uma pull request nunca é automatizado, em nenhum token
- Um servidor ou espaço de trabalho com a sua própria GitHub App mantém o bot para tudo isto, incluindo as revisões
O que os proprietários e os membros da organização devem saber
Secção intitulada “O que os proprietários e os membros da organização devem saber”- Um servidor em que alguém inicia sessão detém o token de utilizador da App dessa pessoa: até 8 horas por token, renovado até ela desligar. Pode agir em nome dela em todos os repositórios onde a App partilhada está instalada e a que ela consegue aceder. O Connect pode cortar um servidor de vez (uma instalação retirada ou negada), mas um token já entregue continua válido até expirar
- Instalar a GitHub App partilhada numa organização dá consentimento a todos os servidores do Control Center onde qualquer membro inicie sessão, e não a um só servidor
- O bot é partilhado, como acima: uma organização não consegue saber no GitHub qual servidor agiu como o bot
- Uma organização que queira a sua própria fronteira regista a sua própria GitHub App e executa o seu próprio Connect (Executar um servidor Connect), ou configura a App nos seus próprios servidores
Confiança na configuração
Secção intitulada “Confiança na configuração”| Connect | Como o servidor confia na respetiva configuração |
|---|---|
| Alojado | Verifica uma assinatura Ed25519 com as chaves compiladas na versão. Recusa uma época inferior à mais alta que já viu (rollback) |
| Próprio | Fixa, na primeira utilização, o id da 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 alteração põe em pausa os inícios de sessão através do Connect (pins_changed) até o proprietário do servidor clicar em Confiar nas novas apps |
Operações
Secção intitulada “Operações”As definições do Connect do servidor estão reservadas ao proprietário do servidor.
| Operação | O que faz |
|---|---|
connect.status |
Modo, URL, bloqueio, id de instalação, estado de saúde, época da configuração e a origem de cada faixa |
connect.configure |
Define hosted, custom (com url) ou off |
connect.test |
Obtém de novo a configuração e comunica o estado de saúde |
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 substitui-o mesmo quando um Connect não conseguiu retirar a chave antiga); ver Trocar a chave de instalação |
A escolha própria de um espaço de trabalho tem as suas próprias operações, cada uma indicando o espaço de trabalho:
| Operação | Quem | O que faz |
|---|---|---|
workspaceConnect.status |
Qualquer membro | A escolha, no que ela resolve, o estado de saúde e a origem de cada fornecedor. 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 | Obtém de novo a configuração do Connect do espaço de trabalho e comunica o estado de saúde |
workspaceConnect.confirmPins |
Administrador do espaço de trabalho | Aceita os identificadores alterados do Connect próprio do espaço de trabalho |
Os próprios inícios de sessão usam oauth.lanes, oauth.begin,
oauth.status, oauth.complete, oauth.connections e oauth.disconnect. A
pessoa é sempre quem faz a chamada com sessão iniciada.
Início de sessão através do Connect
Secção intitulada “Início de sessão através do Connect”- O servidor pede ao Connect que inicie a faixa e recebe o URL de autorização do fornecedor, que verifica antes de o mostrar. O GitHub mostra sempre o seletor de contas
- A pessoa aprova no navegador. O fornecedor regressa ao Connect
- O Connect mostra o que o servidor que iniciou o início de sessão vai poder fazer como a pessoa, e durante quanto tempo. O Connect não consegue saber quem executa esse servidor, por isso a página pede à pessoa que continue apenas se ela própria iniciou o início de sessão, e que a feche se alguém lhe enviou a ligação. Quando o navegador está noutra rede que não a do início de sessão, a página di-lo: é normal num servidor alojado ou noutro dispositivo, e é também o aspeto de um phishing. Cancelar termina o início de sessão: o código do fornecedor nunca é usado. Cada página responde uma vez: uma resposta que não veio da página que o Connect acabou de mostrar é recusada
- Depois de Continuar, o Connect mostra um código de 8 caracteres e uma
ligação
control-center://oauth-done. Quem obtiver o código fica com o acesso que acabou de ser aprovado, por isso só deve ir para onde o início de sessão foi iniciado - A pessoa escreve o código na aplicação, ou segue a ligação. O servidor reclama o início de sessão com o código e com a sua própria prova do pedido
Um início de sessão expira ao fim de 10 minutos. Cinco códigos errados
terminam-no. Uma ligação que esta aplicação não iniciou é recusada com Login
não iniciado aqui. O Connect limita quantos inícios de sessão um endereço de rede
consegue iniciar, e com que frequência são emitidos tokens do GitHub por pessoa e
servidor, por pessoa em todos os servidores, por endereço e para a app inteira.
Os novos inícios de sessão têm um orçamento próprio, para nunca atrasarem as
renovações de que outras pessoas precisam. Acima de um limite, uma chamada é
recusada com rate_limited, e o servidor tenta de novo mais tarde sem terminar a
sessão de ninguém. Um início de sessão acima do limite da pessoa é desfeito no
GitHub e recusado.
Trocar a chave de instalação
Secção intitulada “Trocar a chave de instalação”Só o proprietário do servidor pode trocar a chave, com Trocar a chave no cartão Control Center Connect em Definições → Servidor → Início de sessão único. Não existe nenhum comando para isso. Trocar a chave:
- Termina a sessão de toda a gente em todas as faixas que passam pelo Connect. Para cada servidor Connect com o qual a chave antiga foi usada, o servidor revoga os inícios de sessão do GitHub e do Slack que lá mantém (um início de sessão do Google não tem nada a revogar e expira)
- Retira o id de instalação antigo em cada um desses servidores Connect, assinado com a chave antiga e provado com um selo de credencial que o servidor mantém desse Connect. A partir daí, o Connect recusa todos os pedidos feitos com a chave antiga, por isso um selo ou uma cópia da chave antiga tirada deste servidor não serve de nada, e os espaços de trabalho do Slack associados ao id antigo ficam libertados para se poderem voltar a ligar. Os tokens já entregues continuam válidos até expirarem (uma hora para um token de bot, oito horas para o de uma pessoa). Um servidor Connect do qual este servidor não mantém nenhum selo não tem nada a retirar 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 retirar o id antigo, para antes de trocar as chaves e mostra O Connect não conseguiu retirar a chave antiga. Rodar mesmo assim troca as chaves de qualquer forma; o id de instalação antigo fica então utilizável nesse Connect até os seus tokens expirarem, no máximo 8 horas para o GitHub
- Não mexe nos inícios de sessão através das apps do próprio servidor
- Exige que o novo id de instalação seja adicionado à lista de permissões de um Connect próprio
Códigos de estado
Secção intitulada “Códigos de estado”| Código | Significado |
|---|---|
hosted_unprovisioned |
Esta compilação não tem chave de configuração alojada |
signature |
A configuração alojada falhou a verificação da assinatura |
rollback |
O Connect serviu uma configuração mais antiga do que a que o servidor já tinha visto |
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 retirado |
pins_changed |
Um Connect próprio anunciou identificadores de app diferentes |
protocol |
O Connect respondeu num formato que este servidor não compreende |