Configurar provedores de entrada
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
httpsomente paralocalhost. - Você precisa de acesso ao arquivo de configuração do servidor,
/opt/excubius/.env, ou ao instalador:sudo ./install.sh --reconfigurepergunta 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
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.
- 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.
- Em Overview, copie o Directory (tenant) ID e o Application (client) ID.
- 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.
- 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.
- Em API permissions, mantenha as permissões delegadas do Microsoft Graph
openid,profileeemail.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. - Em Token configuration, selecione Add optional claim, tipo de token ID, declaração
email, e aceite a solicitação que adiciona a permissãoemaildo Graph. Sem ela, o Excubius usapreferred_username, o que funciona bem quando os nomes UPN (nomes principais de usuário) são endereços de e-mail. - 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.
- 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:
-
Conecte-se ao servidor, assuma a conta de serviço com
sudo -iu excubiuse adicione os três valores a/opt/excubius/.env:ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
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
- 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.emaile.../auth/userinfo.profile.
- 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. - Copie o Client ID e o Client secret para
/opt/excubius/.envcomoGOOGLE_CLIENT_IDeGOOGLE_CLIENT_SECRETe reinicie a plataforma como nas etapas do Entra ID. - Verifique se o recurso
access.google_loginestá 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.
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.
| Modo | Uma primeira entrada sem convite | Função atribuída |
|---|---|---|
| By invitation (o padrão) | Recusada | — |
| Allowed domains | Aceita quando o domínio do endereço de e-mail está na lista. A correspondência é exata; subdomínios não contam | A 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:
- Abra Settings › Users and roles e escolha a entidade no seletor, por exemplo Veredas Ltda..
- 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.
- Escolha By invitation ou Allowed domains.
- Para Allowed domains, digite os Domains, separados por vírgulas ou espaços (até 50), por exemplo
ciguapa.example, e escolha a Default role. - 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_DOMAINSda 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ódigo | Significado | O que fazer |
|---|---|---|
not_invited | Não há convite e nenhuma entidade aceita registro por domínio; ou o link de convite é desconhecido | Convide a pessoa ou permita o domínio dela |
domain_not_allowed | O 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 Google | Adicione o domínio ou convide a pessoa |
account_disabled | A conta existe e está desativada | Ative-a em Users and roles |
email_mismatch | O endereço da conta não é o convidado, ou o Google não o verificou | Entre com a conta convidada ou convide o endereço correto |
invite_expired | O convite expirou ou outra pessoa já o usou | Envie um novo convite |
invalid_state | A entrada levou mais de 10 minutos, foi iniciada em outro navegador ou guia ou a resposta não correspondeu à solicitação | Comece novamente pela página de entrada |
provider_error | O provedor recusou (consentimento negado ou cancelado), não está configurado ou está desativado, ou a resposta dele não passou na validação | Verifique 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.