Centralized Platform Settings

Overview

The Platform Settings component provides a mechanism for the system to retrieve dynamic configuration from a central, re<customer>e service. This allows for platform-wide settings to be managed and updated without requiring a new deployment of the product.

This component is responsible for:

• Polling a re<customer>e endpoint for settings in SaaS deployments.
• Validating the authenticity and integrity of the retrieved settings, which are provided as a signed JSON Web Token (JWT).
• Persisting the validated settings to the local database.
• Providing the current settings to other components within the platform.
• Enforcing data residency rules by comparing the platform's runtime region against a centrally-defined region.

In self-hosted (BYOC) deployments, the components for reading settings are active, but the client that polls the re<customer>e service is not invoked. In this mode, the system uses product defaults.

How it works

The platform settings system operates on a pull-based model. The lifecycle and data flow differ based on the deployment model (SaaS vs. self-hosted).

flowchart TD
    subgraph "SaaS Deployment Only"
        A(Scheduler)
    end

    subgraph "Platform Components"
        B(Settings Client)
        D(JWT Verifier)
        E(Settings Store)
        G(Settings Provider)
        H(Data Residency Guard)
    end

    subgraph "External Systems"
        C(Re<customer>e Settings Service)
        F(Database)
    end

    subgraph "Internal Consumers"
        I(Other Platform Services)
    end

    A -->|1. Triggers periodic poll| B
    B -->|2. Requests settings with credentials| C
    C -->|3. Returns signed settings (JWT)| B
    B -->|4. Validates JWT signature| D
    B -->|5. Persists validated settings| E
    E -->|6. Writes to| F
    G -->|7. Reads current settings from| E
    H -->|8. Consumes settings for checks| G
    I -->|Consumes settings for behavior| G

    style A fill:#f9f,stroke:#333,stroke-width:2px

1. Polling (SaaS Only): In a SaaS environment, a scheduler periodically triggers the PlatformSettingsClient. This client is responsible for initiating the settings retrieval process.
2. Request: The PlatformSettingsClient authenticates to the re<customer>e settings service by sending the platform's productId, installationId, and the raw license JWT.
3. Response: The re<customer>e service returns a signed JWT containing the platform settings.
4. Verification: The SpecariaSettingsJwtVerifier validates the signature of the incoming JWT against a known JSON Web Key Set (JWKS). This ensures the settings are authentic and have not been tampered with.
5. Persistence: Upon successful verification, the PlatformSettingsClient passes the settings to the PlatformSettingsStore. The JdbcPlatformSettingsStore implementation writes the settings to the platform's database. This store also interfaces with an AuditRepository to record specific changes, such as those related to support access.
6. Provisioning: Other components within the system access the configuration via the PlatformSettingsProvider, which reads the most recently persisted settings from the store. This ensures that even if a poll fails, the system continues to operate with the last known good configuration.

Data Residency Enforcement

A key consumer of platform settings is the RegionResidencyGuard. This component enforces data residency requirements.

• It compares the platform's own runtime region, determined by the RuntimeRegionProvider, against the region.selected value retrieved from the platform settings.
• In SaaS mode, if the SaasCapability is enabled and there is a mismatch between the runtime region and the configured region, the guard can block write operations to prevent data from being stored in an incorrect location.
• In self-hosted (BYOC) mode, or if the SaaS capability is not licensed, the RegionResidencyGuard is a no-op and always permits operations, regardless of the settings.

Configuration

The platform's runtime region is configured via system properties or environment variables. This value is used by the RegionResidencyGuard for data residency checks.

The system resolves the region using the following order of precedence:

1. s2r.capacity.region system property
2. s2r.region system property
3. S2R_REGION environment variable
4. The hardcoded default value of me-west1 if none of the above are set or are blank.

Example

To set the runtime region to eu-central-1, you can use either a system property or an environment variable.

Set via a system property at startup:

java -Ds2r.capacity.region=eu-central-1 -jar application.jar

Set via an environment variable:

export S2R_REGION="eu-central-1"
java -jar application.jar

Troubleshooting

Write Operations Blocked in SaaS Mode

• Condition: API requests that perform write operations are rejected.
• Cause: This can occur in a SaaS deployment if the RegionResidencyGuard detects a mismatch between the platform's runtime region (e.g., me-west1) and the region specified in the centrally-managed platform settings (e.g., region.selected is us-east-2). The guard blocks writes to enforce data residency policy.
• Resolution: Ensure the platform is deployed in the region specified by the central configuration.

Platform Settings Are Not Updating

• Condition: Changes made in the central settings service are not reflected in the platform's behavior.
• Cause: The PlatformSettingsClient may be failing to retrieve or validate new settings. Potential causes include:
  • Network connectivity issues preventing the client from reaching the re<customer>e settings service.
  • The HTTP request timing out. The client uses a fixed 15-second timeout.
  • An invalid or expired license JWT, causing the re<customer>e service to reject the request.
  • The returned settings JWT failing signature validation.
• Impact: The platform will continue to use the last known good configuration stored in its database. New settings will not be applied until a poll succeeds.

See Also

• Product Identity: The PlatformSettingsClient uses the product identity to authenticate with the re<customer>e settings service.
• Licensing: The raw license JWT is a required credential for fetching settings. The RegionResidencyGuard's behavior is also gated by the SaasCapability from the license.

All SOAP-to-REST docs