Skip to Content

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):

FornecedorProtocoloUtilização típica
OpenID Connect (generic)OIDCQualquer Identity Provider OIDC conforme à norma.
SAML 2.0 (generic)SAMLQualquer Identity Provider SAML 2.0.

Enterprise:

FornecedorProtocoloUtilização típica
Microsoft EntraOIDCInício de sessão com um tenant Microsoft Entra (profissional ou escolar).
OktaOIDCInício de sessão com uma org Okta Workforce. Necessita do seu domínio Okta.
Auth0OIDCInício de sessão com um tenant Auth0. Necessita do seu domínio Auth0.
Ping Identity (PingOne)OIDCInício de sessão com um ambiente PingOne. Necessita do host PingOne e do ID do ambiente.
KeycloakOIDCInício de sessão com um Realm Keycloak. Necessita do URL do servidor e do Realm.
OneLoginOIDCInício de sessão com uma conta OneLogin. Necessita do seu domínio OneLogin.
JumpCloudOIDCInício de sessão com uma conta JumpCloud.
DATEVOIDCInício de sessão com uma conta DATEV (consultores fiscais e respetivos clientes).
CriiptoOIDCIdentificações eletrónicas europeias (MitID, BankID, itsme e outras) através de uma única ligação ao seu tenant Criipto.
SignicatOIDCIdentificações eletrónicas europeias através de uma única ligação à sua conta Signicat.
German eID (Online-Ausweis)OIDCIní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.

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.

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).

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çãoEfeito
NomeA designação apresentada na Admin Console e no registo de auditoria.
DiretórioOnde são criados os utilizadores just-in-time.
Home realm discoveryQuando 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 fidedignaControla a ativação automática e se o e-mail do fornecedor é adotado.
AtivadoSó 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

TermoSignificado
LigaçãoUma delegação do início de sessão num Identity Provider externo.
Associação de contasA 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 fidedignaUma ligação cujo claim de e-mail verificado a plataforma considera fidedigno para a ativação automática.
Home Realm DiscoveryO 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.

Nesta página