KEPLIN Docs

Entrar com fornecedores de autenticação

Registar o Microsoft Entra ID, o Google, um serviço OpenID Connect ou OAuth 2.0 e o Active Directory, escolher as formas de entrar de cada app e ligar as contas externas aos utilizadores.

Os utilizadores de uma app entram, de origem, com o utilizador e a palavra-passe que a app lhes guarda. Uma empresa que já tem as contas num serviço próprio prefere que as pessoas entrem com essas contas: com a conta Microsoft 365, com a conta Google ou com a conta do domínio. Os fornecedores de autenticação servem para isso.

Um fornecedor só confirma quem a pessoa é. As contas e os roles continuam a ser geridos em cada app, em Utilizadores da app: entrar por um fornecedor nunca cria utilizadores, e uma pessoa que não tenha conta na app não entra, mesmo com uma conta válida no fornecedor.

O trabalho divide-se em três partes:

  1. Registar o fornecedor, uma vez, nas Definições da plataforma.
  2. Escolher, em cada app, por onde os utilizadores dela entram.
  3. Dizer, em cada utilizador da app, com que conta externa ele entra.

Nota

Os fornecedores são para quem usa as apps. As contas da plataforma, com que se constroem as apps, continuam a entrar com o email e a palavra-passe delas.

Os tipos de fornecedor

Tipo Para quê
Microsoft Entra ID As contas Microsoft 365 da empresa.
Google As contas Google Workspace ou Google.
OpenID Connect Keycloak, Okta, Auth0, ADFS e outros serviços com OpenID Connect.
OAuth 2.0 Serviços com OAuth 2.0 sem OpenID Connect. A conta vem do perfil pedido ao serviço.
Active Directory O Active Directory da empresa. Só existe nas instalações com um só tenant.

Os quatro primeiros abrem a página de entrada do serviço e voltam à app com a pessoa identificada. O Active Directory não sai da app: a pessoa escreve a conta do domínio e a palavra-passe nos campos Utilizador e Palavra-passe do ecrã de login, e o Keplin confirma-as no domínio.

Registar um fornecedor

Só um administrador regista fornecedores.

  1. Na barra lateral, abre Definições e, no grupo Apps, a secção Autenticação das apps. A página Fornecedores de autenticação lista os que já existem, com o tipo, o estado e as apps que os usam.
  2. Carrega em Novo fornecedor.
  3. Em Tipo, escolhe o serviço. O tipo não muda depois de criado.
  4. Em Nome, escreve o nome por que as apps vão escolher o fornecedor, por exemplo entra-empresa. Aceita letras minúsculas, algarismos, hífen e underscore, e não muda depois de criado, porque entra no endereço de retorno.
  5. Opcional: em Texto do botão, escreve o texto do botão no ecrã de login das apps. Vazio, fica o texto de origem do tipo (por exemplo, «Entrar com Microsoft»), na língua de cada app.
  6. Preenche os campos da Ligação, que dependem do tipo e estão nas secções seguintes desta página.
  7. Copia o Endereço de retorno com Copiar e regista-o no serviço, como endereço de redireccionamento. É o mesmo para todas as apps, mesmo para as que têm domínio próprio.
  8. Carrega em Testar ligação. O resultado aparece por baixo e diz a causa quando falha.
  9. Carrega em Gravar.

O registo de um fornecedor Microsoft Entra ID: o nome, o texto do botão, o ID do directório, o ID da aplicação e o segredo do cliente
O registo de um fornecedor Microsoft Entra ID: o nome, o texto do botão, o ID do directório, o ID da aplicação e o segredo do cliente

As credenciais (segredos, chaves privadas e palavras-passe) ficam cifradas no servidor e nunca chegam ao browser nem aos scripts. Depois de gravadas, não voltam ao ecrã: para manter a que está gravada, deixa o campo vazio; para a mudar, escreve a nova.

O interruptor Activo desliga um fornecedor sem o apagar: desactivado, nenhuma app o mostra e as credenciais ficam guardadas.

Atenção

O Microsoft Entra ID e o Google só aceitam endereços de retorno em https. O endereço de retorno é feito a partir do Endereço público da instalação (ver Definições da plataforma): com um endereço público em http, estes dois fornecedores não funcionam, e o formulário avisa.

Microsoft Entra ID

No portal do Microsoft Entra, regista uma aplicação para o Keplin e acrescenta o Endereço de retorno como URI de redireccionamento da plataforma Web. Depois, preenche:

Campo O que escrever
ID do directório O ID do directório (tenant) da empresa, em GUID. Só entram contas deste directório. Os valores common, organizations e consumers são recusados, porque aceitam contas de qualquer empresa.
ID da aplicação O ID da aplicação (cliente) do registo.
Credencial Segredo do cliente ou Certificado.
Client secret Com Segredo do cliente: o valor do segredo criado no registo.
O segredo expira em Com Segredo do cliente: a data de validade do segredo. Os alarmes avisam 30 dias antes.
Chave privada e Impressão digital do certificado Com Certificado: a chave privada do certificado carregado no registo, em PEM (PKCS #8), e a impressão digital SHA-1 que o Entra mostra. Com certificado, o Keplin assina os pedidos e não há segredo a expirar.
Terminar também no fornecedor Ligado, sair da app faz também sair da conta Microsoft neste browser.

Google

Na consola do Google Cloud, cria um cliente OAuth do tipo aplicação Web e acrescenta o Endereço de retorno aos URIs de redireccionamento autorizados. Depois, preenche o Client ID e o Client secret.

Opcional: em Domínio do Google Workspace, escreve o domínio da empresa (por exemplo, empresa.pt) para só entrarem contas desse domínio.

OpenID Connect

Campo O que escrever
Endereço do emissor O endereço do serviço. A configuração é lida de /.well-known/openid-configuration nesse endereço.
Client ID O identificador do cliente registado no serviço.
Autenticação do cliente Como o Keplin se apresenta ao trocar o código pelo token: Segredo no cabeçalho (client_secret_basic), Segredo no corpo (client_secret_post) ou Chave privada (private_key_jwt).
Client secret ou Chave privada Conforme a autenticação escolhida. A chave privada vai em PEM (PKCS #8), e o serviço tem de conhecer a chave pública.
Scopes Os scopes pedidos. Têm de incluir openid.
Claim da conta O claim do token que se compara com a conta declarada no utilizador da app: email, preferred_username ou upn.
Exigir email verificado Com o claim email: só liga a conta quando o token diz que o email foi verificado.
Terminar também no fornecedor Ligado, sair da app faz também sair da conta do serviço neste browser.

OAuth 2.0

Para serviços que só falam OAuth 2.0, a conta vem do perfil que o Keplin pede ao serviço depois de entrar.

Campo O que escrever
Endereço de autorização e Endereço do token Os dois endereços OAuth 2.0 do serviço.
Endereço do perfil O endereço pedido com o access token. A resposta tem de ser JSON.
Client ID e Client secret O cliente registado no serviço.
Scopes Os scopes pedidos.
Campo do ID O campo do perfil que nunca muda (por exemplo, id). Fica guardado no primeiro acesso.
Campo da conta O campo do perfil que se compara com a conta declarada no utilizador da app (por exemplo, email ou login).

Active Directory

O Active Directory só precisa do servidor e de uma conta de leitura. O resto, o Keplin lê do domínio.

  1. Em Servidor, escreve o IP ou o nome de um controlador de domínio. Para ter alternativas, escreve mais, um por linha.
  2. Em Utilizador e Palavra-passe, escreve a conta que o Keplin usa para procurar as pessoas no domínio. Basta o nome (keplin); também aceita EMPRESA\keplin ou keplin@empresa.local. Só precisa de leitura.
  3. Carrega em Testar ligação. O bloco Lido do domínio mostra o Domínio, o Nome NetBIOS, a Base DN, os Controladores e o Certificado do servidor.
  4. Se o certificado não for de uma autoridade que o servidor do Keplin conheça, confirma a Impressão digital (SHA-256) com o administrador do Active Directory e carrega em Aceitar este certificado. O Keplin passa a confiar nele neste fornecedor, e a renovação do certificado de um controlador não pára as entradas.
  5. Em Como as pessoas escrevem o utilizador, escolhe a forma aceite no ecrã de login: só o nome, domínio e nome, ou o endereço.
  6. Opcional: em Grupo obrigatório, carrega em Escolher grupo e procura o grupo cujos membros podem entrar, também através de grupos dentro dele. O grupo não dá roles.
  7. Carrega em Gravar. Sem o teste da ligação, a gravação é recusada, porque o Keplin tem de ler o domínio a partir do servidor.

O registo de um fornecedor Active Directory, antes do teste da ligação
O registo de um fornecedor Active Directory, antes do teste da ligação

Em Opções avançadas ficam a Segurança (LDAPS (porta 636) ou StartTLS (porta 389)), o Tempo máximo (s) de espera por cada controlador antes de passar ao seguinte, e o Certificado da CA, em PEM, para usar a CA da empresa em vez do certificado aceite no teste.

O Keplin nunca envia palavras-passe sem cifra: um controlador que não aceite LDAPS nem StartTLS é recusado no teste, e o administrador do Active Directory tem de lhe instalar um certificado.

Escolher as formas de entrar de uma app

  1. Abre a app e, na engrenagem Definições da app, a secção Autenticação.
  2. Em Formas de entrar, liga as que a app usa: Username e password (as credenciais geridas em Utilizadores da app) e os fornecedores registados nas Definições da plataforma.
  3. Ordena-as com Subir e Descer. A ordem da lista é a ordem dos botões no ecrã de login.
  4. Opcional: em Entrar directamente, escolhe um fornecedor. Quem abre a app vai logo para ele, sem passar pelo ecrã de login. Depois de sair, ou de uma entrada recusada, o ecrã de login aparece.
  5. Carrega em Gravar.

As formas de entrar de uma app, com a palavra-passe e um fornecedor
As formas de entrar de uma app, com a palavra-passe e um fornecedor

O ecrã de login de sistema mostra os botões dos fornecedores sozinho. Num ecrã de login desenhado na app, os botões aparecem onde estiver o widget Fornecedores de entrada: sem ele, a secção avisa que os botões não aparecem. O Active Directory não tem botão, porque usa os campos Utilizador e Palavra-passe.

O ecrã de login de uma app, com o botão do fornecedor por baixo dos campos
O ecrã de login de uma app, com o botão do fornecedor por baixo dos campos

O registo público e a recuperação da palavra-passe só servem quem entra com palavra-passe.

Ligar as contas externas aos utilizadores

Cada utilizador da app diz com que conta entra em cada fornecedor.

  1. Em Definições da app › Utilizadores da app, abre a ficha do utilizador.
  2. Em Contas externas, escolhe o fornecedor e escreve a Conta: o email, o UPN ou o utilizador do domínio, conforme o fornecedor.
  3. Carrega em Acrescentar e depois em Gravar.

Uma pessoa que só entra por fornecedores não precisa de palavra-passe: numa conta nova, o campo Password só é obrigatório quando a ficha não tem contas externas, e numa conta existente desliga-se Entra com palavra-passe. Desligado, a palavra-passe é apagada e a recuperação da palavra-passe deixa de funcionar para essa pessoa.

A conta fica à espera do primeiro acesso. Quando a pessoa entra pela primeira vez, o Keplin confirma a conta e guarda o identificador do fornecedor que nunca muda; a conta passa a ligada com a data. A partir daí, mudar o email ou o nome da pessoa no fornecedor não desfaz a ligação.

A ficha de um utilizador da app, com uma conta externa à espera do primeiro acesso
A ficha de um utilizador da app, com uma conta externa à espera do primeiro acesso

Na lista de utilizadores, o filtro Todas as formas de entrar mostra só quem entra por uma forma, ou só as contas À espera do primeiro acesso.

No KeplinGo

No KeplinGo, a entrada por um fornecedor abre a página do serviço num separador do Chrome, porque o Google e o acesso condicional da Microsoft podem recusar entradas dentro da app. Quando a pessoa acaba de entrar, o KeplinGo volta à frente com a app já aberta. O Active Directory entra pelo formulário da app, como no browser.

O segredo do Microsoft Entra a expirar

Um fornecedor do Microsoft Entra com Segredo do cliente tem a data em O segredo expira em. Trinta dias antes, os alarmes da plataforma avisam por email; com o segredo expirado, ninguém entra nas apps por esse fornecedor. Para o renovar, cria um segredo novo no Microsoft Entra e escreve-o, com a data nova, no fornecedor.

Perguntas frequentes

A pessoa entrou no fornecedor e a app diz que não tem acesso. A app não tem um utilizador com essa conta externa, ou o utilizador está desactivado. Confirma em Utilizadores da app se a conta escrita em Contas externas é a mesma com que a pessoa entra no fornecedor.

Posso apagar um fornecedor que as apps usam? Podes. A remoção diz quantas apps o usam, e quem só entra por ele deixa de conseguir entrar. Para o parar sem perder a configuração, desliga Activo.

O botão do fornecedor não aparece no ecrã de login. Confirma que o fornecedor está Activo e ligado em Formas de entrar e, num ecrã de login desenhado, que o ecrã tem o widget Fornecedores de entrada.