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 TLS 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 valid 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.

Test Apps

For integration testing, apps are provided as Docker Compose YAML files located in the test-apps folder on the host system. When Ocelot-Cloud is running in TEST mode, these apps are loaded into an App Store mock so that they can be installed as if from a real App Store. This enables local development and testing of app integrations before publishing them to the real App Store.

In TEST mode, the GUI provides a Reload button on the App Store page that refreshes the test apps from the host file system into the App Store Mock. This allows for quick iteration on app definitions without restarting Ocelot-Cloud. Typical workflow:

  1. Modify a test app’s Docker Compose YAML file in the test-apps folder
  2. Uninstall the app from the Installed Apps page
  3. Open the App Store and click Reload Test Apps
  4. Install the updated version of the app
  5. Check whether integration works as expected
  6. Repeat as needed

Practice

  1. Add a DNS entry for your test domain in /etc/hosts (e.g. we use ocelotcloud.test.ocelot-cloud.org → 127.0.0.1)
  2. Add your app (Docker Compose YAML) to the test-apps folder.
  3. Start Ocelot-Cloud in PROD mode using the CI runner.
  4. Open the settings in the Ocelot-Cloud UI and set your test domain as the host. For example, we use test.ocelot-cloud.org.
  5. Generate a TLS certificate via the DNS-01 challenge.
  6. Download the generated certificate (certificate.pem).
  7. Stop Ocelot-Cloud and restart it in TEST mode.
  8. Set the host again and upload the previously downloaded certificate.
  9. Restart your browser and revisit Ocelot-Cloud under ocelotcloud.<test-domain> (for example ocelotcloud.test.ocelot-cloud.org).
  10. Install and start your app via the mocked App Store and verify that the OIDC login flow works as expected.