Skip to Content

Instalar um Enterprise Connector

Requisitos, transferência, instalação, inscrição, atualizações, migração e remoção do Enterprise Connector on-premises.

Esta página trata do lado do software: o que é instalado na sua própria rede, como se inscreve o software, como se mantém atualizado e como se remove. O lado da consola (criação do conetor, URL de aprovisionamento, estado, eliminação) está descrito em Enterprise Connectors.

O que é instalado

Uma instalação Windows aloja a aplicação do agente e um ou mais conetores. São coisas distintas:

ComponenteO que éExecução
Aplicação do agenteA janela de gestão que abre na máquina. Inscreve conetores, mantém a respetiva configuração e mostra estado, logs e diagnóstico.A pedido, iniciada por si.
Serviço de broker localRegistado no primeiro arranque como serviço Windows iec-nats. Transporta a comunicação interna entre a janela e os conetores instalados. Associado exclusivamente à máquina local.De forma permanente, como serviço Windows.
Serviço do agenteUm serviço Windows por cada conetor inscrito, com o nome iec-agent-<agent id>. Mantém a ligação de saída para a plataforma e executa o trabalho propriamente dito.De forma permanente, como serviço Windows.

Uma vez que cada conetor é um serviço Windows autónomo, os conetores continuam a funcionar quando a janela da aplicação é fechada e voltam a arrancar após um reinício. A janela só é necessária para os configurar, inspecionar ou atualizar.

Uma máquina pode alojar vários conetores, incluindo conetores de tipos diferentes e conetores associados a diretórios diferentes.

Requisitos

  • Windows em x64. O instalador e a aplicação requerem direitos de administrador local, e a aplicação pede elevação de privilégios em cada arranque, porque gere serviços Windows.
  • Apenas HTTPS de saída. O conetor estabelece a ligação ao anfitrião da plataforma na porta 443 (HTTPS e WebSocket sobre TLS) e mantém-na aberta. Do seu lado não é necessária qualquer regra de firewall de entrada nem qualquer porta publicada.
  • Acessibilidade do sistema de origem. Um conetor de autenticação tem de alcançar o seu controlador de domínio ou servidor LDAP, normalmente na porta 636 para LDAPS ou 389 para LDAP. Um conetor de aprovisionamento tem de alcançar o destino SCIM que se destina a servir.
  • Uma conta de serviço para o diretório. Um conetor de autenticação liga-se ao Active Directory ou LDAP com uma conta de leitura dedicada (uma conta com direitos de escrita apenas se ativar a sincronização ascendente ou a reescrita de palavras-passe).
  • Nenhum acesso de entrada à própria máquina. A comunicação interna entre a janela e os serviços está associada à máquina local e é recusada em qualquer outro endereço.

Escolha uma máquina que esteja sempre ligada e próxima do serviço de diretório, por exemplo um servidor de gestão no mesmo local. Para efeitos de resiliência, instale um segundo conetor do mesmo diretório noutra máquina, em vez de um segundo conetor na mesma.

Nota: o instalador ainda não está assinado digitalmente, pelo que o Windows SmartScreen apresenta um aviso no primeiro arranque. Verifique a soma de verificação indicada junto à transferência antes de prosseguir.

Transferir o instalador

  1. Na consola, abra Diretórios → Enterprise Connectors e crie o conetor que pretende inscrever (consulte Enterprise Connectors).
  2. Abra o conetor acabado de criar. Enquanto não estiver inscrito, a respetiva página oferece Download for Windows, juntamente com a versão e a soma de verificação SHA-1 do instalador.
  3. Transfira o instalador e copie-o para a máquina de destino.

Se o cartão de transferência não for apresentado, o serviço de transferência não está configurado para a sua instância. Solicite o pacote de instalação ao seu contacto de suporte.

Instalar a aplicação

  1. Execute o instalador na máquina de destino e confirme o pedido de elevação de privilégios. A instalação é feita para todos os utilizadores e cria um atalho no ambiente de trabalho.
  2. Inicie a aplicação. No primeiro arranque, regista e inicia o serviço de broker local.
  3. No primeiro arranque, a aplicação pede que defina uma palavra-passe e volta a pedi-la em cada arranque seguinte. Quem tiver acesso à máquina e a esta palavra-passe pode gerir os conetores aí existentes, pelo que deve ser tratada como uma credencial administrativa.

