OpenCloud integration issues

Ocelot-Cloud acts as the reverse proxy in front of OpenCloud. OpenCloud uses a mandatory OpenID Connect (OIDC) authentication flow. Even when using local users (IDM), OpenCloud always authenticates via its internal OIDC provider. Because of this, OpenCloud must be able to reach its own OIDC discovery endpoint at the URL defined by OC_URL.

During authentication, OpenCloud performs OIDC discovery and token validation requests from its own container to the URL defined by OC_URL. These requests are routed through the reverse proxy (Ocelot-Cloud) and then forwarded back to the OpenCloud service itself. This internal request loop only happens during authentication, but it is the source of most issues in local, containerized setups.

Why this becomes a problem in local development

In production, OC_URL usually points to a publicly reachable domain. In local development, however, the host is always localhost, so the configuration becomes:

OC_URL=https://opencloud.${HOST} → OC_URL=https://opencloud.localhost 

During login, OpenCloud performs internal HTTP requests to:

https://opencloud.localhost/.well-known/openid-configuration

These requests are not sent by the browser, but by the OpenCloud service itself from inside its Docker container. In this context, localhost refers only to the container, not the host and not other containers, which prevents OpenCloud from reaching its own OIDC endpoint without additional configuration.

Docker network alias solution

To solve this, we assign a network alias when attaching the Ocelot-Cloud container to the OpenCloud Docker network.

${APP}.${HOST} → opencloud.localhost

This ensures that, inside Docker, opencloud.localhost resolves to the reverse proxy container, not to 127.0.0.1. This pattern is generic and reused for other apps: the alias always matches the externally advertised application URL.

The alias is derived from placeholders used throughout the system. In local development, ${APP} resolves to opencloud and ${HOST} resolves to localhost, resulting in opencloud.localhost. This keeps local and production configurations structurally identical while allowing Docker-internal name resolution.

Port alignment requirement

Another critical requirement is port alignment. OpenCloud connects to its OIDC issuer using the URL implied by OC_URL. Since OC_URL uses https://, OpenCloud implicitly connects on port 443, regardless of how traffic is forwarded internally. For OpenCloud’s internal OIDC calls to succeed, the reverse proxy must therefore listen on port 443 inside the Docker network. This is why the Ocelot-Cloud binary was configured to bind directly to port 443 inside the container.

Reverse proxy security considerations

Because OpenCloud handles authentication and authorization internally, any additional authentication enforced by the reverse proxy will interfere with the OIDC flow. For this reason, the access policy of the OpenCloud application must be set to Public. This is also desirable from a client perspective as OpenCloud desktop and mobile clients must be able to connect directly to the OpenCloud service without being blocked by reverse-proxy-level authentication.