SSO corporativo (OIDC, SAML) & autenticação multifator (MFA)

Localização da configuração

Os administradores da empresa acessam esses parâmetros via Configurações → Empresa, nas abas Métodos de conexão e Autenticação em duas etapas.

VPN, proxy ou firewall corporativo

Se os seus usuários fazem logon atrás de uma VPN, de um proxy corporativo ou de um firewall com inspeção SSL, alguns fluxos do SSO podem ser bloqueados ou alterados (cookie de estado removido, domínios de identidade inacessíveis). O sintoma típico é um logon que falha ou entra em loop — enquanto o SSO funciona sem a VPN. Compartilhe a matriz de fluxos de rede com a sua equipe de rede para permitir os domínios necessários sem inspeção SSL nem reescrita de cookies.

Métodos de conexão disponíveis

O FoxPlan suporta várias abordagens de autenticação:

• Senha
• Google Sign-in
• Microsoft Sign-in
• SSO corporativo (OIDC)
• SSO corporativo (SAML 2.0)

Importante

Os administradores da empresa conservam sempre a conexão por senha, mesmo quando ela está desativada para a empresa. Isso evita ficar trancado fora do FoxPlan se o provedor de identidade ficar indisponível.

Exceções: manter a senha para determinados usuários

Ao migrar sua organização para o SSO, você pode desativar a conexão por senha para todos, exceto uma lista de usuários designados.

Desmarque Senha: um seletor «Exceções: usuários que mantêm a senha» aparece então abaixo das caixas de seleção. Escolha nele os usuários em questão e depois salve.

Esses usuários continuarão vendo o campo de senha na tela de conexão, enquanto todos os outros deverão passar pelo SSO ou pela conexão Google/Microsoft.

Casos de uso típicos:

• Contas de emergência («break-glass») em caso de pane do provedor de identidade
• Prestadores ou externos ausentes do seu diretório corporativo
• Migração progressiva: migrar as equipes para o SSO em ondas

A configuração é aplicada pelo servidor, e não apenas pela página de login: um login com senha feito pela API ou pelo aplicativo móvel é recusado, e Você esqueceu sua senha? não envia nenhum link. Os administradores da empresa e as exceções acima mantêm o acesso. As contas de API, autenticadas por token, não são afetadas.

dica

O seletor só é visível se o método Senha estiver desmarcado: enquanto ele estiver ativo, já se aplica a todos e nenhuma exceção é necessária.

Opções de MFA

As organizações podem escolher entre:

• TOTP (compatível com Google Authenticator, Microsoft Authenticator, Okta, Keycloak)
• Verificação por e-mail
• Sem MFA

Escopo: a quem se aplica a autenticação em duas etapas

Assim que um método é selecionado (TOTP ou E-mail), uma seção «Aplica-se a» permite escolher a população em questão:

Opção	Efeito
Todos os usuários	A autenticação em duas etapas se impõe a toda a empresa (comportamento padrão).
Somente os usuários listados	Apenas os usuários selecionados passam pela autenticação em duas etapas.
Todos os usuários exceto os listados	A autenticação em duas etapas se aplica a todos, exceto aos usuários selecionados.

Para os dois últimos modos, um seletor permite designar os usuários em questão.

Casos de uso típicos:

• Implantação progressiva: começar por «Somente os usuários listados» com uma equipe piloto, depois passar para «Todos os usuários».
• Reforço direcionado: exigir a autenticação em duas etapas apenas para os administradores e os perfis sensíveis.
• Exclusões técnicas: dispensar contas que não podem responder a um desafio MFA (contas de serviço, terminais compartilhados) via «Todos os usuários exceto os listados».

O escopo é aplicado no lado do servidor: um usuário fora do escopo se conecta diretamente, sem desafio MFA, mesmo se um método estiver ativo para a empresa.

cuidado

No modo «Todos os usuários exceto os listados», cada usuário excluído constitui um enfraquecimento do nível de segurança. Revise essa lista regularmente.

Fluxo de conexão

