OIDC Integration Testing Strategy

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

Theory

  • Quollix acts as the OIDC provider. Apps act as OIDC clients.
  • Apps started by Quollix resolve the OIDC provider via the domain quollix.<host> inside the shared Docker network.
  • Many OIDC clients require the provider’s endpoints to be served over HTTPS with a valid TLS certificate.
  • Quollix’s well-known endpoint is available at quollix.<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.
  • Quollix 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 Quollix 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 Quollix. 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 quollix.test.quollix.org → 127.0.0.1)
  2. Add your app (Docker Compose YAML) to the test-apps folder.
  3. Start Quollix in PROD mode using the CI runner.
  4. Open the settings in the Quollix UI and set your test domain as the host. For example, we use test.quollix.org.
  5. Generate a TLS certificate via the DNS-01 challenge.
  6. Download the generated certificate (certificate.pem).
  7. Stop Quollix and restart it in TEST mode.
  8. Set the host again and upload the previously downloaded certificate.
  9. Restart your browser and revisit Quollix under quollix.<test-domain> (for example quollix.test.quollix.org).
  10. Install and start your app via the mocked App Store and verify that the OIDC login flow works as expected.