Configure Credentials
HCL Digital Experience 9.5 uses several credentials in its deployment to manage access between applications and from outside the container deployment.
Adjusting default credentials
You can adjust the default credentials that HCL Digital Experience 9.5 is using by adding the following syntax to your custom-values.yaml file and changing the values you need:
# Security related configuration, e.g. default credentials
security:
# Security configuration for Core
core:
# Credentials used for IBM WebSphere Application Server administrative access.
# The credentials defined in these values define the WebSphere Application Server's primary administrative user. The user gets created if necessary and/or the password is set to the current value.
# - If the WAS admin credentials were changed by any other means than through the helm values, the currently active credentials need to be entered as the values for wasUser and wasPassword.
# - If LDAP is configured as the user repository, the WebSphere Application Server admin user won't be applied automatically and LDAP has the authority over the credentials. Whenever the credentials are changed in LDAP, the values for wasUser and wasPassword need to be manually updated accordingly.
wasUser: "wpsadmin"
wasPassword: "wpsadmin"
# Credentials used for HCL Digital Experience Core administrative access.
# The credentials defined in these values define the HCL Digital Experience Core administrative user. The user gets created if necessary and/or the password is set to the current value.
# - If LDAP is configured as the user repository, the WebSphere Application Server admin user won't be applied automatically and LDAP has the authority over the credentials. Whenever the credentials are changed in LDAP, the values for wpsUser and wpsPassword need to be manually updated accordingly.
wpsUser: "wpsadmin"
wpsPassword: "wpsadmin"
# Credentials used for Config Wizard administrative access. This only takes effect when "configuration.core.tuning.configWizard" is enabled.
# The credentials defined in these values define the WebSphere Application Server primary administrative user. The user gets created if necessary and/or the password is set to the current value.
# This will also map the user as the user for Config Wizard and dxconnect (for dxclient)
# - If the Config Wizard admin credentials were changed by any other means than through the helm values, the currently active credentials need to be entered as the values for configWizardUser and configWizardPassword.
# - If LDAP is configured as the user repository, the WebSphere Application Server admin user won't be applied automatically and LDAP has the authority over the credentials. Whenever the credentials are changed in LDAP, the values for configWizardUser and configWizardPassword need to be manually updated accordingly.
configWizardUser: "wpsadmin"
configWizardPassword: "wpsadmin"
# Security configuration for Digital Asset Management
digitalAssetManagement:
# Credentials used by Digital Asset Management to access the persistence database.
dbUser: "REDACTED"
dbPassword: "REDACTED"
# Credentials used by the persistence database to perform replication between database nodes.
replicationUser: "REDACTED"
replicationPassword: "REDACTED"
# Security configuration for Open LDAP
openLdap:
# Admin user for Open LDAP, can not be adjusted currently.
ldapUser: "REDACTED"
# Admin password for Open LDAP
ldapPassword: "REDACTED"
# Security configuration for Remote Search
remoteSearch:
# Credentials used for IBM WebSphere Application Server administrative access.
# The credentials defined in these values define the WebSphere Application Server's primary administrative user. The user gets created if necessary and/or the password is set to the current value.
# - If the WAS admin credentials were changed by any other means than through the helm values, the currently active credentials need to be entered as the values for wasUser and wasPassword.
# - If LDAP is configured as the user repository, the WebSphere Application Server admin user won't be applied automatically and LDAP has the authority over the credentials. Whenever the credentials are changed in LDAP, the values for wasUser and wasPassword need to be manually updated accordingly.
wasUser: "wpsadmin"
wasPassword: "wpsadmin"
Core security credentials
The security credentials defined in the security
section of the Helm values are necessary to pass the user credentials to the IBM Websphere Application Server and HCL Digital Experience Core startup scripts. The behavior slightly differs depending on the user registry that is configured for HCL Digital Experience. See Registry Types.
Remote Search security credentials
Same as Core, when Remote Search is enabled, WAS admin credentials can be configured from the Helm chart. The behavior slightly differs depending on the user registry that is configured for HCL Digital Experience. See Registry Types.
Config Wizard security credentials
The following only takes effect when Config Wizard is enabled.
For CF212 and below upgrading to CF213 and beyond:
- When upgrading to CF213 or higher, the
configWizardUser
andconfigWizardPassword
undersecurity.core
in yourcustom-values.yaml
file must be updated to the current credentials of thewpsadmin
user in the file-based user registry of Core once, followed by a Helm upgrade. This is required because the file-based user registry of Core is copied to and reused by Config Wizard and Config Wizard is initially usingwpsadmin
as the primary admin user. For more information see: Persisted Config Wizard Profile. - After the Helm upgrade, the Config Wizard credentials can now be updated if needed, separately from the Core.
The section in your custom-values.yaml
must be set like this:
security:
core:
configWizardUser: "wpsadmin"
configWizardPassword: "<your wpsadmin password in the file-based user registry of Core >"
Alternatively, you can set the username wpsadmin
and the correct password in a custom secret and reference them as customConfigWizardSecret
.
Note
When the values are not set correctly during the upgrade, the following error message appears in the logs:
Neither the new nor previous Config Wizard Admin credentials in the Kubernetes secrets are valid. Please supply the correct credentials and restart.
Please follow the steps above to resolve the error for the initial startup.
Similar to Core and Remote Search, you can configure the Config Wizard admin credentials from the Helm chart. The behavior slightly differs depending on the user registry that is configured for HCL Digital Experience. See Registry Types.
Registry Types
LDAP
If LDAP is configured in the Helm values under configuration.core.ldap
, the core security credentials need to be manually set to the credentials of the administrator user(s) from LDAP and kept up to date manually in the helm chart if the users are changed in the LDAP. The credentials are used in several startup and configuration scripts. Changes in the helm values will not cause any changes to the LDAP users.
Please refer to the Updating user ID and passwords topic for additional information on how to manually change credentials.
File-based user registry
If no LDAP is configured in the Helm values, HCL Digital Experience is configured with a default file-based user repository. In this case, the security credentials for Core, Config Wizard and Remote Search that are specified in the custom-values.yaml
are applied to the file-based registry. This means that any changes to the values are automatically reflected in the administrator user accounts for Websphere and DX.
Value | Effect |
---|---|
security.core.wasUser |
Creates a user with this name if it does not exist already. Then makes that user the Websphere primary admin user. |
security.core.wasPassword |
Sets the password of the wasUser to this value. |
security.core.wpsUser |
Creates a user with this name if it does not exist already. Then makes that user a HCL Digital Experience administrator. |
security.core.wpsPassword |
Sets the password of the wpsUser to this value. |
security.core.configWizardUser |
Creates a user with this name if it does not exist already. |
security.core.configWizardPassword |
Sets the password of the configWizardUser to this value. |
security.remoteSearch.wasUser |
Creates a user with this name if it does not exist already. Then make that user the Websphere primary admin user for Remote Search. |
security.remoteSearch.wasPassword |
Sets the password of the Remote Search wasUser to this value. |
Updating Credentials
If the user credentials were, at any time, changed manually and not through the Helm values, the values for Core, ConfigWizard and Remote Search credentials in Helm must be updated (See the above table for reference). If you are using the custom secret, the credentials in the secret must also be set to the current credentials. Then, a helm upgrade
with those values must be executed. Afterward, the Helm values can be used to change the credentials.
If an LDAP is configured as the user registry, you must manually set the security credentials to the credentials of the administrator user from LDAP. If the users are changed in the LDAP, you must manually update the security credentials in the Helm chart. The credentials are used in several startup and configuration scripts. Changes in the Helm values will not cause any changes to the LDAP users.
Upgrading
Ensure that the current credentials are set properly in the Helm Values before doing the upgrade.
Configuring Credentials from Secrets
You can also configure the credentials that HCL Digital Experience 9.5 is using by creating a secret that contains the credentials and referencing them by adding the secret name to your custom-values.yaml
file and doing a helm upgrade
to apply it in the deployments:
# Referencing the secret to configure credential, e.g. core credentials
security:
# Security configuration for Core using secrets
core:
# Credentials used for IBM WebSphere Application Server administrative access.
# The credentials defined in these values define the WebSphere Application Server primary administrative user. The user gets created if necessary and/or the password is set to the current value.
# - If the WAS admin credentials were changed by any other means than through the helm values, the currently active credentials need to be entered as the values for wasUser and wasPassword.
# - If an LDAP is used, then the WebSphere Application Server admin user is never applied automatically and LDAP has the authority over the credentials. Whenever the credentials are changed in LDAP, the values for wasUser and wasPassword need to be manually updated accordingly.
# - If you are using a secret to configure credentials, you must leave the default credentials string empty
# - If both default credential and secret name are filled it will block the chart from being deployed.
wasUser: ""
wasPassword: ""
# Provide a secret name that will be used to set credentials for WAS
# Required attributes:
# - username
# - password
# Secret name is being referenced to configure credentials, this secret conatians the key-value pair for "username" and "password"
customWasSecret: "my-was-credential-secret"
Important
Only one method of configuring credentials can be applied at once. Either configure it by using secrets or using the credentials in the Helm custom-values.yaml
, unused credential values should be explicitly set to empty/null.
Important
A Helm upgrade is required in order for the new credentials values to reflect inside the containers.
Note
The mechanism described above for file-based user registries applies in the same way when custom secrets are used
Guidelines for Configuring Credentials from Secrets
1. Create a Custom Secret
Create a secret that will be used to reference credentials, this secret should contain all the required attributes (e.g. "username", "password") needed by the credentials.
There are two ways to create and deploy custom secrets:
By Kubectl Command\ This is the preferred way of creating a secret inside a cluster, Kubernetes will handle the encoding of the key-value pairs in a base64-encoding format.
$ kubectl create secret generic <secret-name> --from-literal=username=<your-username> --from-literal=password=<your-password> --namespace=<namespace>
For details please refer to the official Kubernetes documentation about Managing Secrets using kubectl.
By YAML files\ Secrets can also be created using a secret yaml manifest.
Note
The string values assigned in the data fields of the secret should be base64-encoded. The containers expect a base64-encoded string to be passed from the secrets key-value pairs. The credentials will not work if the values passed are plain strings.
# Example manifest for creating secret by using a yaml file
apiVersion: "v1"
kind: "Secret"
data:
# The value of the key-value pair should be strictly base64-encoded
username: <username>
# The value of the key-value pair should be strictly base64-encoded
password: <password>
metadata:
labels:
name: <secret-name>
namespace: <namespace>
type: "Opaque"
2. Reference the Secret
Once the secret is created inside the cluster, you can now reference them in their respective custom secret fields inside the custom-values.yaml
under security
section. See this example for reference.
Note
For Core LTPA AND LDAP you can reference your secrets under configuration.core
section of the Helm values.
3. Check the Required Attributes in Secrets
There are multiple credentials used in HCL Digital Experience 9.5. Each application has different required attributes for credentials. If you want to use a secret to configure credentials for a specific application, check the data attributes of the secret that you are using. This is for the Helm chart to map and have those values passed or cascaded accordingly to each application.
Persistence DAM User Credential secret
has a username limitation. The username can begin with lowercase letters or an underscore and can contain only lowercase letters, numbers, underscore, or a dollar sign. The maximum length is 63 characters.
Note
Helm validates the inputs and the deployment will not be applied if required attributes are not set properly in the custom secrets.
Here's a list of the required credential attributes for each application:
Secrets | Helm Reference | Required Attributes | Application |
---|---|---|---|
Core WAS Credential secret | security.core.customWasSecret |
username password |
Core |
Core WPS Credential secret | security.core.customWpsSecret |
username password |
Core |
Core Config Wizard Credential secret | security.core.customConfigWizardSecret |
username password |
Core (Config Wizard) |
Core LDAP Credential secret | configuration.core.ldap.customLdapSecret |
bindUser bindPassword |
Core |
Core LTPA Credential secret | configuration.core.ltpa.customLtpaSecret |
ltpa.version ltpa.realm ltpa.desKey ltpa.privateKey ltpa.publicKey ltpa.password |
Core |
Core Content AI Secret | security.core.customContentAISecret |
apiKey |
Core |
DAM Plugin Google Vision Credential secret | security.damPluginGoogleVision.customDamGoogleVisionSecret |
authenticationKey apiKey |
DAM Google Vision |
DAM Plugin Kaltura Credential secret | security.damPluginKaltura.customDamKalturaSecret |
authenticationKey secretKey |
DAM Kaltura |
Persistence Connection Pool Credential secret | security.persistence.customConnectionPoolSecret |
username password |
Persistence |
Persistence DAM User Credential secret | security.digitalAssetManagement.customDamSecret |
username password |
Digital Asset Management |
Persistence Replication Credential secret | security.digitalAssetManagement.customReplicationSecret |
username password |
Digital Asset Management |
Persistence User Credential secret | security.digitalAssetManagement.customDBSecret |
username password |
Digital Asset Management |
Image Processor Credential secret | security.imageProcessor.customImageProcessorSecret |
authenticationKey |
Image Processor |
License Manager Credential secret | security.licenseManager.customLicenseManagerSecret |
username password |
License Manager |
Open LDAP Credential secret | security.openLdap.customLdapSecret |
username password |
Open LDAP |
Remote Search WAS Credential secret | security.remoteSearch.customWasSecret |
username password |
Remote Search |
Core WAS Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-was-secret
namespace: <namespace>
type: "Opaque"
Core WPS Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-wps-secret
namespace: <namespace>
type: "Opaque"
Core Config Wizard Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-config-wizard-secret
namespace: <namespace>
type: "Opaque"
Core LDAP Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
bindUser: <bindUser>
# Required attribute
bindPassword: <bindPassword>
metadata:
labels:
name: sample-core-ldap-secret
namespace: <namespace>
type: "Opaque"
Core LTPA Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
"ltpa.version": <version>
# Required attribute
"ltpa.realm": <realm>
# Required attribute
"ltpa.desKey": <desKey>
# Required attribute
"ltpa.privateKey": <privateKey>
# Required attribute
"ltpa.publicKey": <publicKey>
# Required attribute
"ltpa.password": <password>
metadata:
labels:
name: sample-core-ltpa-secret
namespace: <namespace>
type: "Opaque"
Core Content AI Secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
apiKey: <apiKey>
metadata:
labels:
name: sample-core-content-ai-secret
namespace: <namespace>
type: "Opaque"
DAM Plugin Google Vision Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
authenticationKey: <authenticationKey>
# Required attribute
apiKey: <apiKey>
metadata:
labels:
name: sample-google-vision-secret
namespace: <namespace>
type: "Opaque"
DAM Plugin Kaltura Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
authenticationKey: <authenticationKey>
# Required attribute
secretKey: <secretKey>
metadata:
labels:
name: sample-kaltura-secret
namespace: <namespace>
type: "Opaque"
Persistence Connection Pool Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-connection-pool-secret
namespace: <namespace>
type: "Opaque"
Persistence DAM User Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute. The username can begin with lowercase letters or an underscore and can contain only lowercase letters, numbers, underscore, or a dollar sign. The maximum length is 63 characters.
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-dam-user-secret
namespace: <namespace>
type: "Opaque"
Persistence Replication Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-replication-secret
namespace: <namespace>
type: "Opaque"
Persistence User Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-replication-secret
namespace: <namespace>
type: "Opaque"
Image Processor Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
authenticationKey: <authenticationKey>
metadata:
labels:
name: sample-kaltura-secret
namespace: <namespace>
type: "Opaque"
License Manager Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-license-manager-secret
namespace: <namespace>
type: "Opaque"
Open LDAP Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-open-ldap-secret
namespace: <namespace>
type: "Opaque"
Remote Search WAS Credential secret
apiVersion: "v1"
kind: "Secret"
data:
# Required attribute
username: <username>
# Required attribute
password: <password>
metadata:
labels:
name: sample-remote-search-was-secret
namespace: <namespace>
type: "Opaque"