Construir
Mutual TLS (mTLS)
O agent autentica-se neste backend inscrevendo-se para obter o seu próprio certificado de cliente mTLS — não há chave de API, nem token de portador para configurar em tempo de execução, nem nenhum modo de autenticação alternativo. Nunca tens de criar ou lidar com o certificado tu mesmo; o agent gera a sua própria chave e obtém-na assinada durante a inscrição.
6 min de leitura
A ideia central: o agent inscreve-se para obter um certificado. No primeiro arranque prova quem é com uma credencial de uso único (um token de inscrição, ou a sua identidade de cloud), o backend emite-lhe um certificado, e o agent guarda esse certificado em disco. A partir daí apresenta o certificado em cada ligação — essa é toda a história da autenticação; não há nenhuma chave separada para gerir, rodar, ou à qual recorrer.
Não és tu que crias o certificado
CONNXL_MTLS_CERT e CONNXL_MTLS_KEY são apenas caminhos de ficheiro onde
o agent guarda o certificado que lhe é emitido — não um certificado que forneces. O agent gera a
sua própria chave privada (que nunca sai do host) e obtém o certificado assinado do backend durante
a inscrição.
De onde vem o token de inscrição
Na maioria das vezes nunca tocas num token: Transferir agent configurado na página do Agente do ambiente (separador Implementação) grava um novo diretamente no binário, e o agent gasta-o ao inscrever-se no primeiro arranque. Cada transferência configurada gera o seu próprio token e eles acumulam-se — transferir vários nunca invalida os anteriores, por isso podes levantar muitas réplicas do agent de um ambiente.
Só copias um token à mão para a via manual (contentores, IaC, automação). Clica em Regenerar no mesmo painel para revelar um uma única vez —copia-o agora— ao lado de um excerto de variáveis de ambiente pré-preenchido com os teus IDs. Nota que Regenerar revoga todos os tokens já emitidos para este ambiente (cada binário configurado que tenhas transferido e qualquer token manual anterior) e entrega-te um só, novo, no lugar deles. Por isso recorre a ele em dois casos: para emitir um token manual, ou para cortar uma transferência divulgada ou obsoleta.
Quem pode fazer isto
Cunhar um token de inscrição —seja transferindo um agent configurado ou clicando em Regenerar— é uma ação de administrador, e o token tem o mínimo privilégio: não faz nada exceto permitir que um agent obtenha o seu certificado para este ambiente.
Regenerar nunca perturba um agent já inscrito
Revogar tokens só bloqueia inscrições novas. Um agent que já se inscreveu tem o seu próprio certificado de cliente mTLS e continua a autenticar-se com ele — Regenerar não o alcança. Para retirar o acesso de um agent em execução revogas o seu certificado, não o seu token de inscrição.
Definir os caminhos do certificado e o token
No host do agent, define o URL do backend, o token de inscrição e os dois caminhos onde o agent deve guardar o seu certificado e chave:
CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_TOKEN=<your-enrollment-token>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pemDois certificados diferentes — não os confundas
Estes caminhos CONNXLMTLS* são para o canal agent-para-backend. Não são o cert.pem / key.pem que o Office exige para o próprio HTTPS do agent — esse par é separado e continua a ser obrigatório. Aponta os dois para ficheiros diferentes.
Arrancar o agent
Arranca o agent como de costume. Como ainda não há certificado em disco, ele inscreve-se: gera uma chave e um pedido de assinatura, envia o pedido para o backend com o teu token, e escreve o certificado emitido nos dois caminhos acima. Em cada arranque posterior encontra o certificado já lá e apenas o apresenta — sem reinscrição.
O token é consumido no momento em que é usado
Assim que o agent tem um certificado inscrito, esse certificado é a sua ÚNICA credencial — o token de inscrição que o obteve já foi consumido e pode ser descartado. Para reinscrever um host de substituição, transfere um binário configurado novo (cada um leva o seu próprio token) ou emite um manual com Regenerar — lembrando que Regenerar revoga todos os tokens pendentes do ambiente, por isso usa-o com intenção.
Sem token? Usa a identidade de cloud do agent
Se o agent corre em AWS, GCP ou Azure, pode inscrever-se sem token nenhum para copiar — prova a sua identidade com o documento de instância assinado do fornecedor de cloud. Duas coisas a configurar:
- Autoriza primeiro a instância. Na página do Agente do ambiente, abre o separador Segurança e adiciona uma regra em Identidades de cloud de confiança para o fornecedor e a conta, o projeto ou a subscrição em que o agent corre (opcionalmente fixada a regiões específicas). Só as instâncias que correspondem a uma regra se podem inscrever.
- Define as variáveis de ambiente de atestação em vez do token — o fornecedor mais os IDs do suplemento e do ambiente (ambos mostrados na página do Agente):
CONNXL_BACKEND_URL=https://<this-backend-host>
CONNXL_ENROLL_ATTESTATION=aws # or gcp | azure
CONNXL_ADDIN_ID=<your-add-in-id>
CONNXL_ENV_ID=<your-environment-id>
CONNXL_MTLS_CERT=/etc/connxl/agent-cert.pem
CONNXL_MTLS_KEY=/etc/connxl/agent-key.pemA renovação é automática
Uma vez inscrito, o agent renova o seu certificado por conta própria bem antes de expirar — não há nada para rodar à mão e nenhum tempo de inatividade para planear.
Referência de funções
Uma função tem dois eixos independentes — o seu tipo (a espécie de fonte de dados contra a qual corre, definido quando escolhes uma ligação) e a sua forma do resultado e modelo de execução, que escolhes no construtor. Esta página é o catálogo completo dos três.
Construtor do painel de tarefas
Desenha o painel de tarefas que os teus utilizadores abrem a partir do friso — arrasta blocos para separadores, dá-lhe a tua marca com as tuas cores e logótipo, e publica alterações em cada livro aberto sem precisares de reimplementar.