# 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](https://dts-identity.com/pt/docs/directories/enterprise-connectors.md).

## O que é instalado

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

| Componente | O que é | Execução |
|---|---|---|
| **Aplicação do agente** | A 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 local** | Registado 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 agente** | Um 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](https://dts-identity.com/pt/docs/directories/enterprise-connectors.md)).
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](https://dts-identity.com/pt/docs/directories/enterprise-connector-configuration.md).

### 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

- [Enterprise Connectors](https://dts-identity.com/pt/docs/directories/enterprise-connectors.md) para criar, monitorizar e eliminar conetores na consola.
- [Configurar e operar um Enterprise Connector](https://dts-identity.com/pt/docs/directories/enterprise-connector-configuration.md) para a origem de dados, TLS, estado, logs e diagnóstico.
- [Diretórios de utilizadores](https://dts-identity.com/pt/docs/directories/user-directories.md) para as definições de diretório que um conetor de autenticação serve.