1. O usuário digita seu e-mail e continua
2. O FoxPlan identifica a empresa associada
3. Os métodos de autenticação disponíveis para essa organização são exibidos
4. O usuário escolhe Senha ou SSO conforme as opções ativadas

Para os fluxos por senha, os desafios MFA se aplicam. Os fluxos SSO delegam a autenticação ao provedor de identidade.

Configuração do SSO corporativo (OIDC)

O FoxPlan suporta os provedores OIDC: Okta, Keycloak, Google, Microsoft e implementações personalizadas.

No lado do provedor de identidade:

• Criar uma aplicação OIDC do tipo Web
• URL de redirecionamento: {origin}/login/oauth2/code/{registrationId}
• Coletar Client ID, Client Secret (ou certificado, ver abaixo) e Issuer URI

No lado do formulário SSO do FoxPlan:

• Seleção do provedor
• Nome de exibição
• Client ID
• Autenticação do cliente: segredo partilhado ou certificado
• Issuer URI
• Scopes: openid,profile,email
• Atributo username (tipicamente sub ou email)
• Toggle de ativação

Configuração do SSO corporativo (SAML 2.0)

Para os provedores de identidade que só falam SAML — AD FS anterior ao Windows Server 2016, ou SAML imposto pela sua política de segurança — e para qualquer provedor SAML 2.0: Entra ID, Okta, Keycloak, Shibboleth… Depois de conectado, o usuário obtém exatamente a mesma sessão que com OIDC.

No formulário SSO do FoxPlan, escolha o provedor SAML 2.0 e informe, de preferência, os metadados do provedor:

• URL dos metadados — para o AD FS: https://<servidor-adfs>/FederationMetadata/2007-06/FederationMetadata.xml. Ela é relida a cada conexão: um certificado de assinatura renovado no provedor é considerado sem intervenção.
• ou os metadados XML colados, se o servidor FoxPlan não conseguir acessar essa URL. Um XML ilegível é recusado já ao salvar. Cole-o novamente quando o provedor renovar o certificado.

Os metadados trazem o entity ID, a URL SSO e o certificado de assinatura do provedor. Sem eles, preencha esses três campos manualmente.

No provedor de identidade, declare o FoxPlan com os valores exibidos na tela e por Verificar a configuração:

Dado	Valor
Identificador do FoxPlan (entity ID, Relying party identifier)	{origin}/saml2/service-provider-metadata/{registrationId}
URL de retorno (ACS, binding HTTP-POST)	{origin}/login/saml2/sso/{registrationId}
Metadados do FoxPlan	A mesma URL do identificador: ela serve o arquivo de metadados, importável como está (AD FS: "Import data about the relying party published online")

{registrationId} vale <identificador da empresa>-saml2.

Atributos. O FoxPlan associa o usuário à sua conta pelo e-mail. Ele o procura no atributo indicado nas opções avançadas, depois nos nomes usuais — email, mail, a URI do AD FS http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, o OID LDAP urn:oid:0.9.2342.19200300.100.1.3, o UPN — e, na falta deles, no NameID, se ele tiver a forma de um endereço. Nome e sobrenome seguem a mesma lógica (givenName, surname, URIs do AD FS). Sem e-mail, a conexão é recusada.

Com o AD FS, adicione à relação de confiança uma regra de emissão "Send LDAP Attributes as Claims": E-Mail-Addresses → E-Mail Address, Given-Name → Given Name, Surname → Surname.

Binding. A solicitação de autenticação sai por padrão em HTTP-Redirect; HTTP-POST continua disponível. A resposta do provedor volta sempre em HTTP-POST.

Não suportado: assinatura das solicitações de autenticação, criptografia das asserções e logout SAML (Single Logout). No AD FS, não declare um certificado de criptografia na relação de confiança e não exija solicitações assinadas.

Instalação on-premise

O próprio servidor FoxPlan baixa os metadados do provedor. Se eles forem servidos por um AD FS interno cujo certificado é assinado pela PKI da empresa, deposite o certificado dessa autoridade em ca-sortant/ — veja Certificados de entrada e de saída.

