How to Configure Keycloak as the IDP for ownCloud Infinite Scale

This guide connects ownCloud Infinite Scale (oCIS) to Keycloak using OpenID Connect (OIDC), the identity layer built on OAuth 2.0. Keycloak authenticates users; oCIS trusts the signed identity and access information Keycloak issues. The browser-based sign-in uses HTTPS redirects, while oCIS also needs to reach Keycloak’s discovery and signing-key endpoints.

As of October 6, 2026, ownCloud’s current administration documentation describes these settings under Infinite Scale 9.0. The official Keycloak deployment example is a useful starting point, but its Compose file and realm export can change. Pin compatible image versions and review the files you deploy instead of copying an unversioned example blindly.

What you need before configuring OIDC

Prepare the public HTTPS address for oCIS, such as https://cloud.example.com, and the public HTTPS address for Keycloak, such as https://sso.example.com. Both names must resolve correctly from users’ browsers. The oCIS server must also be able to reach Keycloak’s OIDC metadata and public signing keys. If a reverse proxy fronts either service, configure its public hostname and forwarded headers consistently.

• A working ownCloud Infinite Scale deployment and administrator access to its environment or Compose configuration.
• A working Keycloak realm and administrator access. A realm is a Keycloak namespace for users, clients, roles, and identity settings.
• A TLS certificate trusted by the browser and by the server that validates Keycloak’s TLS certificate. Production use should not disable certificate verification.
• A decision about account matching: connect existing oCIS users to stable identity claims, or enable first-login account provisioning with the required write-enabled user backend.

1. Find the exact Keycloak issuer

In Keycloak, the OIDC issuer is normally the realm URL, not the admin-console URL and not the discovery-document URL. For a realm named team, it may look like https://sso.example.com/realms/team. Older installations or deployments with a path prefix can differ, so do not construct the value from memory. Open the realm’s discovery document at https://sso.example.com/realms/team/.well-known/openid-configuration and copy the value of its issuer property exactly.

From a server that can reach Keycloak, you can inspect the document with:

curl -fsS https://sso.example.com/realms/team/.well-known/openid-configuration

Check that the returned issuer uses the same scheme, host, path, and realm name that you will configure in oCIS. OpenID Connect validates issuer identity exactly; a reverse-proxy hostname mismatch or an extra slash can break login.

2. Registre um cliente OIDC para o ownCloud Web.

Um cliente é o registro de aplicativo que o Keycloak usa para determinar qual serviço pode solicitar login. Crie ou adapte um cliente OpenID Connect no domínio usado para oCIS. Use um ID de cliente, como `<client_id>` web, ou um valor personalizado, e certifique-se de que ele corresponda ao WEB_OIDC_CLIENT_IDvalor no oCIS. O exemplo oficial do ownCloud usa `<client_id>` webcomo padrão.

Para um cliente baseado em navegador, utilize o fluxo de código de autorização padrão e uma configuração de cliente público consistente com o exemplo oficial. Insira os padrões exatos de redirecionamento HTTPS e de redirecionamento pós-logout exigidos pela sua implementação. Um padrão de nome de host específico, como `example.com`, https://cloud.example.com/*é mais fácil de auditar do que um curinga amplo em todos os hosts. Adicione apenas as origens da web necessárias para a sua implementação. Não crie um segredo do cliente para um cliente de navegador público e o incorpore na configuração do frontend.

3. Verifique as reivindicações e os escopos.

As declarações OIDC são atributos de identidade contidos em um token ou retornados pelo endpoint user-info. No mínimo, escolha a declaração de nome de usuário com cuidado. O proxy ownCloud usa o valor padrão para preferred_usernameresolver um usuário, e o exemplo do Keycloak configura o cliente web com escopos padrão de perfil e e-mail. Verifique se o seu domínio realmente retorna as declarações que você usa; a disponibilidade das declarações depende dos escopos do cliente e dos mapeadores de protocolo.

Para contas existentes, a declaração configurada deve corresponder ao atributo de usuário estável do ownCloud. Uma alteração no nome de usuário ou no e-mail pode causar problemas de correspondência de contas se você o usar como identificador permanente. A subdeclaração é garantidamente única e estável por provedor de identidade, mas pode não corresponder a um nome de usuário preexistente. Teste o mapeamento de contas com uma conta sem privilégios de administrador antes de liberar o acesso para todos os usuários.

4. Aponte a Escala Infinita para o Keycloak

Defina os seguintes valores no ambiente para a implantação do oCIS. O exemplo pressupõe HTTPS e um domínio Keycloak em /realms/team. Use seus próprios URLs. Este bloco em formato YAML é ilustrativo; Docker Compose, Kubernetes, systemd e outros métodos de implantação expressam variáveis ​​de ambiente de maneira diferente.

