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.

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. Start Quollix in PROD mode using the CI runner.
  3. Open the settings in the Quollix UI and set your test domain as the host. For example, we use test.quollix.org.
  4. Generate a TLS certificate via the DNS-01 challenge.
  5. Download the generated certificate (certificate.pem).
  6. Stop Quollix and restart it in TEST mode.
  7. Set the host again and upload the previously downloaded certificate.
  8. Restart your browser and revisit Quollix under quollix.<test-domain> (for example quollix.test.quollix.org).
  9. Install and start your app via the mocked App Store and verify that the OIDC login flow works as expected.