Provisionamento de usuários e grupos AD

O provisionamento permite que o seu diretório (Active Directory, Entra ID, Okta, Keycloak…) conduza o FoxPlan. Ele funciona com OIDC e com SAML 2.0, portanto com o AD FS.

• Contas criadas na primeira conexão. Um usuário desconhecido do FoxPlan, membro de pelo menos um grupo AD associado a um grupo FoxPlan, recebe uma conta na primeira conexão SSO, sem convite. Ele entra no espaço de trabalho desse grupo como Membro do espaço de trabalho: sem direitos nem licença. O administrador atribui depois um papel.
• Grupos sincronizados a cada conexão. Os grupos FoxPlan associados seguem os grupos AD do usuário: ele entra ou sai deles a cada conexão. Esses grupos configuram a sua interface — menus, funções, favoritos compartilhados, modelos de projeto.

Grupos e papéis continuam separados: o provisionamento nunca altera um papel. Um usuário que não pertence a nenhum grupo associado é recusado, como sem provisionamento. Um usuário excluído no FoxPlan não é recriado pelo SSO.

Ativar o provisionamento — na configuração SSO, painel Provisionamento de usuários:

• marque Criar as contas e sincronizar os grupos na conexão;
• Atributo dos grupos: deixe vazio para reconhecer os nomes usuais (groups, memberOf, declarações Group e Role do AD FS), ou informe o atributo (SAML) ou o claim (OIDC) do seu provedor.

Associar os grupos — na aba Acesso de utilizadores → Grupos do espaço de trabalho, edite um grupo e preencha Grupos AD associados, um por linha. Um grupo AD é designado pelo nome (Finance, CONTOSO\Finance) ou pelo identificador (GUID do Entra). A comparação ignora maiúsculas e o prefixo de domínio, e só mantém o CN de um DN LDAP. Os grupos padrão não se associam: seus membros decorrem dos papéis.

Uma conta provisionada também é membro do grupo padrão All users. Seus menus e funções são a interseção de All users e dos seus grupos sincronizados: um grupo AD só pode restringir, nunca ampliar. Configure All users de forma ampla e restrinja nos grupos associados ao AD.

Na lista de membros, um selo AD indica os que estão presentes apenas pela sincronização. Eles seguem o AD, não a tela. Um membro adicionado manualmente nunca é removido pela sincronização.

No provedor de identidade, transmita os grupos do usuário:

Provedor	Ajuste
AD FS	Regra de emissão "Send Group Membership as a Claim", ou "Send LDAP Attributes as Claims": Token-Groups – Unqualified Names → Group
Entra ID	Token configuration → Add groups claim. O Entra envia o identificador (GUID) dos grupos e, acima de 200 grupos, deixa de enviar a lista: limite a emissão aos grupos atribuídos à aplicação
Okta	Groups claim filtrado nos grupos úteis
Keycloak	Mapper Group list (SAML) ou Group Membership (OIDC)

Saídas

Só com o provisionamento na conexão, uma saída do AD só é considerada na próxima conexão do usuário. O SCIM, abaixo, a aplica imediatamente. Caso contrário, exclua o usuário no FoxPlan.

Com AD FS, desmarque também Senha nos métodos de login: uma conta desativada no AD não consegue mais entrar de forma alguma, no máximo quando sua sessão FoxPlan expirar (24 h).

Provisionamento automático por SCIM (Entra ID, Okta)

Com o Entra ID ou o Okta, o diretório também pode enviar por conta própria usuários e grupos ao FoxPlan, sem esperar a conexão deles: é o protocolo SCIM 2.0. As regras são as do provisionamento na conexão — conta criada como Membro do espaço de trabalho apenas para membros de um grupo associado, papéis nunca alterados. O SCIM acrescenta as saídas imediatas: um usuário desativado, ou removido da aplicação no diretório, perde o acesso na hora.

