Current state

com.top_logic/src/main/webapp/WEB-INF/conf/ldapConf.config.xml defines the security device LdapSecurity (LDAPAuthenticationAccessDevice) entirely through %LDAP_*% aliases. The accompanying ldapConf.xml sets these aliases to fixed placeholder values:

%LDAP_URL%              ldap://ldap.your.domain:389
%LDAP_PRINCIPAL%        you@your.domain
%LDAP_CREDENTIAL%       your-password
%LDAP_BASE_DN%          DC=YourDC
%LDAP_FILTER%           (objectClass=Person)
%LDAP_GROUP_1%          CN=YourCN,DC=YourDC
%LDAP_GROUP_2%          (empty)
%LDAP_GROUP_3%          (empty)
%LDAP_ALLOW_PWD_CHANGE% false
%LDAP_NESTED_GROUPS%    false
%LDAP_MAPPING_ALL%      /WEB-INF/database/ldap/all-mapping.properties
%LDAP_MAPPING_PERSON%   /WEB-INF/database/ldap/person-mapping.properties
%LDAP_MAPPING_GROUP%    /WEB-INF/database/ldap/group-mapping.properties
%LDAP_MFA_REQUIREMENT%  optional

An application that authenticates against an LDAP therefore needs, besides the metaConf.txt entry ldapConf.xml, an alias file of its own that overrides these placeholders. Usually that file holds environment-specific values (host, base DN, groups) and the bind credential, so it either gets committed with them or has to re-implement the indirection with ${env:...} itself. Example of such a file, which every application currently has to write:

<entry name="%LDAP_URL%" value="${env:ldap_url}"/>
<entry name="%LDAP_CREDENTIAL%" value="${env:ldap_credential}"/>
...

Proposal

Let ldapConf.xml read every alias from a system property or environment variable, keeping the current values as defaults:

<entry name="%LDAP_URL%" value="${env:ldap_url:ldap://ldap.your.domain:389}"/>
<entry name="%LDAP_PRINCIPAL%" value="${env:ldap_principal:you@your.domain}"/>
<entry name="%LDAP_CREDENTIAL%" value="${env:ldap_credential:your-password}"/>
<entry name="%LDAP_BASE_DN%" value="${env:ldap_base_dn:DC=YourDC}"/>
<entry name="%LDAP_FILTER%" value="${env:ldap_filter:(objectClass=Person)}"/>
<entry name="%LDAP_GROUP_1%" value="${env:ldap_group_1:CN=YourCN,DC=YourDC}"/>
<entry name="%LDAP_GROUP_2%" value="${env:ldap_group_2:}"/>
<entry name="%LDAP_GROUP_3%" value="${env:ldap_group_3:}"/>
<entry name="%LDAP_ALLOW_PWD_CHANGE%" value="${env:ldap_allow_pwd_change:false}"/>
<entry name="%LDAP_NESTED_GROUPS%" value="${env:ldap_nested_groups:false}"/>
<entry name="%LDAP_MAPPING_ALL%" value="${env:ldap_mapping_all:/WEB-INF/database/ldap/all-mapping.properties}"/>
<entry name="%LDAP_MAPPING_PERSON%" value="${env:ldap_mapping_person:/WEB-INF/database/ldap/person-mapping.properties}"/>
<entry name="%LDAP_MAPPING_GROUP%" value="${env:ldap_mapping_group:/WEB-INF/database/ldap/group-mapping.properties}"/>
<entry name="%LDAP_MFA_REQUIREMENT%" value="${env:ldap_mfa_requirement:optional}"/>

(DefaultAliasManager.ENVIRONMENT_VARIABLE accepts any default value without an unescaped }, including parentheses, commas and colons.)

An application then enables LDAP with the single metaConf.txt entry ldapConf.xml (e.g. in a deploy aspect) and passes the values per deployment as -Dldap_url=... etc. or as environment variables; the credential can be supplied from a secret store of the deployment. Applications that override the aliases in a later configuration file keep working, since a later alias entry wins.

The documentation page of the LDAP connection (doc:ldapConnection, see #25771) should name the properties.

Use case

The release notes application (BOS/tl-releasenotes, deploy aspect with-ldap) currently carries such an alias file ldap.xml that only maps all %LDAP_*% aliases to ${env:ldap_*}; with this change the file can be removed and the aspect reduces to its metaConf.txt.