A palavra-passe protege exclusivamente a janela de gestão local. Não tem qualquer relação com a sua conta da consola e não é utilizada para a ligação à plataforma.

Inscrever um conetor

A inscrição liga a instalação local ao registo de conetor que criou na consola.

  1. Na consola, abra o conetor e copie o respetivo URL de aprovisionamento. Este só é mostrado aos administradores que podem editar o diretório (e só é devolvido pela API de gestão a clientes com enterpriseConnectors.write), uma vez que a primeira inscrição define a chave de encriptação do diretório.
  2. Na aplicação, abra Agents e escolha Provision agent.
  3. Cole o URL de aprovisionamento e submeta o formulário.

A aplicação gera um par de chaves, troca-o pelas credenciais permanentes do conetor, instala o serviço do conetor e inicia-o. Em poucos segundos, a consola mostra o conetor como Ready.

O URL de aprovisionamento é de utilização única e expira ao fim de alguns dias. Um conetor já inscrito não pode ser inscrito uma segunda vez com o mesmo URL. Se o URL tiver expirado, elimine o conetor pendente na consola e crie um novo.

Interceção de TLS e autoridades de certificação privadas

Se a sua rede termina e volta a assinar o tráfego TLS, ou se o anfitrião da plataforma utiliza um certificado de uma autoridade privada, expanda as advanced TLS options durante a inscrição:

  • Custom CA certificates (PEM) permite colar os certificados das autoridades em que o conetor deve confiar, para além do arquivo de certificados do Windows. É o caminho recomendado.
  • Ignore invalid certificates desativa completamente a verificação, tanto para a inscrição como para a ligação permanente do conetor. Utilize esta opção apenas como medida temporária.

Ambas as definições podem ser alteradas mais tarde na página Identity da aplicação. Consulte Configurar e operar um Enterprise Connector.

Vários conetores para o mesmo diretório

Todos os conetores de autenticação de um diretório têm de funcionar com o mesmo par de chaves: o primeiro conetor a inscrever-se estabelece a chave do diretório, e a inscrição de qualquer conetor posterior é recusada se a respetiva chave for diferente. Para acrescentar um segundo conetor a um diretório existente:

  1. Na máquina que já executa um conetor, abra Identity, introduza uma frase-passe e escolha Export keypair. Guarde o bloco cifrado e a frase-passe em local seguro.
  2. Na consola, crie o segundo conetor e copie o respetivo URL de aprovisionamento.
  3. Na segunda máquina, escolha Provision agent, cole o URL, expanda keypair import e cole o bloco exportado juntamente com a respetiva frase-passe.

A frase-passe é a única proteção da chave privada exportada e a única forma de voltar a abrir o bloco. Elimine a cópia exportada assim que o segundo conetor estiver em funcionamento.

Mudar um conetor para outra máquina

Utilize os mesmos passos de exportação e importação descritos acima e, em seguida, desative a instalação antiga:

  1. Exporte o par de chaves na máquina antiga.
  2. Crie um novo conetor na consola e inscreva-o na nova máquina com o par de chaves exportado.
  3. Confirme que o novo conetor comunica Ready e processa os inícios de sessão.
  4. Desinstale o conetor na máquina antiga e elimine o respetivo registo na consola.

Migrar um conector anterior

Se estiver instalado na máquina um conector da versão principal anterior, a página Agents mostra um aviso Previous connector found. Ao escolher Import previous connector, a inscrição, o par de chaves e as definições de diretório são transferidos e, em seguida, o serviço Windows antigo é parado e removido. O conetor mantém a sua identidade na consola, pelo que não é necessária uma nova inscrição nem um novo URL de aprovisionamento.

Tudo o que não foi possível transferir é listado como aviso após a importação, por exemplo um filtro de diretório guardado num formato antigo que tem de ser recriado na página Data source. Reveja as definições da origem de dados e execute um teste de ligação antes de considerar a migração concluída.

