Cómo configurar Keycloak como proveedor de identidad para ownCloud Infinite Scale

Esta guía conecta ownCloud Infinite Scale (oCIS) con Keycloak mediante OpenID Connect (OIDC), la capa de identidad basada en OAuth 2.0. Keycloak autentica a los usuarios; oCIS confía en la identidad firmada y la información de acceso que emite Keycloak. El inicio de sesión a través del navegador utiliza redirecciones HTTPS, mientras que oCIS también necesita acceder a los puntos finales de descubrimiento y firma de claves de Keycloak.

A fecha de 6 de octubre de 2026, la documentación de administración actual de ownCloud describe estas configuraciones en Infinite Scale 9.0. El ejemplo oficial de implementación de Keycloak es un buen punto de partida, pero su archivo Compose y la exportación del reino pueden cambiar. Fije versiones de imagen compatibles y revise los archivos que implemente en lugar de copiar un ejemplo sin control de versiones sin más.

Lo que necesitas antes de configurar OIDC

Prepare la dirección HTTPS pública para oCIS, como https://cloud.example.com, y la dirección HTTPS pública para Keycloak, como https://sso.example.com. Ambos nombres deben resolverse correctamente desde los navegadores de los usuarios. El servidor oCIS también debe poder acceder a los metadatos OIDC y las claves de firma públicas de Keycloak. Si un proxy inverso actúa como servidor frontal para cualquiera de los servicios, configure su nombre de host público y los encabezados reenviados de forma coherente.

• Una implementación operativa de ownCloud Infinite Scale y acceso de administrador a su entorno o configuración de Compose.
• Un dominio de Keycloak en funcionamiento y acceso de administrador. Un dominio es un espacio de nombres de Keycloak para usuarios, clientes, roles y configuraciones de identidad.
• Un certificado TLS de confianza para el navegador y para el servidor que valida el certificado TLS de Keycloak. En entornos de producción, no se debe deshabilitar la verificación del certificado.
• Una decisión sobre la coincidencia de cuentas: conectar a los usuarios de oCIS existentes con identidades estables o habilitar el aprovisionamiento de cuentas en el primer inicio de sesión con el backend de usuario con permisos de escritura necesarios.

1. Encuentra el emisor exacto de Keycloak

En Keycloak, el emisor OIDC suele ser la URL del reino, no la URL de la consola de administración ni la URL del documento de descubrimiento. Para un reino llamado team, puede tener este aspecto https://sso.example.com/realms/team: . Las instalaciones o implementaciones antiguas con un prefijo de ruta pueden ser diferentes, así que no construya el valor de memoria. Abra el documento de descubrimiento del reino en https://sso.example.com/realms/team/.well-known/openid-configurationy copie el valor de su issuerpropiedad exactamente.

Desde un servidor que pueda acceder a Keycloak, puede inspeccionar el documento con:

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

Verifique que el emisor devuelto utilice el mismo esquema, host, ruta y nombre de dominio que configurará en oCIS. OpenID Connect valida la identidad del emisor con exactitud; una discrepancia en el nombre de host del proxy inverso o una barra diagonal adicional pueden provocar un fallo en el inicio de sesión.

2. Registre un cliente OIDC para ownCloud Web.

Un cliente es el registro de aplicación que Keycloak utiliza para decidir qué servicio puede solicitar el inicio de sesión. Cree o adapte un cliente OpenID Connect en el dominio utilizado para oCIS. Utilice un ID de cliente como web, o un valor personalizado, y asegúrese de que coincida con el WEB_OIDC_CLIENT_IDvalor en oCIS. El ejemplo oficial de ownCloud utiliza webcomo valor predeterminado.

Para un cliente basado en navegador, utilice el flujo de código de autorización estándar y una configuración de cliente público coherente con el dominio de ejemplo oficial. Introduzca los patrones exactos de redirección HTTPS y de redireccionamiento posterior al cierre de sesión que requiera su implementación. Un patrón de nombre de host específico https://cloud.example.com/*es más fácil de auditar que un comodín amplio para todos los hosts. Añada únicamente los orígenes web que necesite su implementación. No cree un secreto de cliente para un cliente de navegador público y luego lo incorpore en la configuración del frontend.

3. Verifique las reivindicaciones y el alcance.

Las declaraciones OIDC son atributos de identidad que se incluyen en un token o que devuelve el punto final user-info. Como mínimo, elija cuidadosamente la declaración de nombre de usuario. El proxy de ownCloud utiliza por defecto preferred_usernamela resolución de un usuario, y el ejemplo de Keycloak configura el cliente web con ámbitos de perfil y correo electrónico estándar. Verifique que su propio reino devuelva las declaraciones que utiliza; la disponibilidad de las declaraciones depende de los ámbitos del cliente y de los mapeadores de protocolo.

