Pular para o conteúdo principal
Versão: 0.4 · atual

Configurar provedores de entrada

Guia de instruçõesRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Instalador (administrador do Linux), Superadministrador, Administrador de entidade
PlanosFree · Core · Pro · EnterpriseImplantaçãoAuto-hospedado

As pessoas entram no Excubius com a conta da organização delas, do Microsoft Entra ID ou do Google. O Excubius nunca armazena uma senha de diretório: ele recebe um token assinado do provedor, verifica-o e guarda a conta como o provedor mais o identificador da pessoa nele, nunca apenas como um endereço de e-mail. Este guia mostra como registrar o Excubius em cada provedor e como decidir quem recebe uma conta.

Antes de começar​

  • Saiba qual é o endereço público do servidor, https://<primary name>. Todos os endereços de redirecionamento abaixo começam com ele. As pessoas que abrem o Excubius por um alias são enviadas ao nome principal para entrar, por isso um endereço de redirecionamento por provedor é suficiente. Consulte Configurar nomes e TLS.
  • Use HTTPS. O Microsoft Entra ID aceita http somente para localhost.
  • Você precisa de acesso ao arquivo de configuração do servidor, /opt/excubius/.env, ou ao instalador: sudo ./install.sh --reconfigure pergunta novamente os valores do Entra ID.
  • Para ativar ou desativar a entrada com o Google, você precisa da função Super admin (Superadministrador). Para escolher quem recebe uma conta em uma entidade, você precisa de Entity admin (Administrador de entidade) nela.

Como uma primeira entrada é decidida​

As funções são atribuídas somente quando a conta é criada ou quando um convite é aceito. Uma conta existente entra com as funções que tem, de modo que uma função removida por um administrador não é devolvida na próxima entrada.

Registrar o Excubius no Microsoft Entra ID​

Plano

A entrada com o Microsoft Entra ID faz parte dos planos Core, Pro e Enterprise.

Crie um registro de aplicativo por instalação, para um único locatário. Registros multilocatário (common ou organizations) não são compatíveis.

  1. No Microsoft Entra admin center, abra App registrations e selecione New registration.
    • Name: o que as pessoas verão na solicitação de consentimento, por exemplo o nome pelo qual elas conhecem o monitoramento.
    • Supported account types: Accounts in this organizational directory only (single tenant).
    • Redirect URI: plataforma Web, https://<primary name>/api/v1/auth/entra/callback.
  2. Em Overview, copie o Directory (tenant) ID e o Application (client) ID.
  3. Em Certificates & secrets › Client secrets, selecione New client secret e copie o Value dele, não o ID. Ele é exibido apenas uma vez. Anote a data de vencimento: a entrada para de funcionar quando o segredo expira, por isso crie o próximo antes dessa data e substitua o valor.
  4. Em Authentication, deixe Access tokens e ID tokens desativados para os fluxos implícito e híbrido e deixe Front-channel logout URL vazio. O Excubius usa o fluxo de código de autorização com PKCE.
  5. Em API permissions, mantenha as permissões delegadas do Microsoft Graph openid, profile e email. User.Read, adicionada por padrão, não causa problemas. Conceda o consentimento do administrador se o seu locatário não permitir que os usuários consintam por conta própria.
  6. Em Token configuration, selecione Add optional claim, tipo de token ID, declaração email, e aceite a solicitação que adiciona a permissão email do Graph. Sem ela, o Excubius usa preferred_username, o que funciona bem quando os nomes UPN (nomes principais de usuário) são endereços de e-mail.
  7. Se quiser atribuir funções a grupos do diretório, selecione Add groups claim em Token configuration:
    • Escolha Groups assigned to the application e depois atribua os grupos em Enterprise applications › seu aplicativo › Users and groups. Assim os tokens ficam pequenos e levam apenas os grupos que você mapeia. Security groups também funciona.
    • Para o token ID, escolha Group ID. O Excubius compara IDs de objeto de grupo; os nomes não correspondem.
    • Um token leva no máximo 200 grupos. Acima disso, o Entra ID não envia nenhum grupo, e o Excubius trata a pessoa como se ela não tivesse nenhum grupo do diretório.
  8. Se quiser, em Enterprise applications › seu aplicativo › Properties, defina Assignment required? como Yes. Assim, somente os usuários e grupos atribuídos ao aplicativo podem entrar, antes que o Excubius aplique as próprias regras.

Agora forneça os valores ao Excubius:

  1. Conecte-se ao servidor, assuma a conta de serviço com sudo -iu excubius e adicione os três valores a /opt/excubius/.env:

    ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2b
    ENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555
    ENTRA_CLIENT_SECRET=<the secret value>
  2. Reinicie a plataforma:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

A página de entrada mostra Sign in with Microsoft quando os três valores estão definidos. O segredo do cliente é lido somente do arquivo de configuração: ele nunca é gravado no banco de dados, nunca é retornado pela API e nunca é registrado em log.