Manter tudo atualizado

As atualizações existem em duas camadas, ambas geridas na página Update da aplicação:

  • A atualização da aplicação abrange a própria janela de gestão. Escolha Download update e depois Install & restart. A janela fecha-se por instantes; os serviços dos conetores continuam a funcionar.
  • As atualizações dos agentes abrangem os binários do serviço. Cada versão da aplicação inclui os binários de conetor correspondentes, pelo que, após uma atualização da aplicação, a lista Agents assinala os conetores afetados com update available. Escolha Update em cada conetor ou utilize o cartão Agent updates na página Update. O serviço do conetor reinicia no âmbito da atualização.

Quando vários conetores servem o mesmo diretório, atualize um de cada vez, para que os inícios de sessão continuem a funcionar durante o reinício. A página Release notes da aplicação lista as alterações de cada versão.

Iniciar, parar e reiniciar

A lista Agents oferece Start, Stop e Restart para cada conetor instalado. Uma paragem fica memorizada: o conetor permanece parado ao longo dos reinícios até voltar a ser iniciado.

Enquanto um conetor de autenticação estiver parado, o respetivo diretório não tem qualquer caminho até ao Active Directory ou LDAP, a menos que outro conetor desse diretório esteja online. Durante esse período, os inícios de sessão dos utilizadores desse diretório falham e as sincronizações agendadas são ignoradas.

Desinstalar

Remover um único conetor

  1. Na aplicação, abra Agents e escolha Stop para o conetor. A desinstalação só é oferecida para um conetor parado.
  2. Escolha Uninstall. O serviço Windows é parado e removido, e a pasta local do conetor é eliminada.
  3. Na consola, elimine o registo do conetor em Diretórios → Enterprise Connectors.

Remover o último conetor de autenticação de um diretório deixa esse diretório sem ligação à respetiva origem: os inícios de sessão e a sincronização param até que outro conetor seja inscrito. A chave partilhada do diretório subsiste após a remoção, pelo que um conetor de substituição tem de ser inscrito com o mesmo par de chaves, exportado previamente.

Remover toda a instalação

  1. Desinstale primeiro todos os conetores na aplicação, conforme descrito acima. O desinstalador da aplicação remove a aplicação e o serviço de broker local, mas não os serviços de conetor ainda registados.
  2. Desinstale a aplicação através de Definições → Aplicações no Windows.
  3. Elimine os registos dos conetores na consola.

Resolução de problemas

  • O SmartScreen bloqueia o instalador. Compare a soma de verificação SHA-1 apresentada na consola com o ficheiro transferido e prossiga através de Mais informações → Executar mesmo assim.
  • A inscrição falha com um ticket expirado ou desconhecido. O URL de aprovisionamento é de utilização única e de curta duração. Elimine o conetor pendente na consola, crie um novo e inscreva-o com o respetivo URL atualizado.
  • A inscrição é recusada por causa de uma chave pública diferente. Outro conetor do mesmo diretório foi inscrito com um par de chaves diferente. Exporte o par de chaves do conetor em funcionamento e importe-o durante a inscrição.
  • A inscrição falha com um erro de certificado. A sua rede interceta o tráfego TLS ou o certificado da plataforma provém de uma autoridade privada. Cole os certificados da autoridade de certificação nas advanced TLS options.
  • O serviço do conetor não arranca. Abra Insight → Logs na aplicação para esse conetor. Um serviço que não consegue alcançar a plataforma tenta continuamente de novo, pelo que uma falha persistente resulta normalmente de uma restrição de firewall ou de proxy de saída na porta 443.
  • Um serviço Windows é indicado como marcado para eliminação. Feche a consola Serviços que esteja aberta e o separador Serviços do Gestor de Tarefas e tente novamente. Se o estado se mantiver, reinicie a máquina.
  • A consola mostra o conetor offline apesar de o serviço estar em execução. O conetor está em funcionamento, mas não consegue concluir a ligação de saída. Verifique a página Status da aplicação e, em seguida, os logs.

Consulte também

Nesta página