OIDC Integration Testing Strategy

This article describes the recommended strategy for testing OIDC integrations in a local development setup between apps and Ocelot-Cloud.

Theory

Ocelot-Cloud acts as the OIDC provider. Apps act as OIDC clients.
Apps started by Ocelot Cloud resolve the OIDC provider via the domain ocelotcloud.<host> inside the shared Docker network.
Many OIDC clients require the provider’s endpoints to be served over HTTPS with a valid, signed certificate.
Ocelot Cloud’s well-known endpoint is available at ocelotcloud.<host>/.well-known/openid-configuration.
While some apps may allow self-signed certificates, using a real certificate is the safest option and avoids the need to relax or disable client-side TLS verification.
Ocelot-Cloud can automatically generate and manage certificates for a test domain, making it easy to reproduce a production-like setup locally.

Add your app (Docker Compose YAML) to the test-apps folder.
Start Ocelot-Cloud in PROD mode using the CI runner.
Open the settings in the Ocelot-Cloud UI and set your test domain as the host. For example, we use test.ocelot-cloud.org.
Generate a TLS certificate via the DNS-01 challenge, following the instructions in the documentation.
Download the generated certificate (certificate.pem).
Stop Ocelot-Cloud and restart it in TEST mode.
Set the host again and upload the previously downloaded certificate.
Restart your browser and revisit Ocelot-Cloud under ocelotcloud.<test-domain> (for example ocelotcloud.test.ocelot-cloud.org).
Install and start your app via the mocked App Store and verify that the OIDC login flow works as expected.

The initial certificate generation must be done in PROD mode, as this generates a real, publicly trusted certificate.
TEST mode enables loading apps from the test-apps folder and persists the certificate on the host filesystem for reuse.
Restarting the browser may be necessary to ensure cached certificates are cleared and the new certificate is used.