How to Set Up Two-Factor Authentication in ownCloud Infinite Scale

To require two-factor authentication (2FA) for ownCloud Infinite Scale sign-ins, configure it in the OpenID Connect identity provider (IDP) that authenticates your users. For many deployments, that means enabling time-based one-time passwords (TOTP) in Keycloak, then requiring users to enroll before they can finish signing in. Infinite Scale does not provide a general-purpose TOTP enrollment screen of its own. Its built-in IDP is minimal; ownCloud recommends using an external OpenID Connect provider for broader identity needs, and its documentation points to Keycloak for 2FA.

Hypothetical example: Northstar Design is a fictional 40-person company with ownCloud Infinite Scale already connected to a Keycloak realm named files. Staff currently sign in with a password. The administrator wants them to enroll an authenticator app and use a code when they next authenticate. This example is illustrative, not a report of a real installation or test. The steps below assume Keycloak is already the IDP used by Infinite Scale; if it is not, first follow the official deployment guidance for connecting the two services.

The interface images in this guide are conceptual examples, not screenshots from a live Northstar or ownCloud system. Menu wording and layout may differ across Keycloak versions. The instructions were checked against the ownCloud Infinite Scale 8.2 documentation and Keycloak Server Administration Guide 26.8 on October 6, 2026.

What 2FA changes in an Infinite Scale deployment

OpenID Connect (OIDC) is the sign-in protocol that lets Infinite Scale rely on an IDP rather than authenticate each password itself. Keycloak asks for the primary credential and, when its authentication flow requires it, a second factor such as TOTP. Infinite Scale then receives the resulting OIDC authentication. A TOTP is a short-lived code generated from a shared secret and the current time; an authenticator app stores the secret when a user scans the enrollment QR code.

That separation matters. Setting an OTP policy in Keycloak changes how Keycloak authenticates users. Setting an ownCloud MFA option does not enroll a phone or create a TOTP credential. In particular, the ownCloud OCIS_MFA_ENABLED option is for step-up authentication on specific protected routes when the IDP supports the OpenID Connect Authentication Context Class Reference (ACR) claim. It is not a switch that adds a universal TOTP prompt to every login.

Before changing the realm

• Confirm which IDP and realm the production Infinite Scale clients actually use. Compare the OIDC issuer and client IDs with the deployment configuration rather than guessing from the browser address bar.
• Have an administrator account for the correct Keycloak realm, a supported authenticator app for each user, and a recovery process for users who lose a device.
• Check that the Keycloak login page and Infinite Scale are available over HTTPS with valid certificates. Keep an existing administrator session open while making authentication changes, and test with a non-administrator account first.
• Inventory all sign-in paths. The browser flow controls browser-based OIDC authentication; API credentials, service accounts, app passwords, or other authentication flows may be governed separately.

1. Confirm that Infinite Scale uses Keycloak

In the Northstar example, the administrator confirms that the web client is already redirected to the files realm at https://login.example.test/realms/files. The ownCloud deployment example uses settings such as OCIS_OIDC_ISSUER, WEB_OIDC_CLIENT_ID, and, in its Keycloak setup, PROXY_OIDC_REWRITE_WELLKNOWN. These are deployment configuration values, not fields that ordinary users change in the Infinite Scale web interface.

If your instance still uses the embedded IDP, plan the Keycloak integration separately before enforcing OTP. Connecting an external IDP involves more than entering an issuer URL: client registration, redirect and web-origin configuration, token claims, HTTPS, and the desktop or mobile clients in use all need to agree. Use ownCloud's maintained Keycloak deployment example as a starting point for your exact version and topology.

2. Select a time-based OTP policy in Keycloak

Open the files realm in Keycloak Admin Console and go to Authentication, then Policy, then OTP Policy. Choose a time-based policy (TOTP) for authenticator apps. Keycloak also supports counter-based HOTP, but TOTP is the usual fit for phone authenticator apps because codes change with time.

Review the policy before rollout. Keycloak exposes settings such as the hash algorithm, code length, clock-drift window, token period, and whether a code can be reused. Start with values supported by the authenticators your users have. A larger clock window can help with clock drift, but it also extends the interval in which a code may be accepted. Keep the server clock synchronized and avoid widening that window as a substitute for fixing time synchronization.

3. Require OTP enrollment for new users

Em Autenticação > Ações Obrigatórias , certifique-se de que a opção Configurar OTP esteja habilitada e marque-a como ação padrão. A documentação do Keycloak afirma que uma ação obrigatória padrão se aplica quando um novo usuário faz login pela primeira vez. Isso cria um requisito de inscrição; o usuário ainda precisa concluir a configuração antes que uma credencial TOTP seja criada.

Verifique também o fluxo de autenticação do navegador. No fluxo padrão do navegador Keycloak, o subfluxo de autenticação de dois fatores condicional solicita um código OTP quando o usuário possui uma credencial OTP configurada. Se os usuários não precisarem configurar o OTP, eles podem prosseguir sem a solicitação do segundo fator. Mantenha a etapa normal de senha ou primeiro fator e teste o fluxo cuidadosamente antes de vincular um fluxo personalizado. Alterações no fluxo de autenticação afetam todo o domínio e podem bloquear administradores se configuradas incorretamente.

4. Adicionar o requisito de inscrição para usuários existentes

Uma ação padrão não é retroativa para contas já existentes. Para a equipe atual da Northstar, o administrador abre cada usuário no domínio do Keycloak e adiciona "Configurar OTP" nas ações obrigatórias desse usuário, salvando a alteração em seguida. O Keycloak também documenta uma opção na aba "Credenciais" do usuário para enviar um e-mail de redefinição de credenciais que direciona o usuário para a configuração do OTP. Escolha o método que melhor se adapta ao seu processo de gerenciamento de contas e verifique se os usuários conseguem receber o e-mail caso você o utilize.

