Configuration reference
Use these settings to override the standard installation. Unless shown in full, environment variable names have the prefix ISTARI_DIGITAL_IDENTITY_SERVICE_.
Required
The chart and provisioner supply generated keys, client settings, and the default CORS origin. Supply the database and identity provider credentials.
| Variable | Description |
|---|---|
OIDC_ISSUER | Provider issuer URL without a trailing slash; for Zitadel, https://zitadel.<customer_istari_fqdn>. |
OIDC_CLIENT_ID | Client ID of the Identity Service's application at the upstream identity provider |
OIDC_PRIVATE_KEY | Base64-encoded application-key JSON; required for private_key_jwt. Client-secret methods use OIDC_CLIENT_SECRET. |
BASE_URL | Public Identity Service URL. Defaults to <ISTARI_DIGITAL_API_URL>/identity; the callback is <BASE_URL>/callback. |
SIGNING_KEY_ID / SIGNING_KEY_B64 | Signing key ID and base64-encoded private-key PEM, supplied together by the provisioner. A legacy SIGNING_KEY value takes precedence over both. |
SIGNING_KEY | Optional legacy/manual alternative: base64-encoded signing key JSON. Leave unset on a new provisioner installation. |
DATABASE_URL | PostgreSQL connection string for the service's dedicated database |
CORS_ALLOWED_ORIGINS | Comma-separated browser origins. The chart supplies https://<common.mainFqdn>. An override replaces the list, so include every allowed origin. Keep CORS_ALLOW_ALL disabled in production. |
REGISTRY_PUBLIC_KEY_B64 | Registry public key (base64 PEM), supplied by the provisioner. |
FRONTEND_REDIRECT_URIS | Exact-match frontend redirect allowlist, derived from common.mainFqdn by the chart. |
MCP_REDIRECT_URIS | Exact-match MCP redirect allowlist, derived by the chart. Required even when MCP is not deployed. |
Required When the Chart's Zitadel Import Runs
Supply the management key through the Zitadel Configurator or manual registration. To disable imports, set identity.idpMigration.enabled: false.
See Checking the import for skipped and incomplete imports.
| Variable | Default | Behavior |
|---|---|---|
ZITADEL_MANAGER_KEY | unset | Base64-encoded machine-user JSON key for organization imports and lookup of users who have not signed in. |
Recommended and Optional
| Variable | Default | Behavior |
|---|---|---|
TOKEN_ENCRYPTION_KEY_B64 | Provisioner-generated | Base64 encoding of the encryption key; supplied automatically with the provisioner. |
TOKEN_ENCRYPTION_KEY | unset | Legacy/manual encryption-key override, which takes precedence over TOKEN_ENCRYPTION_KEY_B64. See key formats and rotation. |
ACCESS_TOKEN_TTL | 15m | Access-token lifetime (Go duration). Must be longer than the 5-minute authorization-code lifetime. A shorter or invalid value is fatal at startup. |
OIDC_SCOPES | Provider default | Google and Lastwall use openid profile email. Google adds access_type=offline. Required Zitadel scopes are added automatically. |
JWT_DEFAULT_TENANT_ID | unset | Fallback upstream grouping for Zitadel or Keycloak when the token has no grouping claim. Must match a provider-to-tenant mapping. Entra, Okta, PingFederate, Lastwall, and Google ignore this setting and use local memberships. |
ADMIN_ROLE_KEY | customer_admin | Zitadel role imported as tenant administrator access. |
ENROLLMENT_POLICY | open | For Zitadel, open allows first-time enrollment into a mapped organization. pre-registered-only requires an existing account. Other providers retain their subject or verified-email preparation requirements. |
TENANT_DEACTIVATION_REVOCATION_CASCADE | true | With true, tenant suspension revokes memberships and roles; users with no active tenant lose all remaining grants, including Platform Administrator. With false, those grants and memberships are retained. Users with no active tenant remain suspended in both cases. Explicit membership revocation always revokes that tenant's roles. |
ENFORCE_CLIENT_REGISTRATION | true | Rejects unregistered clients and redirect URIs outside their allowlists. With false, violations are only logged. |
ISTARI_DIGITAL_API_URL | unset | API Gateway base URL (no prefix). When set, BASE_URL and JWT_ISSUER derive to <api>/identity — the recommended configuration |
JWT_ISSUER | derived | iss claim of issued tokens; must match the public URL |
JWT_AUDIENCE | istari-data-platform | aud claim of issued tokens |
OIDC_CLIENT_AUTH_METHOD | private_key_jwt | private_key_jwt requires OIDC_PRIVATE_KEY; client_secret_basic and client_secret_post require OIDC_CLIENT_SECRET. See the provider guide for supported methods. |
OIDC_CLIENT_SECRET | unset | Client secret for the client_secret_* auth methods |
OIDC_SUBJECT_CLAIM | Provider default | Stable ID-token identifier: oid for Entra, sub for the other providers. Normally leave unset; Entra, Okta, PingFederate, Lastwall, and Google reject a different claim. |
REFRESH_TOKEN_TTL | 720h (30 days) | Refresh-token lifetime (Go duration). Must be positive |
MAX_SESSION_DURATION | 720h (30 days) | Session ceiling; refresh tokens never outlive it. Must be positive |
Advanced
| Variable | Default | Behavior |
|---|---|---|
HOST / PORT | 0.0.0.0 / 8000 | Listen address |
IDP_PROVIDER | zitadel | Selected provider: zitadel, keycloak, entra, okta, pingfederate, lastwall, or google. |
DISCOVERY_API_VERSION | 2 | Use 2. Legacy 1 is supported only for Zitadel and Keycloak. |
OIDC_AUTHORIZATION_ENDPOINT, OIDC_TOKEN_ENDPOINT, OIDC_JWKS_URI, OIDC_USERINFO_ENDPOINT, OIDC_END_SESSION_ENDPOINT | unset | Explicit IdP endpoint overrides for providers with broken or absent OIDC discovery; each set value wins over the discovered one. Normally leave unset |
OIDC_ASSERTION_AUDIENCE | unset | Overrides the aud of the service's own client assertions to the upstream identity provider, for providers with strict conventions. Zitadel and Keycloak accept the default |
OIDC_API_BASE_URL | OIDC_ISSUER | Zitadel HTTP API address when it differs from the browser-facing issuer. Must be an absolute HTTP(S) URL; requests retain the issuer's Host header. |
ADDITIONAL_ASSERTION_AUDIENCES | unset | Additional exact-match HTTP(S) audiences for client assertions. The chart includes the gateway URL automatically; malformed entries prevent startup. |
ALLOW_WILDCARD_REDIRECTS | false | Non-production only. Lets a registered redirect-allowlist entry carry a single * inside its https hostname (one DNS label, never a dot) |
AUDIT_SYSLOG_HOST, AUDIT_SYSLOG_PORT, AUDIT_FORMAT, AUDIT_FALLBACK_PATH, AUDIT_TLS_SKIP_VERIFY | Host/path unset; port 6514; format rfc5424; TLS skip false | Forward audit events to a SIEM over TLS syslog; configure a local file fallback if needed. TLS verify skip is for testing only. |
OTEL_ENABLED / OTEL_SERVICE_NAME | false / identity-service | OpenTelemetry traces over OTLP/HTTP; standard OTEL_* exporter variables are honored |
Platform client registration
Identity Service registers the fixed client IDs registry, frontend, and mcp at startup. The provisioner supplies the Registry key pair and MCP service credential; the chart supplies redirect allowlists. For installations without the provisioner, use Manual setup.
Generated Secrets use the release's fullnameOverride (istari by default):
istari-provisioner-registry-credentialsistari-provisioner-mcp-credentialsistari-provisioner-identity-platform-clients
The Registry private key stays in its credential Secret; Identity Service receives only the public key. Frontend and MCP are public clients with redirect allowlists.
Upgrading from suffixed client IDs
Older installations may have suffixed client IDs such as frontend-c3d4. These override the fixed IDs and can fail after an upgrade or database replacement.
Move the services onto the fixed IDs by removing these keys where they are set:
VITE_IDENTITY_ROUTER_CLIENT_IDandVITE_IDENTITY_SERVICE_CLIENT_IDfrom the frontend's secret,istari-frontendISTARI_DIGITAL_IDENTITY_SERVICE_CLIENT_IDfrom the MCP service's secret,istari-mcp
Setting them to frontend and mcp instead works too. Then restart both Deployments: kubectl rollout restart deployment/istari-frontend deployment/istari-mcp.
Overriding the redirect allowlists
Set ISTARI_DIGITAL_IDENTITY_SERVICE_FRONTEND_REDIRECT_URIS or ISTARI_DIGITAL_IDENTITY_SERVICE_MCP_REDIRECT_URIS in istari-identity. Each override replaces the chart's comma-separated list. Include every permitted URI with exact path, case, and trailing slash; wildcards are not accepted by default. Restart Identity Service after changes. Redirects outside the allowlist are refused.
Provisioner in a separate release
If your deployment runs the provisioner in a separate Helm release, set provisioner.enabled: false and provisioner.external: true in the consuming release. Both releases must use the same namespace and fullnameOverride so the consumer mounts the generated Secrets. This still uses the provisioner; keep its state and generated Secrets available to the consuming services.