# Ligações

Permita o início de sessão com um Identity Provider externo (OIDC, SAML, Microsoft Entra, social), com associação de contas e criação JIT.

> **Nota de plano:** Os fornecedores sociais (como o Google, a Apple, o GitHub e muitos outros) fazem parte de todos os planos. Os fornecedores enterprise (OIDC/SAML genérico, Microsoft Entra, Okta, Auth0, Ping Identity, Keycloak, OneLogin, JumpCloud, DATEV, os agregadores de identificação eletrónica Criipto e Signicat, e o eID alemão) requerem a funcionalidade **enterprise identity brokering**, incluída no plano Advanced e superiores (e no Trial).

Uma **ligação** permite que os seus utilizadores iniciem sessão com um Identity Provider *externo*, ou seja, uma opção "Continuar com…" no ecrã de início de sessão. A plataforma delega a autenticação no fornecedor, recebe de volta o perfil do utilizador e associa-o a uma conta existente ou cria uma nova. Em termos de protocolo, a plataforma atua como Relying Party (OIDC) ou Service Provider (SAML); o fornecedor externo é o Identity Provider.

Gere as ligações em **Integrações → Ligações**, na Admin Console.

## Fornecedores disponíveis

As ligações dividem-se em três grupos.

**Genéricos** (baseados em normas, configuráveis mais do que uma vez):

| Fornecedor | Protocolo | Utilização típica |
|---|---|---|
| **OpenID Connect (generic)** | OIDC | Qualquer Identity Provider OIDC conforme à norma. |
| **SAML 2.0 (generic)** | SAML | Qualquer Identity Provider SAML 2.0. |

**Enterprise:**

| Fornecedor | Protocolo | Utilização típica |
|---|---|---|
| **Microsoft Entra** | OIDC | Início de sessão com um tenant Microsoft Entra (profissional ou escolar). |
| **Okta** | OIDC | Início de sessão com uma org Okta Workforce. Necessita do seu domínio Okta. |
| **Auth0** | OIDC | Início de sessão com um tenant Auth0. Necessita do seu domínio Auth0. |
| **Ping Identity (PingOne)** | OIDC | Início de sessão com um ambiente PingOne. Necessita do host PingOne e do ID do ambiente. |
| **Keycloak** | OIDC | Início de sessão com um Realm Keycloak. Necessita do URL do servidor e do Realm. |
| **OneLogin** | OIDC | Início de sessão com uma conta OneLogin. Necessita do seu domínio OneLogin. |
| **JumpCloud** | OIDC | Início de sessão com uma conta JumpCloud. |
| **DATEV** | OIDC | Início de sessão com uma conta DATEV (consultores fiscais e respetivos clientes). |
| **Criipto** | OIDC | Identificações eletrónicas europeias (MitID, BankID, itsme e outras) através de uma única ligação ao seu tenant Criipto. |
| **Signicat** | OIDC | Identificações eletrónicas europeias através de uma única ligação à sua conta Signicat. |
| **German eID (Online-Ausweis)** | OIDC | Início de sessão com o cartão de identificação alemão através do AusweisIDent. |

**Sociais e de consumo** (cada um configurado uma vez): Amazon, Apple, Basecamp, Bitbucket, Box, DigitalOcean, Discord, Docusign, Dropbox, Facebook, Figma, Fitbit, FreshBooks, GitHub, GitLab, Google, Hugging Face, Intuit (QuickBooks), Kakao, Klarna, LINE, LinkedIn, Microsoft account, netID, PayPal, Salesforce, Slack, SoundCloud, Spotify, Strava, TikTok, Twitch, Vimeo, WordPress.com, X, Xero e Yahoo.

As ligações OIDC e SAML genéricas podem ser configuradas mais do que uma vez (para vários fornecedores diferentes); cada fornecedor nomeado é configurado uma única vez. Novos fornecedores vão sendo acrescentados ao longo do tempo, pelo que o ecrã de criação é a lista de referência.

A lista de ligações mostra um banner quando atinge o limite de ligações do seu plano; esvazie ou remova uma ligação para poder acrescentar outra.

