Skip to content

External service settings

Settings for email, Jira, sessions, the identity provider, the directory, and the analytics backends. The integration switches are at the end of this page. Procedures are in Secrets and integrations.

email

Setting Default Explanation
email.send_enabled false Enables email delivery. Keep false until a valid SMTP service and sender address are configured.
email.smtp_server smtp.example.org SMTP server hostname. Replace the example host when email is enabled.
email.sender sites@example.org Sender address used for platform messages.
email.domain example.org Domain used to build user email addresses when no directory supplies them. It does not set trusted browser domains.
email.reporter support@example.org Reporter or support email address shown in messages.

jira

Setting Default Explanation
jira.api_url https://jira.example.org/rest/api/2/ Jira REST API base URL. Replace the example value when Jira notifications are enabled.
jira.api_username Empty Jira API account name.
jira.api_token Empty; use JIRA_API_TOKEN Secret Jira API token. Do not put the token in a values file.
jira.reporter Empty Jira reporter user name.
jira.project Empty Jira project key or name used for created issues.
jira.component Empty Jira component assigned to created issues.
jira.issue_type Task Jira issue type used for created issues.
jira.initial_transition [] Candidate Jira transition names used when an issue is opened. The first available configured transition is used.
jira.final_transition ["Resolve", "Resolve/Reject", "Close Issue"] Candidate Jira transition names used to complete an issue. Configure names that exist in your Jira workflow.

session

Setting Default Explanation
session.secret_key Empty; required Encryption key for session cookies and session data. Startup fails if the key is missing or shorter than 32 bytes. Generate it with openssl rand -base64 48. Supply SESSION_SECRET_KEY through sites-secrets; keep the value stable across Hub replicas and restarts.
session.refresh_each_request true Refreshes session data on each request. Disable only if the session behaviour has been tested for your deployment.
session.permanent_lifetime 259200 seconds (72 hours) Lifetime of a permanent session.

oidc

Setting Default Explanation
oidc.cookie_expire 12h OpenID Connect (OIDC) session cookie expiry as a duration string, for example 30m, 1h, or 1d.
oidc.cookie_refresh 2h OIDC session refresh interval as a duration string. Keep it shorter than the expiry.
oidc.scopes ["openid", "email"] Scopes requested from the identity provider. Add only scopes the platform needs and the provider permits.
oidc.token_type_hint access_token Token type hint sent to the identity provider for introspection.
oidc.issuer_url Empty OIDC issuer URL. The platform discovers endpoints from <issuer_url>/.well-known/openid-configuration. Always required. If the identity provider supports .well-known discovery, this is the only endpoint setting that you must provide; the other endpoint URLs are not necessary. The platform also checks that the issuer in the discovery document matches this value.
oidc.authorization_url Empty Authorization endpoint. It replaces the discovered endpoint and disables OAuth2 Proxy native discovery. Part of the explicit endpoint set.
oidc.user_info_url Empty User-info endpoint. It replaces the discovered endpoint. Part of the explicit endpoint set.
oidc.account_url Empty User account-management page. This is not the OIDC user-info endpoint.
oidc.token_url Empty Token endpoint. It replaces the discovered endpoint. Part of the explicit endpoint set.
oidc.introspection_url Empty Token introspection endpoint. It replaces the discovered endpoint. This setting alone does not disable OAuth2 Proxy native discovery. Part of the explicit endpoint set.
oidc.revocation_url Empty Token revocation endpoint. It replaces the discovered endpoint. Part of the explicit endpoint set.
oidc.jwks_url Empty JSON Web Key Set (JWKS) endpoint. It replaces the discovered endpoint and disables OAuth2 Proxy native discovery. Part of the explicit endpoint set.
oidc.logout_url Empty Optional logout endpoint. It replaces the discovered endpoint. If you use explicit endpoints and leave it empty, logout clears only the local session.
oidc.client_id Empty OIDC client ID. Provide the OIDC_CLIENT_ID key in oidc-secrets; do not rely on a committed configuration value for credentials.
oidc.client_secret Empty; use OIDC_CLIENT_SECRET Secret OIDC client secret. Keep it in oidc-secrets.
oidc.extra_audiences ["sites"] Token audiences that the platform accepts in addition to the client ID. The Hub, the OAuth2 Proxy, and the Site proxy use this list. Set it to your own values, or to [] to accept only the client ID.
oidc.redirect_uri Empty Callback URL registered with the identity provider. It must match the public host and callback path.

For the normal issuer-first setup and the effects of endpoint overrides, see secrets and integrations.

ldap

