Protected Custom Settings

What makes protected custom settings different

Protected custom settings are a Salesforce packaging mechanism, not just a convenience for storing values. The key distinction is that the package can read the values at runtime, while subscriber org code and packaged metadata consumers cannot inspect them directly. That separation matters when a managed package needs private configuration without exposing it as part of the customer-facing package surface.

How they work inside a managed package

In practice, protected custom settings behave like package-private configuration. They let the vendor ship operational values with the package while limiting visibility outside the package boundary. That is useful for internal endpoints, feature flags, partner-specific logic, or other values that should be available to the package logic but not disclosed to subscribers or downstream consumers of the packaged metadata.

The important design point is that protection applies to the setting value, not to every possible use of the package. The package still has to be designed so that runtime code only relies on values it can legitimately read, and so that sensitive configuration is not duplicated in unprotected metadata, documentation, or installation defaults.

Why this matters for packaging and configuration hygiene

Protected custom settings help reduce accidental disclosure of configuration data across an installed package boundary. They also support cleaner separation between what a package needs to execute and what a subscriber should be able to view or override. That makes them especially useful when the same package is installed in many orgs and the vendor wants a stable internal configuration model.

They are not a substitute for broader secret handling discipline. If a value is truly sensitive, teams still need to think about whether it belongs in package metadata at all, whether it should be rotated externally, and whether the package design creates any unnecessary dependency on a hidden value that could complicate support or change management.

Common implementation pitfalls

Protected custom settings are sometimes treated as a general hiding mechanism, but they only solve a narrow packaging problem. They do not make bad configuration safe, they do not validate data quality, and they do not automatically protect values that are mirrored into logs, debug output, client-side code, or integration payloads.

Another common mistake is assuming that protected means immutable. Package maintainers still need a clear ownership model for updates, default values, environment-specific overrides, and support workflows. If the package depends on a hidden setting, the team should be deliberate about how changes are introduced and how failures are diagnosed when the hidden value is missing or incorrect.

Risk and Threat Considerations

Protected custom settings reduce exposure, but the main risk is false confidence. If a package relies on hidden configuration for security-relevant behavior, any accidental disclosure, weak update process, or reuse of the same value across orgs can create a predictable failure point.

Failure mechanism: The setting can be copied into less-protected places, exposed through operational tooling, or become a single point of dependency for package logic, which turns a private configuration choice into a control weakness.

Impact: Exposure can reveal internal package behavior, weaken tenant separation, or allow misuse of configuration-dependent code paths, especially when the value influences access, routing, or integration behavior.

Practitioner Guidance

Why practitioners should care: Protected custom settings are most useful when a managed package needs private runtime configuration without leaking it into the subscriber experience. Treat them as a packaging control with clear boundaries, not as a general-purpose secret store.

Governance implication: Define who owns the hidden values, how they are changed, and what operational checks confirm that the package still behaves correctly after an update. That avoids configuration drift and makes support more predictable.

Practitioner takeaway: Use protected custom settings to reduce unnecessary disclosure, but keep sensitive values out of the package design whenever a more dedicated secret-management pattern is available.

Related resources from NHI Mgmt Group

• What breaks when a custom SSO implementation is too tightly coupled to tenant-specific IdP settings?
• Why do protected branch and fork settings still leave room for pipeline compromise?
• How should teams control custom GPT access to protected APIs?
• Custom Data Retention Settings