Registrar o Excubius no Google​

  1. No Google Cloud console, abra Google Auth Platform.
    • Audience: Internal quando todos têm uma conta do Google Workspace da sua organização; External caso contrário. Publique o aplicativo ou adicione usuários de teste enquanto testa.
    • Data access: os escopos openid, .../auth/userinfo.email e .../auth/userinfo.profile.
  2. Em Clients, selecione Create client, tipo Web application, e adicione o URI de redirecionamento autorizado https://<primary name>/api/v1/auth/google/callback. Você não precisa de origens JavaScript.
  3. Copie o Client ID e o Client secret para /opt/excubius/.env como GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET e reinicie a plataforma como nas etapas do Entra ID.
  4. Verifique se o recurso access.google_login está ativado em Settings › Instance. Ele vem ativado por padrão.

A página de entrada mostra Sign in with Google. Enquanto access.google_login estiver desativado, a entrada com o Google é recusada, e não apenas ocultada.

Google e domínios permitidos

Qualquer pessoa pode criar uma conta pessoal do Google com qualquer endereço de e-mail em que receba mensagens. Por isso, uma entrada com o Google só vale para um domínio permitido quando o Google é a autoridade do endereço: uma conta do Google Workspace desse mesmo domínio, com um endereço verificado. As contas pessoais do Google sempre precisam de um convite, e, para um convite, o Google precisa informar que o endereço está verificado.

Escolher quem recebe uma conta​

Cada entidade tem um modo de registro que se aplica a ela e a tudo o que está abaixo dela, até que uma entidade inferior defina o próprio.

ModoUma primeira entrada sem conviteFunção atribuída
By invitation (o padrão)Recusada—
Allowed domainsAceita quando o domínio do endereço de e-mail está na lista. A correspondência é exata; subdomínios não contamA Default role (Viewer, a menos que você escolha outra; nunca Super admin) na entidade que define o registro, herdada abaixo dela como qualquer função

Para defini-lo:

  1. Abra Settings › Users and roles e escolha a entidade no seletor, por exemplo Veredas Ltda..
  2. Selecione a guia Registration. A página informa de onde vem a configuração atual: desta entidade, de uma entidade acima dela ou da instalação.
  3. Escolha By invitation ou Allowed domains.
  4. Para Allowed domains, digite os Domains, separados por vírgulas ou espaços (até 50), por exemplo ciguapa.example, e escolha a Default role.
  5. Selecione Save.

Para que uma entidade inferior volte a seguir a entidade pai, selecione Inherit from above again.

  • Uma pessoa cujo domínio é permitido em várias entidades recebe a função padrão de cada uma.
  • Na entidade raiz, a configuração ALLOWED_SIGNUP_DOMAINS da instalação se aplica até que um registro seja salvo nela. Ela equivale a Allowed domains com esses domínios e a função Viewer na raiz. Salvar o registro da raiz, mesmo como By invitation, a substitui.
  • Uma entidade definida como By invitation deixa de conceder funções por domínio ela mesma, mas não pode retirar uma função herdada do registro de uma entidade ancestral.
  • Para bloquear o acesso de alguém, desative a pessoa. Remover o domínio não afeta as contas existentes. Consulte Gerenciar usuários e funções.

Convites e entrada​

Um convite é um link, https://<primary name>/invite/<token>, que um administrador de entidade cria para um endereço de e-mail, uma função e uma entidade; consulte Convidar alguém. Quando a pessoa o abre:

  • A página mostra a entidade, a função, quem fez o convite e um endereço mascarado, e depois os botões de entrada. O provedor recebe o pedido de pré-selecionar o endereço convidado.
  • O endereço da conta com que a pessoa entra deve ser o convidado, comparado sem diferenciar maiúsculas de minúsculas.
  • A conta é criada, ou uma conta existente do mesmo provedor é vinculada, e a função é atribuída na entidade do convite. Uma função inferior que já existia ali é elevada; uma superior é mantida.
  • Abrir o link novamente depois simplesmente faz a entrada dessa pessoa.

Quando a entrada é recusada​

O navegador volta para a página de entrada com uma explicação simples, e cada recusa é registrada no log de auditoria como login.failed, com o motivo.

CódigoSignificadoO que fazer
not_invitedNão há convite e nenhuma entidade aceita registro por domínio; ou o link de convite é desconhecidoConvide a pessoa ou permita o domínio dela
domain_not_allowedO registro por domínio existe, mas não para este domínio, ou o provedor não é a autoridade dele, como no caso de uma conta pessoal do GoogleAdicione o domínio ou convide a pessoa
account_disabledA conta existe e está desativadaAtive-a em Users and roles
email_mismatchO endereço da conta não é o convidado, ou o Google não o verificouEntre com a conta convidada ou convide o endereço correto
invite_expiredO convite expirou ou outra pessoa já o usouEnvie um novo convite
invalid_stateA entrada levou mais de 10 minutos, foi iniciada em outro navegador ou guia ou a resposta não correspondeu à solicitaçãoComece novamente pela página de entrada
provider_errorO provedor recusou (consentimento negado ou cancelado), não está configurado ou está desativado, ou a resposta dele não passou na validaçãoVerifique as configurações do provedor acima e a entrada auth.login_refused no log do back-end

Sair do Excubius não faz a pessoa sair da Microsoft nem do Google.