Setting Default Explanation
ldap.connection ldap://directory.example.org LDAP connection URL, including scheme and port when needed. Use LDAPS or another protected transport for credentials.
ldap.start_tls false Upgrade an ldap:// connection to TLS with StartTLS before the bind. Do not set it with ldaps://, which is already encrypted. An ldap:// connection with start_tls false produces the ldap-cleartext consistency warning, because the bind password crosses the network in clear text.
ldap.username Empty Bind identity used to search the directory.
ldap.password Empty; use LDAP_PASSWORD Secret Bind password. Keep it in sites-secrets.
ldap.search_base [] List of directory base DNs to search. Configure one or more values for the directory tree.
ldap.search_filter Empty LDAP search filter used to find users, for example (uid={0}). Required when LDAP is the selected directory provider.
ldap.attributes_username cn LDAP attribute mapped to the user's login name.
ldap.attributes_name displayName LDAP attribute mapped to the user's display name.
ldap.attributes_email mail LDAP attribute mapped to the user's email address.

directory

These settings apply to any directory provider. Do not place these fields under ldap.

Setting Default Explanation
directory.default_users [] Users always included in the user list, in addition to directory users. Each entry is [username, display name, email].
directory.validate_usernames false Restricts entered user names to the directory user list. The application turns this off when the directory integration is none.
directory.policies_list [] Roles, groups, or policies that users can select in access filters. Use values recognised by the identity provider and organisation.

splunk

Setting Default Explanation
splunk.base_url https://splunk.example.org Splunk service base URL.
splunk.search_endpoint /en-GB/app/search/search UI search path appended to base_url for links to Splunk results.
splunk.api_search_endpoint :8089/servicesNS/sites/search/search/jobs/export API search path appended to base_url for analytics queries.
splunk.api_username Empty Splunk API account name.
splunk.api_password Empty; use SPLUNK_API_PASSWORD Secret Splunk API password. Keep it in sites-secrets.
splunk.query_index apps_kubernetes Splunk index queried for analytics.
splunk.query_source_type otel Splunk source type filter used by analytics queries.
splunk.query_fields {"k8s.container.name": "site-proxy"} Extra key/value filters added to the query. Set the field names to match indexed event fields.
splunk.verify_tls true Verifies the Splunk API TLS certificate. The application sets it to false when dev is true.

opensearch

Setting Default Explanation
opensearch.base_url https://opensearch.example.org OpenSearch service base URL.
opensearch.search_endpoint /_dashboards/app/discover#/ Dashboards path appended to base_url for search links.
opensearch.api_search_endpoint :9200 REST API path or port appended to base_url for analytics queries.
opensearch.api_username Empty OpenSearch API account name for Basic authentication.
opensearch.api_password Empty; use OPENSEARCH_API_PASSWORD Secret OpenSearch API password. Keep it in sites-secrets.
opensearch.query_index nginx-logs-* Index pattern queried for analytics.
opensearch.query_source_type Empty Optional source-type filter value. It is used only when query_source_type_field is also set.
opensearch.query_source_type_field Empty Index field matched to query_source_type, for example source_type, event.dataset, or tag.
opensearch.query_fields {"kubernetes.container.name": "site-proxy"} Additional exact-match term filters added to analytics queries.
opensearch.timestamp_field @timestamp Index field that contains the event time.
opensearch.verify_tls true Verifies the OpenSearch API TLS certificate. The application sets it to false when dev is true.

integrations

Each feature has the same three main settings. The defaults disable all integrations. Use provider IDs supported for that feature.

Setting Default Explanation
integrations.<feature>.providers ["none"] List of enabled provider IDs. Use ["none"] to disable a feature. For analytics, supported IDs are none, splunk, and opensearch; for metrics, none and prometheus; for directory, none and ldap; for notifications, none, email, and jira.
integrations.<feature>.default none Provider used for normal dispatch and template selection. It must be present in providers. Notifications can list more than one provider; listed providers can receive broadcasts.
integrations.<feature>.required false Marks the integration as mission-critical for operators: a failed reachability probe logs as ERROR instead of WARNING, and the flag shows on the Hub dependencies page. It does not change response codes or degradation: dependent endpoints return HTTP 503 when the feature is off or unreachable, whether or not this flag is set.

Set <feature> to analytics, metrics, directory, or notifications. For a single provider, set providers: [<id>] and default: <id>. Provider configuration must be complete for the selected integrations. For example, ldap needs its search base and filter, email needs a working SMTP setup, and analytics needs its endpoint and credentials. The application checks some invalid combinations at startup and logs configuration warnings in the Hub dependency view.