OIDC Provider Configuration#

Sure's OpenID Connect (OIDC) provider configuration covers how OIDC issuers are declared, how client credentials are resolved, and how SSL/TLS is handled for discovery and token exchange. It is distinct from the SSO authentication flow (session handling, JIT provisioning, role mapping) — this article covers the wiring layer that makes a provider available to OmniAuth.

Configuration Sources#

OIDC providers can be configured in two ways, controlled by the db_sso_providers Flipper feature flag:

1. YAML — config/auth.yml, loaded via Rails config_for(:auth) 1
2. Database — SsoProvider records, loaded when the Flipper flag is on 2

ProviderLoader.load_providers abstracts the source, caches the result for 5 minutes, and falls back to YAML if the database is unavailable. Call ProviderLoader.clear_cache after updating providers in the admin UI.

Required Fields#

For strategy openid_connect, all four of the following must be present or the provider is silently skipped during OmniAuth initialization 3:

The config file reads these from environment variables by default 4. For additional providers beyond the default, use the naming pattern OIDC_<UPPERCASE_NAME>_* (e.g., OIDC_KEYCLOAK_ISSUER) documented in the YAML comments 5.

ProviderOptionsBuilder#

Oidc::ProviderOptionsBuilder.call(cfg) is the single place that assembles the OmniAuth option hash passed to :openid_connect. Key behaviors:

• Discovery: always true — the builder assumes the IdP exposes /.well-known/openid-configuration 6
• PKCE: always enabled 7
• Response type: code 8
• Default scopes: [:openid, :email, :profile]; override via settings.scopes 9
• Groups claim: when settings.role_mapping is set or groups is in the scope list, claims parameters requesting groups in both id_token and userinfo are appended as extra_authorize_params 10
• Prompt: optional, set via settings.prompt 11

SSL options from Rails.configuration.x.ssl are injected directly into client_options.ssl.

SSL/TLS Configuration#

SSL settings are global to the Rails process and configured at boot by config/initializers/00_ssl.rb.

When SSL_CA_FILE is valid, the initializer merges it with system CAs into a combined bundle at tmp/ssl_ca_bundle.pem and sets ENV["SSL_CERT_FILE"] globally. This is intentional — it ensures gems like openid_connect that bypass SslConfigurable still trust the custom CA during OIDC discovery 12.

The SslConfigurable concern provides helpers (faraday_ssl_options, httparty_ssl_options, net_http_verify_mode) for HTTP clients that do go through Rails configuration. SsoProvider extends this concern for its Faraday-based discovery validation .

Security note: SSL_VERIFY=false removes MITM protection and is not safe for production. The recommended path for self-hosted deployments with internal CAs is SSL_CA_FILE with a PEM certificate.

HTTP-Only Providers#

The SsoProvider model validates issuer URLs permissively — accepting both http:// and https:// schemes 14. However, the underlying openid_connect gem enforces HTTPS for discovery and token requests. There is no built-in option to force HTTP-mode discovery; SSL_VERIFY=false only relaxes certificate validation, it does not downgrade the transport protocol.

Key Files#