Configuring the administrator user and group

This topic explains how to configure the administrator user and group in HCL Digital Experience (DX) Compose. You can set the administrator by using either the basic registry or an external LDAP directory. To update only the administrator password, see Updating the default administrator password.

Before you begin

Review these constraints before you change the administrator:

Basic registry administrator: Set webEngineUser to a short username (for example, dxadmin). Don’t use a Distinguished Name (DN). The system constructs the full DN automatically as uid=<username>,o=<realm>.
LDAP administrator: The username in the Kubernetes secret must be the full DN of the LDAP user (for example, uid=admin,ou=users,dc=example,dc=com). Partial or short IDs aren’t supported.
LDAP group: Set webEngineAdminGroup to the full DN of the LDAP group (for example, cn=admins,ou=groups,dc=example,dc=com).
Disable the basic registry: When basicRegistry.enabled is set to false, the wpsadmin user is removed and can’t be used for authentication. Verify your LDAP configuration before disabling it.
Replace the administrator: Changing the administrator replaces wpsadmin. The previous administrator no longer has access after the change is applied.

Changing to a custom basic registry administrator

To change the administrator to a custom user in the basic registry:

Create a Kubernetes secret with the new administrator credentials:
```
kubectl create secret generic CUSTOM_SECRET_NAME \
  --from-literal=username=CUSTOM_ADMIN_USERNAME \
  --from-literal=password=CUSTOM_ADMIN_PASSWORD \
  --namespace=<NAMESPACE>
```
Replace the values for the following:
- CUSTOM_SECRET_NAME with the name of the secret.
- CUSTOM_ADMIN_USERNAME with the new short username (for example, dxadmin). Do not use a full DN.
- CUSTOM_ADMIN_PASSWORD with the administrator password.
Update the values.yaml file. See the following sample:
```
security:
  webEngine:
    webEngineUser: ""
    webEnginePassword: ""
    webEngineAdminGroup: "CUSTOM_ADMIN_GROUP"
    customWebEngineSecret: "CUSTOM_SECRET_NAME"
    basicRegistry:
      enabled: true
      realm: "defaultWIMFileBasedRealm"
```
Replace the values for the following:
- CUSTOM_ADMIN_GROUP with the short group name (for example, dxadmins). The system constructs the full group DN as cn=<group>,o=<realm>.
- CUSTOM_SECRET_NAME with the name of the secret created in Step 1.
Note

When you use customWebEngineSecret, leave webEngineUser and webEnginePassword empty. Don’t set both.
Run a Helm upgrade.
Restart the server to apply the changes if the pod is not automatically recreated.
Verify the change by logging in to DX Compose using the new administrator credentials and confirming that the user has full administrator access.

Changing to an LDAP user as administrator

When setting the administrator to a user in an external LDAP directory, the username and group must be full DNs and basicRegistry.enabled must be set to false.

Warning

Setting basicRegistry.enabled: false removes the wpsadmin user entirely. Verify that your LDAP credentials and group DN are correct before applying this change to avoid losing administrator access. If something goes wrong, see the Rollback section.

Create a Kubernetes secret with the LDAP user credentials. The username must be the full DN of the LDAP user:
```
kubectl create secret generic CUSTOM_SECRET_NAME \
  --from-literal=username="uid=admin,ou=users,dc=example,dc=com" \
  --from-literal=password=LDAP_USER_PASSWORD \
  --namespace=<NAMESPACE>
```
Replace the values for the following:
- CUSTOM_SECRET_NAME with the name of the secret.
- uid=admin,ou=users,dc=example,dc=com with the full DN of your LDAP user.
- LDAP_USER_PASSWORD with the LDAP user's password.
Note

The username must be the complete DN, including all organizational. For example, uid=admin,ou=users,dc=example,dc=com is valid. A partial DN such as uid=admin,dc=example,dc=com (missing ou=users) may fail to resolve correctly.
Update the values.yaml file. See the following sample:
```
security:
  webEngine:
    webEngineUser: ""
    webEnginePassword: ""
    webEngineAdminGroup: "cn=admins,ou=groups,dc=example,dc=com"
    customWebEngineSecret: "CUSTOM_SECRET_NAME"
    basicRegistry:
      enabled: false
```
Replace the values for the following:
- cn=admins,ou=groups,dc=example,dc=com with the full DN of the LDAP administrator group.
- CUSTOM_SECRET_NAME with the name of the secret created in Step 1.
Note

Both the username in the secret and webEngineAdminGroup must be full DNs when using LDAP authentication.
Run a Helm upgrade.
If the pod does not restart automatically after the Helm upgrade, restart the server manually to apply the changes.

A pod restart is triggered automatically when the Helm upgrade changes the pod spec, for example when using a different secret name or changing webEngineAdminGroup. If only the contents of an existing secret were updated without changing the secret name referenced in the values, the pod will not restart automatically and a manual restart is required.
Verify the change by logging in to DX Compose using the LDAP user credentials and confirming that the user has full administrator access.

For configuring the LDAP registry itself, see Configuring LDAP.

After changing the administrator

After the new administrator is active, update any services or configurations that used the previous administrator credentials. If you don’t update them, authentication failures may occur in dependent services.

Update the following services that commonly store administrator credentials:

Credential Vault: If administrator credentials are stored in the Credential Vault, update the relevant vault slot with the new credentials. Features such as Syndication use these slots for authentication and fail if the stored credentials don’t match the active administrator.
Custom scheduled tasks or scripts: Update any tasks or scripts that authenticate by using the previous administrator username or password.

Rollback

If you provided incorrect credentials or configuration and lost administrator access, use one of the following options to restore a working state.

Option 1: Revert using Helm values

Retrieve the current deployed values:

helm get values <RELEASE_NAME> -n <NAMESPACE> -o yaml -a > backup-values.yaml

Edit the file to restore the previous administrator configuration. The following example reverts to the default wpsadmin user:

security:
  webEngine:
    webEngineUser: ""
    webEnginePassword: ""
    webEngineAdminGroup: "wpsadmins"
    customWebEngineSecret: "<ORIGINAL_SECRET_NAME>"
    basicRegistry:
      enabled: true
      realm: "defaultWIMFileBasedRealm"

Apply the corrected values using a Helm upgrade:

helm upgrade <RELEASE_NAME> <CHART_PATH> -n <NAMESPACE> -f backup-values.yaml

Once the pod is running, verify the rollback by logging in to DX Compose using the restored administrator credentials and confirming full administrator access.

Option 2: Roll back using kubectl

If the pod is failing to start due to incorrect configuration, you can roll back the StatefulSet to its previous revision:

Check the available rollout history:

kubectl rollout history statefulset/<RELEASE_NAME>-web-engine -n <NAMESPACE>

Roll back to the previous revision:

kubectl rollout undo statefulset/<RELEASE_NAME>-web-engine -n <NAMESPACE>

To roll back to a specific revision, use the --to-revision flag:

kubectl rollout undo statefulset/<RELEASE_NAME>-web-engine -n <NAMESPACE> --to-revision=<REVISION_NUMBER>

Monitor the pod status:
```
kubectl get pods -n <NAMESPACE>
```
Once the pod is running, verify the rollback by logging in to DX Compose using the restored administrator credentials and confirming full administrator access.

Rolling back the StatefulSet restores the previous pod specification, but it does not revert Helm values or Kubernetes secrets. After the pod is stable, update your Helm values to match the restored configuration. This prevents configuration mismatches during the next Helm upgrade.

For adding other administrators and non-administrator users, see configOverrideFiles.