[Image: A lista de ligações com três Identity Providers configurados]

## Adicionar uma ligação

1. Na página Ligações, escolha **Criar ligação** e selecione um fornecedor.
2. Reveja os **pré-requisitos** que a ligação apresenta, por exemplo o registo de uma aplicação no fornecedor externo para obter um client ID e um secret, e confirme.
3. Preencha o formulário de configuração (ver abaixo).
4. Guarde. As ligações novas começam no estado **Desativado**; ative uma ligação quando estiver pronto para que apareça no ecrã de início de sessão.

### Campos de configuração

Cada ligação necessita de um **Nome** e de um **Diretório** de destino, o diretório em que são colocados os novos utilizadores criados através desta ligação. Consulte [Diretórios de utilizadores](https://dts-identity.com/pt/docs/directories/user-directories.md).

Os campos específicos de cada protocolo são:

- **OIDC genérico**: o URL de discovery (de configuração) do fornecedor, um client ID, um client secret e os scopes a pedir (por predefinição `openid profile email`). O URL de discovery é lido de cada vez, pelo que a ligação assume os endpoints e as chaves do fornecedor sem que os tenha de reintroduzir.
- **Microsoft Entra**: um client ID, um client secret e o **tenant ID** (ou `common` para multi-tenant). Os endpoints do fornecedor provêm do documento de discovery da Microsoft para esse tenant.
- **Okta**: um client ID, um client secret e o seu **domínio Okta** (por exemplo `acme.okta.com`, uma org de preview ou um domínio personalizado). Crie uma OIDC Web Application na Okta Admin Console e atribua-a aos utilizadores que devem iniciar sessão.
- **Auth0**: um client ID, um client secret e o seu **domínio Auth0** (por exemplo `acme.eu.auth0.com` ou um domínio personalizado). Crie uma Regular Web Application no Auth0 Dashboard.
- **Ping Identity (PingOne)**: um client ID, um client secret, o **host PingOne** (o host regional, como `auth.pingone.com` ou `auth.pingone.eu`, ou um domínio personalizado) e o **ID do ambiente**.
- **Keycloak**: um client ID, um client secret, o **URL do servidor** e o **Realm**. No Keycloak 16 e anteriores, inclua o caminho base `/auth` no URL do servidor. Ative a autenticação de cliente para que o cliente seja confidencial.
- **OneLogin**: um client ID, um client secret e o seu **domínio OneLogin** (por exemplo `acme.onelogin.com`). Defina o método de autenticação do token endpoint da aplicação como **POST**.
- **JumpCloud**: um client ID e um client secret de uma aplicação OIDC personalizada. Defina o respetivo tipo de autenticação de cliente como **Client Secret Post**.
- **DATEV**: um client ID e um client secret de uma app no DATEV Developer Portal, subscrita ao produto "Login with DATEV". O acesso produtivo segue-se a uma revisão técnica.
- **Criipto**: o domínio do seu tenant Criipto (por exemplo `acme.criipto.id` ou um domínio personalizado), um client ID, um client secret e a identificação eletrónica a utilizar. Como a identificação eletrónica é fixa por ligação, acrescente uma ligação para cada identificação eletrónica que queira oferecer.
- **Signicat**: o domínio da sua conta Signicat (por exemplo `acme.signicat.com`), um client ID, um client secret e a identificação eletrónica a utilizar. Acrescente uma ligação por cada identificação eletrónica.
- **German eID (Online-Ausweis)**: o ambiente (produção ou referência) e um client ID e um client secret do AusweisIDent. O AusweisIDent opera o servidor eID e detém o certificado de autorização, pelo que a integração é feita através de OIDC padrão.
- **Kakao**: uma chave de REST API (client ID) e um client secret. Na consola Kakao Developers, ative o Kakao Login, ative o OpenID Connect nas definições avançadas (necessário para receber um ID token) e configure os itens de consentimento. O acesso ao endereço de e-mail exige uma Kakao Business App.
- **netID**: um client ID e um client secret de um serviço que registe no portal de programadores da netID. Um serviço novo arranca em sandbox, para utilizadores de teste autorizados; peça a sua libertação para utilização produtiva.
- **Intuit (QuickBooks)**: um client ID e um client secret de uma app no portal Intuit Developer. As chaves de produção são emitidas depois de a Intuit concluir a avaliação da app.
- **A maioria dos fornecedores sociais**: um client ID (por vezes designado de outra forma, por exemplo o client ID do Slack, a key do Bitbucket, o application ID do GitLab, a integration key do Docusign) e um secret correspondente. Siga o guia de configuração de cada fornecedor para os nomes exatos dos campos.
- **Fornecedores com host ou região**: a Salesforce, o GitLab e o Docusign acrescentam um campo de **host** (por exemplo um Salesforce My Domain, uma instância GitLab autogerida ou o host de produção versus de programador do Docusign), para que a ligação aponte para a instância certa.
- **Apple**: um Services ID (o client ID), o seu team ID, o key ID e o conteúdo da chave privada `.p8` que descarrega da Apple. A chave privada é armazenada cifrada e nunca é mostrada de volta; o client secret que a Apple exige é gerado automaticamente a partir dela.
- **SAML genérico**: o URL de entry point (de início de sessão) do fornecedor, o respetivo Entity ID e o respetivo certificado de assinatura em formato PEM, introduzidos diretamente. O URL de callback (ACS) e o Entity ID da própria plataforma são apresentados no guia de configuração da ligação, para que os registe do lado do fornecedor.

Os secrets e as chaves privadas são introduzidos em campos que ficam em branco quando edita uma ligação existente: deixe um campo de secret vazio para manter o valor guardado. Os secrets nunca são mostrados de volta em texto simples nem escritos em registos.

Ao configurar a ligação, cada guia apresenta também o **URL de callback** a registar no fornecedor, para que este encaminhe a resposta de início de sessão de volta para esta plataforma.

### Encaminhamento por domínio de e-mail (Home Realm Discovery)

Ative o **Home realm discovery** numa ligação e indique um ou mais **Domínios de e-mail**. Quando um utilizador introduz um endereço de e-mail cujo domínio corresponde, é enviado diretamente para esse fornecedor em vez do ecrã da palavra-passe, pelo que ninguém tem de escolher o botão "Continuar com…" certo. Indique os domínios como uma lista separada por vírgulas (por exemplo `acme.com, acme.co.uk`).

- Uma ligação com domínios de e-mail definidos **não é apresentada como botão** na página de início de sessão; só é alcançável através do encaminhamento por domínio (ou de uma ligação direta). Isto mantém o ecrã de início de sessão limpo quando estão configurados vários fornecedores enterprise.
- Um domínio só pode ser atribuído a **uma** ligação; guardar uma segunda ligação com o mesmo domínio é recusado.
- Os utilizadores cujo domínio de e-mail não é encaminhado, e os que iniciam sessão com um nome de utilizador, seguem para o ecrã normal da palavra-passe.
- O e-mail é passado a um fornecedor OIDC como `login_hint`, para que este o possa preencher antecipadamente e o utilizador não tenha de introduzir o e-mail uma segunda vez. Os fornecedores SAML não o recebem (um SAML Request de início de sessão não o consegue transportar de forma fiável).
- Quando uma aplicação inicia o início de sessão com um endereço de e-mail conhecido (um `login_hint` OIDC) num domínio encaminhado, o utilizador é enviado diretamente para o fornecedor, sem ver primeiro o ecrã de início de sessão.
- Desligar o Home Realm Discovery (ou limpar os seus domínios) faz reaparecer o botão da ligação na página de início de sessão.

Se um fornecedor encaminhado estiver temporariamente mal configurado e precisar de alcançar o ecrã da palavra-passe para uma conta desse domínio, acrescente `?noHrd=1` ao URL de início de sessão para saltar o encaminhamento nessa visita.

### Por que motivo regista a sua própria aplicação no fornecedor

Para cada ligação (um fornecedor social como o GitHub ou o LinkedIn, ou um fornecedor enterprise como o Okta ou a Microsoft Entra) regista uma aplicação OAuth *no fornecedor* e indica aqui o respetivo client ID e secret, em vez de utilizar uns partilhados. Isto é intencional:

- O ecrã de consentimento mostra o **seu** nome e o **seu** logótipo, não uns genéricos.
- A aplicação pede exatamente os **scopes de que necessita**.
- O callback é encaminhado para o **seu próprio domínio**, pelo que o fim de sessão e a MFA de step-up se comportam corretamente.

O ecrã de pré-requisitos da ligação enumera o que registar antes de começar.

## Associação de contas

Quando um utilizador regressa através de uma ligação, a plataforma reconhece-o pelo identificador estável que o fornecedor disponibiliza (e não pelo e-mail) e inicia-lhe a sessão na conta associada, atualizando o nome e a imagem a partir do fornecedor.

Para evitar a apropriação de contas, se o fornecedor comunicar um endereço de e-mail que já pertence a uma conta **diferente**, não associada a esta ligação, o início de sessão é **recusado** em vez de as duas serem fundidas em silêncio: não existe um passo de administração para "fundir contas", e um e-mail recebido (sobretudo se não verificado) nunca se apodera de uma conta existente. O e-mail da ligação só é adotado numa conta quando a ligação é uma **Fonte fidedigna**, o fornecedor afirma que o e-mail está verificado e o domínio do e-mail não está reservado por outro diretório (consulte a reserva de domínios de correio em [Diretórios de utilizadores](https://dts-identity.com/pt/docs/directories/user-directories.md)).

## Criação de utilizadores just-in-time

Quando alguém inicia sessão através de uma ligação pela primeira vez e não existe nenhuma conta correspondente, a plataforma cria uma **just in time**:

- O novo utilizador é colocado no **Diretório** configurado na ligação.
- O respetivo perfil (nome, e-mail, imagem) é retirado do fornecedor.
- Não tem palavra-passe e inicia sessão apenas através da mesma ligação.

A forma como a nova conta é ativada depende da definição **Fonte fidedigna**:

- Se a ligação estiver marcada como **Fonte fidedigna** *e* o fornecedor afirmar que o e-mail está verificado, a conta é ativada de imediato.
- Caso contrário, o utilizador recebe um e-mail de ativação e tem de verificar o seu endereço antes de a conta ficar ativa.

Os fornecedores sociais são fidedignos por predefinição; as ligações OIDC e SAML genéricas não são fidedignas por predefinição, porque só deve confiar num claim de e-mail vindo de um fornecedor que controle ou tenha verificado.

### Fornecedores sem endereço de e-mail

Alguns fornecedores não disponibilizam um endereço de e-mail (por exemplo o X, o Strava, o Fitbit, o SoundCloud, o Vimeo e o TikTok). As ligações de identificação eletrónica (Criipto, Signicat e o eID alemão) devolvem igualmente um nome verificado e um identificador nacional em vez de um e-mail. Iniciar sessão através de uma destas continua a funcionar e continua a criar uma conta, mas essa conta não tem e-mail: não é enviado nenhum e-mail de ativação e não pode ser associada por e-mail a uma conta existente. O utilizador pode acrescentar e verificar um e-mail mais tarde, no seu portal de conta, o que também ativa a recuperação por e-mail e todas as opções multifator baseadas em e-mail.

Alguns fornecedores devolvem um e-mail que não verificam (o Spotify, por exemplo). Esse e-mail é guardado na nova conta, mas é tratado como não verificado e nunca é adotado noutra conta existente, pelo que a conta continua a seguir as suas regras normais de verificação.

### Apple

A Apple devolve o nome do utilizador **apenas no primeiro início de sessão**, pelo que um utilizador Apple que regressa mantém o nome captado nessa altura. Os utilizadores que escolhem a opção **Hide My Email** da Apple iniciam sessão com um endereço de relay privado, o que funciona normalmente. A chave privada `.p8` que introduz é armazenada cifrada e utilizada apenas para gerar o client secret de curta duração que a Apple exige.

## Definições por ligação

| Definição | Efeito |
|---|---|
| **Nome** | A designação apresentada na Admin Console e no registo de auditoria. |
| **Diretório** | Onde são criados os utilizadores just-in-time. |
| **Home realm discovery** | Quando ativado, os domínios de e-mail encaminhados para esta ligação. Um utilizador que introduza um e-mail com um destes domínios é enviado diretamente para este fornecedor, e a ligação não é apresentada como botão na página de início de sessão. Um domínio só pode pertencer a uma ligação. |
| **Fonte fidedigna** | Controla a ativação automática e se o e-mail do fornecedor é adotado. |
| **Ativado** | Só as ligações ativadas aparecem no ecrã de início de sessão. |

Pode desativar uma ligação para a retirar do ecrã de início de sessão sem a eliminar, ou eliminá-la por completo. Ambas as ações pedem confirmação através da introdução do nome da ligação.

## Referência

| Termo | Significado |
|---|---|
| Ligação | Uma delegação do início de sessão num Identity Provider externo. |
| Associação de contas | A correspondência de uma identidade federada que regressa com uma conta existente. |
| Criação just-in-time (JIT) | A criação de uma conta nova no primeiro início de sessão federado de um utilizador. |
| Fonte fidedigna | Uma ligação cujo claim de e-mail verificado a plataforma considera fidedigno para a ativação automática. |
| Home Realm Discovery | O encaminhamento automático de um início de sessão para uma ligação, com base no domínio de e-mail que o utilizador introduz. |

## Resolução de problemas

- **O fornecedor devolve um erro no callback.** A causa mais comum é um URL de redirecionamento (callback) que não está registado no fornecedor externo, ou um client ID / secret que não corresponde. Registe o URL de callback exato apresentado quando criou a ligação e volte a verificar as credenciais.
- **A troca de tokens falha com um erro `invalid_client`.** Alguns fornecedores (por exemplo o OneLogin e o JumpCloud) definem por predefinição o método de autenticação do token endpoint da aplicação como Basic. Defina-o como **POST** (client secret post) nas definições da aplicação no fornecedor.
- **Os utilizadores com um determinado domínio de e-mail são enviados diretamente para um fornecedor externo.** Esse domínio está atribuído aos domínios de correio de uma ligação, o que ativa o encaminhamento por domínio (Home Realm Discovery). Remova o domínio da ligação para deixar de o encaminhar. Para alcançar o ecrã da palavra-passe uma única vez (por exemplo quando o fornecedor está mal configurado), acrescente `?noHrd=1` ao URL de início de sessão.
- **O início de sessão com o Kakao falha ou não devolve nenhum ID token.** O Kakao só emite um ID token quando o OpenID Connect está ativado nas definições avançadas de Kakao Login da app. Um item de consentimento em falta também interrompe o início de sessão; configure os itens de consentimento pedidos (alcunha, imagem de perfil) na consola do Kakao.
- **Um utilizador que regressa aterra numa conta nova e vazia.** A associação de contas faz corresponder uma identidade federada a uma conta existente através do e-mail verificado. Se o fornecedor não devolver um e-mail verificado, ou se o e-mail diferir do guardado, não é encontrada nenhuma correspondência e é criada uma conta separada. Confirme que o fornecedor disponibiliza um claim de e-mail verificado.
- **O primeiro início de sessão através de uma ligação é recusado com um erro de domínio.** O domínio do e-mail está reservado por outro diretório. Um domínio listado num diretório não pode ser reivindicado por utilizadores criados noutro sítio, incluindo pelo início de sessão federado just-in-time. Mude a reserva ou utilize um endereço num domínio não reservado.
- **Um utilizador federado é criado, mas permanece inativo.** As contas novas só são ativadas automaticamente numa ligação fidedigna que devolva um e-mail verificado. Nas restantes ligações, a conta segue as suas regras normais de verificação e de ciclo de vida.

Consulte também o [glossário](https://dts-identity.com/pt/docs/reference/glossary.md).