OCIS_URL: https://cloud.example.com
OCIS_OIDC_ISSUER: https://sso.example.com/realms/team
PROXY_OIDC_REWRITE_WELLKNOWN: "true"
WEB_OIDC_CLIENT_ID: web
PROXY_USER_OIDC_CLAIM: preferred_username
OCIS_EXCLUDE_RUN_SERVICES: idp

OCIS_OIDC_ISSUERSeleciona o provedor de identidade externo. PROXY_OIDC_REWRITE_WELLKNOWN=trueFaz com que o proxy reescreva o endpoint de descoberta do OpenID Connect para o emissor configurado; a ownCloud documenta isso como necessário para que seus clientes desktop e mobile descubram o provedor. WEB_OIDC_CLIENT_IDDeve corresponder ao cliente Keycloak. A exclusão idpsegue o exemplo do Keycloak da ownCloud, portanto o provedor incorporado não é iniciado como o provedor de login ativo.

Se você deseja que oCIS crie contas no primeiro login bem-sucedido, PROXY_AUTOPROVISION_ACCOUNTS=trueconfigure o serviço Graph com um backend de usuário com permissão de gravação. Defina o atributo `username` PROXY_USER_OIDC_CLAIMe PROXY_AUTOPROVISION_CLAIM_USERNAMEo atributo `username` para a mesma declaração; para o atributo `username`, consulte a documentação do ownCloud PROXY_USER_CS3_CLAIM=usernamepara este fluxo. O provisionamento automático é opcional e deve ser testado separadamente da autenticação. Não o ative a menos que as declarações recebidas sejam exclusivas e mapeadas conforme o esperado.

5. Permitir o provedor de identidade na política de segurança de conteúdo.

O Infinite Scale usa uma Política de Segurança de Conteúdo (CSP) para controlar quais origens externas seu cliente web pode contatar. A documentação do ownCloud afirma que um provedor de identidade externo, como o Keycloak, requer uma definição de CSP adequada. Se o botão de login aparecer, mas o navegador bloquear a solicitação, verifique o console do navegador em busca de erros de CSP. Configure a política PROXY_CSP_CONFIG_FILE_LOCATIONe permita apenas a origem do Keycloak e as diretivas necessárias para sua implantação. Reinicie o proxy ou a implantação após alterar o arquivo. Não resolva um problema de conexão permitindo todas as origens.

6. Reinicie e verifique o fluxo completo.

Aplique as alterações de ambiente e reinicie a implantação do oCIS usando o método que você já utiliza para gerenciá-la. Não existe um comando de reinicialização universal: um projeto Compose, uma carga de trabalho do Kubernetes e um serviço systemd possuem controles diferentes. Em seguida, verifique cada elo da cadeia:

1. Abra o URL de descoberta do Keycloak e confirme se ele retorna JSON com um issuer, authorization_endpoint, token_endpoint, e jwks_uri.
2. Abra o URL da Web do ownCloud em uma janela anônima do navegador. Confirme se o navegador foi redirecionado para o domínio Keycloak esperado.
3. Faça login com uma conta de teste e confirme se o navegador retorna ao mesmo nome de host do ownCloud sem um loop de redirecionamento.
4. Verifique se o usuário pretendido — e não um duplicado recém-criado — aparece no Infinite Scale e se pode acessar apenas os recursos esperados.
5. Faça o logout para testar e repita o processo com uma segunda conta. Se clientes para desktop ou dispositivos móveis estiverem envolvidos, teste a detecção e o login de cada um separadamente.

Falhas comuns e o que elas geralmente significam

Lista de verificação de produção

• Testamos as versões do ownCloud e do Keycloak com um pino, em vez de depender de uma latesttag flutuante.
• Use HTTPS para ambos os serviços públicos e preserve a verificação de certificado. O ownCloud documenta a substituição insegura de TLS como inadequada para produção.
• Proteja as credenciais de administrador do Keycloak, faça backup do banco de dados e da configuração do domínio do Keycloak e restrinja o acesso administrativo ao Keycloak.
• Mantenha os URIs de redirecionamento e as origens da web limitados aos nomes de host reais do ownCloud.
• Documente a declaração de identificador escolhida e as consequências da alteração de nomes de usuário, nomes de domínio, URLs do emissor ou IDs de cliente.
• Teste o acesso de recuperação antes de alternar uma instância de produção e mantenha um plano de reversão para a configuração anterior.

Referências oficiais

• Configuração do serviço proxy ownCloud Infinite Scale 9.0
• Guia de exemplo de implantação do ownCloud Keycloak
• Arquivos oficiais de implantação do ownCloud ocis_keycloak
• Guia de Administração do Servidor Keycloak 26.8
• Aspectos de segurança de escalabilidade infinita do ownCloud