Executar um servidor Connect
O Control Center Connect executa os logins de provedores (GitHub, Google Calendar, Linear, Slack) para os servidores que não registraram apps próprios. Este guia mostra como executar o seu próprio Connect, para que os apps de provedor, os segredos deles e a lista de servidores autorizados a usá-los fiquem todos com você.
O que o Connect pode e não pode ver está na referência do Connect. Leia-a primeiro se você estiver decidindo se vai executar um.
Pré-requisitos
Seção intitulada “Pré-requisitos”- Um endereço HTTPS público para o Connect, como
https://connect.example.com, atrás de um proxy que termine o TLS.httpsem criptografia só é aceito em loopback - Docker, ou um
cc_serverque você possa reiniciar com variáveis de ambiente extras - Permissão para registrar apps em cada provedor que você quiser atender
- Os servidores que vão usá-lo, com os proprietários deles à mão: cada um tem um id de instalação que você adiciona à lista de permitidos do Connect
Etapa 1: Escolher o endereço
Seção intitulada “Etapa 1: Escolher o endereço”Escolha a URL agora e mantenha-a. CONNECT_PUBLIC_URL faz parte de tudo o que
o Connect faz: as assinaturas das requisições, as credenciais seladas, as URLs
de redirecionamento dos provedores e o id de instalação de cada servidor estão
todos vinculados a ela. Mudá-la depois significa registrar os
redirecionamentos de novo e todo mundo entrar de novo.
Etapa 2: Registrar os apps de provedor
Seção intitulada “Etapa 2: Registrar os apps de provedor”Registre só os provedores que você quiser atender. Um provedor com variáveis
incompletas fica de fora da configuração do Connect, e os servidores o veem
como indisponível. A seguir, <base> é a sua CONNECT_PUBLIC_URL.
| Provedor | O que registrar | O que guardar |
|---|---|---|
| App do GitHub | Callback URL <base>/oauth/github/callback. Setup URL <base>/oauth/github/setup com Redirect on update ativado. Deixe Request user authorization (OAuth) during installation desativado: com ele ativado, o GitHub ignora a Setup URL. Mantenha Expire user authorization tokens ativado |
Id do app, slug, id de cliente, segredo de cliente, uma chave privada |
Um cliente OAuth do tipo Aplicativo da Web com o URI de redirecionamento <base>/oauth/google/callback, e a Google Calendar API ativada |
Id de cliente, segredo de cliente | |
| Linear | Um aplicativo OAuth com as callback URLs <base>/oauth/linear/callback e <base>/oauth/linear_app/callback |
Só o id de cliente |
| Slack | Redirect URLs <base>/oauth/slack_oidc/callback e <base>/oauth/slack/callback. Event Subscriptions em <base>/v1/hooks/slack/events (app_mention, message.*, assistant_thread_*, app_uninstalled, tokens_revoked). Comandos slash em <base>/v1/hooks/slack/commands. Rotação de tokens ativada |
Id do app, id de cliente, segredo de cliente, signing secret |
Conceda ao GitHub App estas permissões de repositório: Metadata de leitura, Contents de leitura e gravação, Pull requests de leitura e gravação, Issues de leitura e gravação, e Checks, Actions e Commit statuses de leitura. Adicione Members da organização com leitura para as solicitações de revisão a equipes. Os webhooks podem ficar desativados: os servidores fazem polling.
O Connect precisa da chave privada do GitHub App (Generate a private key nas configurações do App). Ele assina as requisições do App que encontram a instalação que cobre um repositório (ou, quando o repositório não tem nenhuma, a instalação do proprietário) e emite um token de instalação de um único repositório, cada um somente depois que o próprio login da pessoa que pediu comprovou acesso a esse repositório.
Todo servidor no seu Connect compartilha o bot do App. Ele pode ler, comentar, rotular e reagir como o bot em qualquer um deles. Revisar pull requests como o bot é permitido somente aos servidores que você listar em CONNECT_GITHUB_REVIEW_BOT_INSTALLS (os ids de instalação deles, separados por vírgula); todos os outros servidores publicam revisões com o token do próprio revisor. Enviar push nunca é feito como o bot. Para permitir que um servidor seu revise como o bot, adicione o id de instalação dele ali e reinicie. Guarde o arquivo da chave como um segredo, assim como a chave de selagem. O Linear também não precisa de segredo: o Connect devolve o código ao servidor, que conclui a troca sozinho.
Etapa 3: Reunir os ids de instalação
Seção intitulada “Etapa 3: Reunir os ids de instalação”O Connect só responde aos servidores da lista de permitidos dele. Em cada servidor, aponte-o para o seu Connect e depois leia o id de instalação dele:
- Acesse Configurações → Servidor → Início de sessão único, abra o cartão Control Center Connect e escolha Usar um servidor Connect próprio
- Digite a sua URL e salve. O cartão mostra o ID de instalação do servidor
Em um terminal no host do servidor, o equivalente é:
cc_server connect enable --url https://connect.example.comcc_server connect statusstatus mostra o id de instalação. Ele indica install_blocked até a etapa 5
estar concluída, o que é esperado.
Um id de instalação é derivado por endereço do Connect, então o mesmo servidor tem um id diferente para cada Connect com que conversa. Ele só muda quando o proprietário troca a chave.
Etapa 4: Criar uma chave de selagem
Seção intitulada “Etapa 4: Criar uma chave de selagem”O Connect cifra cada credencial que devolve com uma chave de selagem. Crie uma e guarde-a como arquivo secreto:
docker run --rm ghcr.io/samuelalev/cc-connect:latest \ cc-connect-config seal-key > seal_keyschmod 600 seal_keysPerder a chave de selagem desconecta todo mundo: nenhum selo pode ser aberto sem ela.
Etapa 5: Iniciar o contêiner
Seção intitulada “Etapa 5: Iniciar o contêiner”Cada release publica ghcr.io/samuelalev/cc-connect com proveniência de build.
Em produção, fixe uma tag de versão.
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:latestAponte o seu proxy reverso para a porta 8790, e defina CONNECT_TRUST_PROXY com o número de proxies na frente do Connect para que o limite por endereço veja o endereço de cada cliente. A imagem roda como um usuário sem privilégios, guarda o estado no volume /data e tem uma verificação de integridade embutida (cc-connect --healthcheck, que consulta /healthz: o processo responde). /readyz também verifica se os armazenamentos de estado e de vínculos respondem e se o Redis, quando usado, ainda roda com maxmemory-policy noeviction; aponte para ele a verificação de prontidão de um orquestrador.
A página de consentimento do login responde com um envio de formulário que o Connect aceita somente da própria página: Sec-Fetch-Site, quando enviado, precisa ser same-origin, e Origin, quando enviado, precisa ser a origem de CONNECT_PUBLIC_URL; um envio sem nenhum dos dois é recusado. Por isso o proxy precisa repassar os dois cabeçalhos sem alterá-los, e CONNECT_PUBLIC_URL precisa ser o endereço que os navegadores das pessoas de fato usam. Se continuar naquela página sempre mostrar “Este link expirou”, e o log mostrar oauth.done_refused com motivo origin ou no_origin, um dos dois está errado.
O Connect se recusa a iniciar (código de saída 78) quando a configuração dele
está aberta, insegura ou pela metade, e mostra qual variável está errada. Uma
lista de permitidos ausente, um endereço http fora do loopback, uma chave de
selagem malformada ou NAME e NAME_FILE definidos ao mesmo tempo o impedem
de iniciar.
Ponto de verificação: em cada servidor, o cartão do Connect mostra
Funcionando, e Onde cada login acontece indica Connect para cada
provedor que você registrou. cc_server connect status mostra Health: ok e
as mesmas faixas.
Montar o Connect dentro do cc_server
Seção intitulada “Montar o Connect dentro do cc_server”Um servidor pode hospedar o Connect ele mesmo, em vez de usar um contêiner separado. O serviço montado é o mesmo que a imagem executa.
- Coloque as variáveis
CONNECT_*no arquivo.envdo servidor, como na etapa 5. O servidor se recusa a iniciar quando um segredo do Connect, inclusiveCONNECT_SENTRY_DSN, está exportado no ambiente dele - Adicione
CC_SERVER_CONNECT_HOST=on - Reinicie o servidor. O log dele mostra
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.pemO Connect passa então a ser servido em <server>/connect:
CONNECT_PUBLIC_URLusa por padrão a origem da URL pública do servidor mais/connect. Defina-a explicitamente atrás de um proxy. O caminho dela precisa ser exatamente/connect, e ela precisa ser HTTPS, a menos que seja loopback- Só as variáveis
CONNECT_*chegam ao serviço montado, então ele nunca toma emprestados os apps de provedor próprios do servidor CONNECT_ALLOWED_INSTALLScontinua obrigatória, inclusive para o próprio servidor que o hospeda- Uma montagem mal configurada impede o servidor de iniciar, em vez de servir um broker aberto
- O servidor de demonstração nunca o monta
Registre os redirecionamentos dos provedores com https://<server>/connect e
depois aponte os servidores (inclusive o que o hospeda) para essa URL, como na
etapa 3.
Referência de configuração
Seção intitulada “Referência de configuração”Cada configuração é uma variável de ambiente. Qualquer segredo pode vir de um
arquivo montado: defina NAME_FILE no lugar de NAME. O Connect relê o
arquivo no máximo a cada 30 segundos e mantém o último valor válido. Os segredos
marcados como duplo também aceitam NAME_PREVIOUS (ou
NAME_PREVIOUS_FILE) durante uma rotação.
Endereço e acesso
Seção intitulada “Endereço e acesso”| Variável | Padrão | Significado |
|---|---|---|
CONNECT_PUBLIC_URL |
obrigatória | A URL pública canônica. HTTPS, ou http só em loopback. Um caminho indica uma montagem. Sem query nem fragmento |
CONNECT_ALLOWED_INSTALLS |
obrigatória | Ids de instalação separados por vírgula. * só é aceito junto com CONNECT_SIGNED_CONFIG_FILE |
CONNECT_DENY_INSTALLS |
Ids de instalação recusados mesmo quando permitidos | |
CONNECT_GITHUB_ALLOWED_OWNERS |
Ids numéricos de proprietários do GitHub. Quando definida, os tokens de repositório só são emitidos para repositórios deles. Não limita quem entra: uma pessoa autorizada a usar este Connect ainda recebe o próprio token de usuário do App. Para atender uma única organização, mantenha o App privado para ela | |
CONNECT_GITHUB_REVIEW_BOT_INSTALLS |
Ids de instalação que podem fazer o bot do App revisar pull requests. Vazia por padrão; * é recusado, e cada id também precisa estar permitido |
|
CONNECT_HOST, CONNECT_PORT |
0.0.0.0, 8790 |
Endereço e porta de escuta |
CONNECT_TRUST_PROXY |
0 |
Saltos de proxy confiáveis em X-Forwarded-For (de 0 a 8). Usado para os limites por endereço, a dica de rede da página de login e o endereço registrado no log. Atrás de um proxy, 0 conta cada cliente como o próprio proxy, e o log avisa disso uma vez |
Faixas de provedor
Seção intitulada “Faixas de provedor”| Variável | Padrão | Significado |
|---|---|---|
CONNECT_GITHUB_APP_ID, CONNECT_GITHUB_APP_SLUG, CONNECT_GITHUB_CLIENT_ID |
O GitHub App | |
CONNECT_GITHUB_CLIENT_SECRET |
Segredo, duplo | |
CONNECT_GITHUB_APP_PRIVATE_KEY |
Segredo. A chave privada do App (PEM) | |
CONNECT_GOOGLE_CLIENT_ID, CONNECT_GOOGLE_CLIENT_SECRET |
O cliente Google. O segredo é duplo | |
CONNECT_LINEAR_CLIENT_ID |
O aplicativo do Linear. Sem segredo | |
CONNECT_SLACK_APP_ID, CONNECT_SLACK_CLIENT_ID |
O app do Slack | |
CONNECT_SLACK_CLIENT_SECRET, CONNECT_SLACK_SIGNING_SECRET |
Segredos, duplos | |
CONNECT_KLIPY_APP_KEY |
Chave de busca de GIFs do Klipy. Segredo, duplo | |
CONNECT_KLIPY_MODE |
proxy |
proxy mantém a chave no Connect; key a entrega aos servidores |
CONNECT_<LANE>_SECRET_GENERATION |
1 |
GitHub, Google e Slack: a geração registrada nos selos novos |
CONNECT_<LANE>_MIN_SEAL_GENERATION |
1 |
GitHub, Google e Slack: os selos mais antigos precisam entrar de novo |
CONNECT_<LANE>_ACCEPTS_NEW |
true |
Todas as faixas: false interrompe os novos logins enquanto os existentes continuam sendo renovados |
Selos, estado e armazenamento
Seção intitulada “Selos, estado e armazenamento”| Variável | Padrão | Significado |
|---|---|---|
CONNECT_SEAL_BACKEND |
local |
local ou gcp-kms |
CONNECT_SEAL_KEYS |
Segredo, obrigatório para local. Entradas kid:key separadas por vírgula, a mais recente primeiro; as mais antigas continuam decifrando |
|
CONNECT_KMS_KEY |
projects/…/locations/…/keyRings/…/cryptoKeys/…, obrigatória para gcp-kms |
|
CONNECT_STATE |
memory |
memory para uma instância, redis para várias. Um armazenamento de memória cheio recusa novos logins e requisições em vez de esquecer uma entrada ativa |
CONNECT_REDIS_URL |
Segredo. redis:// ou rediss://. Redis 6.2 ou posterior com maxmemory-policy noeviction, ambos verificados na inicialização |
|
CONNECT_REDIS_CA_FILE |
Pacote de CA para rediss:// |
|
CONNECT_BINDINGS |
file |
Onde ficam os vínculos das equipes do Slack: file ou firestore |
CONNECT_DATA_DIR |
data (/data na imagem) |
Contém bindings.json. Travado por um Connect: um segundo na mesma pasta não inicia |
CONNECT_FIRESTORE_PROJECT, CONNECT_FIRESTORE_DATABASE |
banco de dados (default) |
Para CONNECT_BINDINGS=firestore. O Connect não inicia quando o Firestore não responde |
Configuração, logs e limites
Seção intitulada “Configuração, logs e limites”| Variável | Padrão | Significado |
|---|---|---|
CONNECT_SIGNED_CONFIG_FILE |
Uma configuração assinada offline, servida como está. Usada pelo Connect hospedado do Control Center | |
CONNECT_CONFIG_PUBLIC_KEYS |
Chaves com as quais a configuração assinada precisa ser verificada | |
CONNECT_CONFIG_EPOCH |
1 |
A época da configuração que um Connect auto-hospedado gera |
CONNECT_LOG_HMAC_KEY |
aleatória por processo | Segredo. Defina-a para manter estáveis, entre reinícios e instâncias, as etiquetas que substituem os ids de instalação |
CONNECT_SENTRY_DSN |
Segredo. Um DSN https do Sentry para o qual as linhas de erro são reportadas: o tipo do erro, os frames da pilha, a rota e o id da requisição, nunca uma mensagem, corpo ou cabeçalho | |
CONNECT_SENTRY_ENVIRONMENT |
self-hosted |
O ambiente do Sentry |
CONNECT_VERSION, CONNECT_IMAGE_DIGEST |
Informadas por /v1/version |
|
CONNECT_RATE_INSTALL_PER_MINUTE |
600 |
Requisições por instalação |
CONNECT_RATE_IP_PER_MINUTE |
300 |
Requisições por endereço (um endereço IPv6 conta por /64) |
CONNECT_RATE_GLOBAL_PER_SECOND |
500 |
Requisições para a instância inteira |
CONNECT_RATE_SLACK_HOOK_IP_PER_MINUTE |
600 |
Entregas de eventos e comandos do Slack por endereço, contadas separadamente das outras requisições |
CONNECT_RATE_SLACK_HOOK_GLOBAL_PER_SECOND |
100 |
Entregas de eventos e comandos do Slack para a instância inteira |
CONNECT_RATE_SLACK_TEAM_PER_MINUTE |
600 |
Eventos do Slack por equipe |
CONNECT_RATE_KLIPY_PER_MINUTE |
120 |
Buscas de GIFs por instalação |
CONNECT_RATE_KLIPY_IP_PER_MINUTE |
240 |
Buscas de GIFs por endereço, entre servidores |
CONNECT_RATE_LOGINS_IP_PER_10_MINUTES |
60 |
Logins iniciados por endereço |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_PER_HOUR |
30 |
Tokens do GitHub emitidos por conta do GitHub em um servidor (logins, renovações, tokens de repositório) |
CONNECT_RATE_GITHUB_TOKENS_ACCOUNT_CEILING_PER_HOUR |
4 × o acima (120) |
O mesmo, por conta do GitHub em todos os servidores |
CONNECT_RATE_GITHUB_TOKENS_IP_PER_HOUR |
600 |
Tokens do GitHub emitidos por endereço |
CONNECT_RATE_GITHUB_EXCHANGE_CEILING_PER_HOUR |
500 |
Novos logins no GitHub para o app inteiro |
CONNECT_RATE_GITHUB_APP_MINTS_INSTALL_PER_HOUR |
120 |
Tokens do bot por servidor |
CONNECT_RATE_GITHUB_APP_MINTS_ACCOUNT_PER_HOUR |
240 |
Tokens do bot por conta do GitHub que pede, em todos os servidores |
CONNECT_RATE_GITHUB_APP_CEILING_PER_HOUR |
3000 |
Tokens do bot para o app inteiro |
CONNECT_RATE_GITHUB_TOKEN_CEILING_PER_HOUR |
1500 |
Renovações e tokens de repositório para o app inteiro. Novos logins têm limite próprio, acima |
CONNECT_GITHUB_TOKEN_CAP_WARN |
10 |
Tokens de repositório ativos que uma conta do GitHub pode ter antes de o Connect registrar um aviso |
CONNECT_RATE_RETIRE_IP_PER_HOUR |
10 |
Ids de instalação aposentados por endereço (por /48 para IPv6) |
Uma chamada que passa de um limite recebe a resposta rate_limited. Os servidores tentam de novo depois e nunca desconectam ninguém por causa disso.
Executar mais de uma instância
Seção intitulada “Executar mais de uma instância”Uma instância com CONNECT_STATE=memory basta para a maioria das
organizações. Várias instâncias atrás de um mesmo endereço precisam de
CONNECT_STATE=redis e de CONNECT_BINDINGS=firestore, para que um login
iniciado em uma instância possa terminar em outra e todas as instâncias vejam os
mesmos vínculos do Slack e os mesmos ids de instalação aposentados. Um
CONNECT_DATA_DIR compartilhado não funciona: o primeiro Connect o trava. Os
limites de requisições por instalação, por endereço e da instância são por
instância; os limites de logins, tokens do GitHub, tokens do bot, buscas de GIFs
por endereço, aposentadorias e equipes do Slack são compartilhados pelo
armazenamento de estado.
Rotacionar um segredo de provedor
Seção intitulada “Rotacionar um segredo de provedor”Ninguém é desconectado:
- Crie o segredo novo no provedor e mantenha o antigo
- Mova o valor antigo para
NAME_PREVIOUS, coloque o novo emNAMEe aumenteCONNECT_<LANE>_SECRET_GENERATION. Os arquivos montados são lidos em até 30 segundos - Espere os logins serem renovados, depois exclua o segredo antigo no provedor
e remova
NAME_PREVIOUS
Para rotacionar uma chave de selagem, coloque uma nova entrada de
cc-connect-config seal-key em primeiro lugar em CONNECT_SEAL_KEYS e mantenha
a entrada antiga até os selos dela terem sido renovados.
Trocar um app
Seção intitulada “Trocar um app”Os servidores lembram os ids de app e de cliente que o seu Connect anunciou na primeira vez em que o usaram. Se você substituir um app, o cartão do Connect de cada servidor mostra Os apps do Connect mudaram, e os logins pelo Connect ficam pausados até o proprietário clicar em Confiar nos novos apps. Avise os proprietários dos servidores antes da troca, para que eles saibam que o aviso vem de você.
Bloquear um servidor
Seção intitulada “Bloquear um servidor”Adicione o id de instalação dele a CONNECT_DENY_INSTALLS e reinicie. O
proprietário vê “O Connect bloqueou o ID de instalação deste servidor. Fale com quem opera o seu servidor Connect.” e todos
os logins pelo Connect nesse servidor param.
Um servidor também aposenta o próprio id de instalação antigo quando o proprietário troca a chave. Ele prova que o id é seu com um selo de credencial que este Connect fez para ele, então somente um servidor que já autenticou alguém pode aposentar um id. O Connect guarda os ids aposentados para sempre, então a chave antiga e todos os selos feitos para ela deixam de funcionar, e libera os espaços de trabalho do Slack vinculados ao id antigo. Os tokens já entregues expiram sozinhos: em até 8 horas os de uma pessoa, e em 1 hora os de um bot. O Connect guarda no máximo 100.000 ids aposentados; acima disso, uma rotação é recusada e o log diz isso no nível de erro.
Solução de problemas
Seção intitulada “Solução de problemas”Um servidor diz que o Connect o bloqueou
Seção intitulada “Um servidor diz que o Connect o bloqueou”O id de instalação dele não está em CONNECT_ALLOWED_INSTALLS, está em
CONNECT_DENY_INSTALLS, ou foi aposentado por uma troca de chave. O id muda
quando o proprietário troca a chave; peça o novo.
Todos os logins em um provedor falham
Seção intitulada “Todos os logins em um provedor falham”Pode faltar uma das variáveis dele, então o Connect deixou a faixa de fora. Confira o log de inicialização e as tabelas acima. O GitHub precisa dos cinco: id do app, slug, id de cliente, segredo de cliente e chave privada; o Google precisa tanto do id de cliente quanto do segredo.
Os logins falham com uma divergência de redirecionamento
Seção intitulada “Os logins falham com uma divergência de redirecionamento”O redirecionamento registrado no provedor não corresponde exatamente a
CONNECT_PUBLIC_URL. Compare o esquema, o host, a porta e, em um Connect
montado, o caminho /connect.
Todo mundo precisou entrar de novo
Seção intitulada “Todo mundo precisou entrar de novo”A chave de selagem mudou ou foi perdida, um servidor trocou a chave dele ou os dados de um servidor foram restaurados em outra máquina. Uma credencial selada só abre para a instalação e o Connect que a criaram.