Para um diretório grande, planeje um processo em lote controlado usando uma interface administrativa ou automação compatível com o Keycloak. Não presuma que habilitar a ação padrão tenha inscrito todos os usuários. Crie um usuário de teste e verifique o comportamento esperado no primeiro login antes de aplicar a política a todos.

5. Peça a cada usuário que registre um autenticador.

Quando Alex, um funcionário fictício da Northstar, fizer login no ownCloud e for redirecionado para o Keycloak, o Keycloak solicitará que Alex configure o OTP. Alex abre um aplicativo autenticador, escaneia o código QR exibido pelo Keycloak e insere o código atual do aplicativo para confirmar o cadastro. O código QR contém o segredo TOTP, portanto, os usuários devem tratá-lo como uma credencial: não o enviem a um administrador por e-mail, não o salvem em um ticket compartilhado nem o escaneiem em um dispositivo não confiável.

Se o aplicativo não conseguir ler o código, a página de configuração do Keycloak poderá oferecer a chave subjacente como uma entrada manual. Os usuários devem armazenar essa chave somente no autenticador. Eles devem concluir a etapa de verificação antes de fechar a página de configuração. Um código que falha na validação pode estar desatualizado, digitado incorretamente ou gerado por um aplicativo com um relógio do dispositivo incorreto.

6. Prepare a recuperação antes de aplicar a política.

Os usuários precisam de uma maneira de recuperar o acesso caso o telefone seja perdido, substituído ou formatado. O Keycloak 26.8 documenta os Códigos de Autenticação de Recuperação como uma credencial adicional que pode ser habilitada e adicionada como uma alternativa no fluxo do navegador. Se a sua versão e domínio do Keycloak utilizam esse recurso, habilite-o e teste-o cuidadosamente. Os usuários devem armazenar os códigos de recuperação em um gerenciador de senhas aprovado ou outro local offline protegido e tratar cada código como confidencial. Não os armazene no mesmo aplicativo do telefone que contém o segredo TOTP.

Se os códigos de recuperação não estiverem habilitados em seu domínio, documente um procedimento de recuperação conduzido pelo administrador. Exija a verificação de identidade antes de redefinir ou remover uma credencial OTP. Mantenha uma conta de administrador de emergência sob um processo separado e rigorosamente controlado para que um problema de inscrição de usuário não se transforme em um bloqueio em todo o domínio.

7. Teste o caminho completo de login do ownCloud.

Após a inscrição, saia da conta de teste e entre novamente no endereço normal do Infinite Scale. Confirme se o navegador acessa o domínio Keycloak esperado, aceita a senha da conta, solicita o código temporal e retorna o usuário ao ownCloud após a autenticação bem-sucedida. Em seguida, teste os clientes para desktop e dispositivos móveis compatíveis, os links compartilhados e quaisquer ferramentas operacionais que dependam do mesmo provedor de identidade.

Um teste bem-sucedido no navegador não prova que todos os clientes ou protocolos utilizam o mesmo fluxo. O fluxo do navegador do Keycloak pode não abranger um fluxo de concessão direta separado, e uma sessão de login único (SSO) existente do Keycloak pode satisfazer um login posterior no ownCloud sem exibir outra solicitação de OTP. Isso é uma reutilização esperada da sessão, não uma prova de que o fator está com defeito. Se a política exigir um novo fator com mais frequência, revise as configurações de SSO e de nível de autenticação do Keycloak como parte de uma política de sessão deliberada.

Opcional: exigir autenticação multifator adicional apenas para rotas protegidas.

Algumas implementações exigem um segundo fator apenas quando os usuários acessam um recurso sensível. O Infinite Scale oferece suporte à autenticação de dois fatores em nível de rota por meio de declarações ACR do OIDC. Na documentação da versão 8.2, OCIS_MFA_ENABLEDa aplicação é habilitada e OCIS_MFA_AUTH_LEVEL_NAMESo nível de ACR que indica a MFA é especificado. O IdP deve oferecer suporte à autenticação de dois fatores e emitir o valor de ACR correspondente no token. O Keycloak possui configurações de nível de autenticação e ACR para esse padrão, mas seu fluxo, nível solicitado e mapeamento de token devem corresponder ao valor configurado no Infinite Scale.

OCIS_MFA_ENABLED=true
OCIS_MFA_AUTH_LEVEL_NAMES=advanced

Este exemplo é apenas um ponto de partida: use- advancedo somente se o Keycloak estiver configurado para retornar esse valor de ACR após o fator necessário. Se uma rota protegida for solicitada sem o nível necessário, o Infinite Scale poderá negar o acesso e retornar uma resposta 403 com um X-OCIS-MFA-Requiredcabeçalho. O aumento de nível de rota é diferente da exigência de TOTP durante cada nova autenticação do navegador Keycloak.

Problemas comuns e soluções

Referências oficiais

• Aspectos de segurança do ownCloud Infinite Scale 8.2 — Orientações sobre provedores de identidade OIDC e recomendação do Keycloak.
• Configuração do serviço proxy do ownCloud Infinite Scale 8.2 — declarações OIDC, aumento gradual de ACR, variáveis ​​MFA e comportamento de rotas protegidas.
• Exemplo de implantação do Keycloak no ownCloud — exemplo de configuração para conectar o Infinite Scale ao Keycloak.
• Guia de Administração do Servidor Keycloak 26.8 — Políticas de OTP, ações necessárias, fluxos de navegador, códigos de recuperação e níveis de autenticação.