Para las cuentas existentes, la declaración configurada debe corresponder al atributo de usuario estable de ownCloud. Un nombre de usuario o correo electrónico modificado puede causar problemas de coincidencia de cuentas si se utiliza como identificador permanente. La subdeclaración es única y estable por proveedor de identidad, pero podría no coincidir con un nombre de usuario preexistente. Pruebe la asignación de cuentas con una cuenta que no sea de administrador antes de habilitar el acceso a todos los usuarios.

4. Escala infinita de punto a Keycloak

Configure los siguientes valores en el entorno para la implementación de oCIS. El ejemplo asume HTTPS y un dominio de Keycloak en /realms/team. Utilice sus propias URL. Este bloque de estilo YAML es ilustrativo; Docker Compose, Kubernetes, systemd y otros métodos de implementación expresan las variables de entorno de manera 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_ISSUERSelecciona el proveedor de identidad externo. PROXY_OIDC_REWRITE_WELLKNOWN=trueHace que el proxy reescriba el punto final de descubrimiento de OpenID Connect al emisor configurado; ownCloud documenta esto como necesario para que sus clientes de escritorio y móviles descubran al proveedor. WEB_OIDC_CLIENT_IDDebe coincidir con el cliente Keycloak. La exclusión idpsigue el ejemplo de Keycloak de ownCloud para que el proveedor integrado no se inicie como proveedor de inicio de sesión activo.

Si desea que oCIS cree cuentas en el primer inicio de sesión exitoso, PROXY_AUTOPROVISION_ACCOUNTS=trueconfigure el servicio Graph con un backend de usuario con permisos de escritura. Establezca PROXY_USER_OIDC_CLAIMy PROXY_AUTOPROVISION_CLAIM_USERNAMEen la misma declaración; para el atributo de nombre de usuario, consulte la documentación de ownCloud PROXY_USER_CS3_CLAIM=usernamepara este flujo. El aprovisionamiento automático es opcional y debe probarse por separado de la autenticación. No lo active a menos que las declaraciones entrantes sean únicas y estén asignadas según lo previsto.

5. Permitir el proveedor de identidad en la política de seguridad de contenido.

Infinite Scale utiliza una Política de Seguridad de Contenido (CSP) para controlar los orígenes externos con los que su cliente web puede conectarse. La documentación de ownCloud indica que un proveedor de identidad externo como Keycloak requiere una definición de CSP adecuada. Si aparece el botón de inicio de sesión, pero el navegador bloquea la solicitud, revise la consola del navegador en busca de errores de CSP. Configure la política PROXY_CSP_CONFIG_FILE_LOCATIONy permita solo el origen de Keycloak y las directivas que su implementación necesita. Reinicie el proxy o la implementación después de modificar el archivo. No solucione un problema de conexión permitiendo todos los orígenes.

6. Reinicie y verifique el flujo completo.

Aplique los cambios del entorno y reinicie la implementación de oCIS utilizando el método que ya usa para administrarla. No existe un comando de reinicio universal: un proyecto Compose, una carga de trabajo de Kubernetes y un servicio systemd tienen controles diferentes. Luego, verifique cada eslabón de la cadena:

1. Abra la URL de descubrimiento de Keycloak y confirme que devuelve JSON con un issuer, authorization_endpoint, token_endpoint, y jwks_uri.
2. Abra la URL web de ownCloud en una ventana de navegación privada. Confirme que el navegador se redirige al dominio de Keycloak esperado.
3. Inicia sesión con una cuenta de prueba y confirma que el navegador regresa al mismo nombre de host de ownCloud sin un bucle de redireccionamiento.
4. Compruebe que el usuario previsto —y no un duplicado recién creado— aparece en Infinite Scale y que solo puede acceder a los recursos esperados.
5. Prueba a cerrar sesión y repite el proceso con una segunda cuenta. Si incluyes clientes de escritorio o móviles, prueba su detección e inicio de sesión por separado.

Fallos comunes y lo que suelen significar

Lista de verificación de producción

• Se probaron las versiones de ownCloud y Keycloak mediante pines en lugar de depender de una latestetiqueta flotante.
• Utilice HTTPS tanto para los servicios públicos como para la verificación de certificados. ownCloud documenta que la anulación de TLS, que no es segura, no es adecuada para entornos de producción.
• Proteja las credenciales de administrador de Keycloak, realice copias de seguridad de la base de datos y la configuración del dominio de Keycloak, y restrinja el acceso de administración a Keycloak.
• Limita las URI de redireccionamiento y los orígenes web a los nombres de host reales de ownCloud.
• Documente la declaración del identificador elegido y las consecuencias de cambiar los nombres de usuario, los nombres de dominio, las URL del emisor o los ID de cliente.
• Pruebe el acceso de recuperación antes de cambiar una instancia de producción y mantenga una reversión planificada de la configuración anterior.

Referencias oficiales

• Configuración del servicio proxy ownCloud Infinite Scale 9.0
• Guía de ejemplo de implementación de ownCloud Keycloak
• Archivos oficiales de despliegue de ownCloud ocis_keycloak
• Guía de administración del servidor Keycloak 26.8
• ownCloud Escalabilidad Infinita: Aspectos de Seguridad