1. Em Configurações → Empresa → Provisionamento (SCIM), clique em Gerar um token e copie-o: ele nunca mais será exibido, o FoxPlan só guarda a sua impressão digital.
2. No diretório:
   • Entra ID: Aplicativos empresariais → o seu aplicativo FoxPlan → Provisionamento, modo Automático. Tenant URL: a URL exibida pelo FoxPlan (https://<seu-dominio>/scim/v2); Secret Token: o token. Testar conexão, atribua usuários e grupos ao aplicativo e depois inicie o provisionamento.
   • Okta: o aplicativo → Provisioning → SCIM. SCIM connector base URL: a URL; Unique identifier field: userName; ações Push New Users, Push Profile Updates e Push Groups; autenticação HTTP Header com o token.
3. Associe os grupos FoxPlan aos grupos enviados, pelo nome ou identificador, como descrito acima.

No diretório	No FoxPlan
Usuário atribuído ao aplicativo	Em espera; conta criada assim que ele pertence a um grupo associado
Adicionado a um grupo, ou removido	Entra ou sai dos grupos FoxPlan associados
Desativado, ou removido do aplicativo	Conta desativada na hora: sem conexão, removido dos espaços
Reativado	Conta restaurada

A aba guarda o registro de chamadas por 90 dias. Um usuário enviado cujo e-mail corresponde a uma conta FoxPlan existente é vinculado a ela: desativá-lo no diretório também desativa essa conta. Gerar novo token ou revogá-lo interrompe o provisionamento imediatamente, sem afetar as contas já criadas.

Instalação on-premise

Aqui é o diretório que chama o FoxPlan, na porta 443 e no caminho /scim/v2. O Entra ID e o Okta são serviços online: a URL precisa estar acessível pela Internet, a menos que você use o agente de provisionamento deles instalado na sua rede.

Autenticação do cliente: segredo ou certificado

A troca do código de autorização por um token é a única chamada que o FoxPlan dirige diretamente ao fornecedor de identidade, de servidor para servidor. O FoxPlan tem de se identificar nela, e o campo Autenticação do cliente oferece duas formas de o fazer.

Segredo do cliente (predefinição). Um segredo partilhado, introduzido de ambos os lados. É o modo histórico, e nada muda para as configurações existentes: sem escolha explícita, mantêm-se assim.

Certificado (chave privada). O FoxPlan assina uma asserção JWT com uma chave privada e o fornecedor verifica-a com o certificado público que aí declarou (private_key_jwt, RFC 7523). O segredo nunca circula pela rede — razão pela qual muitas direções de informática proíbem hoje os segredos de cliente.

Surgem então dois campos:

• Certificado do cliente: o certificado X.509 em formato PEM. É a metade pública, que deve ser igualmente carregada no seu fornecedor de identidade (no Entra ID: Certificates & secrets → Certificates).
• Chave privada: em formato PKCS#8 não cifrado, o que começa por -----BEGIN PRIVATE KEY-----. Uma chave PKCS#1 (BEGIN RSA PRIVATE KEY) ou protegida por palavra-passe é recusada, com o comando de conversão a aplicar.

Para gerar um par:

openssl req -x509 -newkey rsa:2048 -keyout chave.pem -out certificado.pem -days 730 -nodes -subj "/CN=foxplan-sso"
openssl pkcs8 -topk8 -nocrypt -in chave.pem -out chave-pkcs8.pem

Declare certificado.pem no fornecedor e cole chave-pkcs8.pem no FoxPlan.

A chave privada é cifrada na base de dados, nunca é devolvida pela API e nunca volta a ser mostrada: ao editar, deixar o campo vazio mantém a chave guardada. O certificado, esse, é público e continua visível.

Um certificado expira

Ao contrário de um segredo, um certificado tem data de fim. Passada essa data, o SSO para de vez.

A data de expiração está por isso sempre à vista: a lista de configurações inclui uma coluna Autenticação que indica, para cada SSO, se se autentica com segredo ou com certificado — e neste último caso a data de expiração, a laranja no mês que a antecede e a vermelho depois de passada. Essa data nunca é introduzida à mão: é lida do próprio certificado sempre que é apresentada, a única fonte que não pode divergir da realidade. Verificar a configuração dá o detalhe completo, impressão digital incluída.

Configuração por provedor

Google — Issuer URI: https://accounts.google.com

Microsoft / Azure — Issuer: https://login.microsoftonline.com/{tenantId}/v2.0

Okta — App do tipo Web com atribuição e políticas de acesso apropriadas

Keycloak — Issuer URI do realm, flow Authorization Code configurado

Ser avisado antes da expiração

A apresentação da data pressupõe que alguém vá vê-la. Por isso o FoxPlan avisa por iniciativa própria: é enviado um e-mail aos administradores da empresa em três momentos — trinta dias, sete dias e no dia em que o certificado expirou. A mensagem nomeia o fornecedor em causa, indica a data e remete para o ecrã de configuração.

Cada patamar é anunciado apenas uma vez: a varredura retém o que já enviou. Assim que o certificado é renovado — voltando a expiração a ultrapassar os trinta dias — o contador rearma-se sozinho para o certificado seguinte. Não é preciso fazer nada.

Se não houver nenhum administrador de empresa declarado, não sai qualquer e-mail: mais uma razão para manter essa lista atualizada nos membros da empresa.

Quando a ligação falha

O utilizador cuja ligação SSO falha regressa ao ecrã de início de sessão com uma frase que nomeia a causa, e não com um código devolvido pelo fornecedor de identidade:

O que o utilizador vê	O que fazer
O certificado de ligação expirou	Renovar o certificado e voltar a carregá-lo de ambos os lados
O certificado não pode ser utilizado	Verificar se a chave privada corresponde ao certificado
O fornecedor recusou as credenciais do FoxPlan	O segredo foi alterado no fornecedor, ou o certificado não está lá declarado
Nenhuma ligação SSO ativa	A configuração está desativada ou não existe
O fornecedor recusou o acesso	A conta não está autorizada na aplicação do lado do fornecedor

O detalhe técnico — mensagem exata do fornecedor, rasto completo — fica nos registos do servidor, para o suporte. O utilizador recebe uma frase que lhe diz a quem se dirigir.

Verificar a configuração antes de testar

Cada configuração da lista tem um botão Verificar a configuração. Abre um relatório que não sai do ecrã e que não tenta qualquer ligação:

• os URL a declarar no fornecedor de identidade, com um botão de cópia: o URL de redirecionamento e o URL de arranque da ligação. São exatamente os que a aplicação vai utilizar, não é preciso reconstruí-los à mão;
• os controlos de coerência: campos obrigatórios preenchidos, documento de descoberta lido a partir do servidor, emissor e pontos de acesso conformes com o que o fornecedor publica. Com autenticação por certificado, o relatório verifica ainda que a chave privada corresponde ao certificado, mostra a impressão digital SHA-1 — a mesma que a consola do fornecedor apresenta — e assinala um certificado expirado ou prestes a expirar.

Três níveis: verde quando está conforme, laranja para um ponto a observar, vermelho para o que impedirá a ligação. O detalhe apresentado à direita de cada linha é o dado em bruto — URL, estado HTTP, mensagem do fornecedor — aquele que se transmite ao suporte.

Um controlo pode ser assinalado como «URL não sondado»: o servidor só contacta endereços públicos em https, e a configuração não está em causa.

Este relatório é apenas de leitura: nunca altera a configuração.

Resolução de problemas

Verifique estes elementos em caso de problema de autenticação:

• A URL de redirecionamento corresponde exatamente entre o IdP e o FoxPlan
• A configuração SSO está de fato ativada
• O e-mail do usuário pertence à empresa correta
• Para Okta/Azure/Keycloak, verifique a atribuição e a conformidade com as policies
• Para os usuários Senha+MFA, verifique o cadastro (segredo TOTP ou e-mail válido)