OpenCms documentation
OpenCms documentation

The OpenCms Secret Provider

The OpenCms Secret Provider is used to securely store sensitive configuration data such as API keys, passwords, or access tokens. These secrets can be accessed by templates, Java code, or OpenCms internals (e.g., integrations with external systems).

Secrets are stored as key-value pairs in a file on the server’s real file system. Optionally, all values can be encrypted using a password with strong AES encryption.

The secret provider is configured in the OpenCms configuration file WEB-INF/config/opencms-system.xml

Use the <secret-store> element below <subscription-manager>:

<secret-store class="org.opencms.security.CmsRfsSecretStore">
  <param name="path">/etc/secrets.properties</param>
  <param name="password">...</param>
</secret-store>
  • class: the class of the secret provider implementation, currently only org.opencms.security.CmsRfsSecretStore is supported
  • path: absolute path to the secrets file in the servers real file system (e.g. /etc/secrets.properties)
  • password (optional): the password used to encrypt/decrypt the stored values (with AES encryption)

Secrets can be accessed via the OpenCms singleton:

String value = OpenCms.getSecretProvider().getSecret("secret-key");

If the key does not exist, null is returned.

It is not possible to list all existing secrets. You must always request a specific key.

The helper class org.opencms.util.CmsSecretUtil provides convenient access:

  • CmsSecretUtil.getSecret("secret-key");
  • CmsSecretUtil.getSecretForUri("secret-key", CmsObject);
  • CmsSecretUtil.getSecretForUri("secret-key", CmsObject, "/vfs/root/path/");

You can access the secrets via the standard context bean:

${cms.getSecretForUri("secret-key")}

The method getSecretForUri allows resolving secrets dynamically based on the current request URI. This is useful when different subsites or sections require different credentials (e.g., API keys per site).

Given a secret-key, OpenCms resolves the secret as follows:

  • Determine the current request path (or the explicitly provided VFS path)
  • Traverse all parent sitemap root paths, starting from the most specific to the least specific
  • For each path, try to resolve a key in this format:
    <secret-key>.<vfs-root-path>
  • Return the first matching key found
  • If no path-specific key exists, fall back to the global key <secret-key>
  • If still not found: return null

The lookup always proceeds from most specific to most general.

Example request path: /sites/default/mercury-demo-de/index.html

Lookup order:

  1. myapikey./sites/default/mercury-demo-de
  2. myapikey./sites/default
  3. myapikey (global fallback)

Example secret keys:

myapikey=test-secret-global
myapikey./sites/default=test-secret-default
myapikey./sites/default/mercury-demo-de=test-secret-de
Request Path

Returned Secret

/sites/default/index.html

test-secret-default

/sites/default/mercury-demo-de/index.html

test-secret-de

any other path

test-secret-global

  • Always use the full VFS root path in the key (e.g. /sites/default/mercury-demo-de)
  • Do not include a trailing slash
  • The site folder is always considered, even if it is not explicitly defined as a sitemap