Need

Semarchy xDM provides built-in integration with AWS Secrets Manager for Data Locations and Dashboard data sources, allowing credentials to be retrieved and rotated automatically.


However, the repository connection is a special case.


Because xDM must connect to the repository database during startup, it cannot use the same internal mechanism that is available for Data Locations. As a result, additional configuration is required when repository credentials are managed and rotated through AWS Secrets Manager.


Without this configuration:

  • Repository credentials must be managed manually.
  • Password rotation becomes operationally complex.
  • Updating credentials may require configuration changes and service restarts.


To support automatic credential retrieval and rotation for the repository connection, you can configure xDM to use the AWS Secrets Manager JDBC Driver.


Summarized Solution

To use AWS Secrets Manager for repository credentials:

  1. Download the AWS Secrets Manager JDBC driver and its dependencies.
  2. Deploy the driver files alongside the existing JDBC drivers used by xDM.
  3. Configure the repository datasource to use the AWS Secrets Manager JDBC driver.
  4. Replace the repository username with the name (or ARN) of the AWS Secret.
  5. Start xDM using the updated configuration.

The JDBC driver retrieves the username and password stored in AWS Secrets Manager and uses them transparently to establish the repository connection.


This allows credential rotation to be managed centrally in AWS without modifying the xDM repository configuration.


Detailed Solution

Understanding the Architecture

For Data Locations and Dashboard data sources, xDM can directly integrate with AWS Secrets Manager.


For the repository connection, the situation is different:

  • xDM must establish a repository connection before the platform is fully initialized.
  • Therefore, the repository connection itself must rely on a JDBC driver capable of retrieving credentials from AWS Secrets Manager.

Amazon provides a JDBC driver specifically designed for this purpose.


Step 1 - Download the AWS Secrets Manager JDBC Driver

Download the AWS Secrets Manager JDBC Driver and its required dependencies from the official AWS documentation.


At the time of writing, the required libraries include:

 aws-java-sdk-core-1.11.418.jar
 aws-java-sdk-secretsmanager-1.11.418.jar
 aws-secretsmanager-caching-java-1.0.1.jar
 aws-secretsmanager-jdbc-1.0.6.jar
 commons-codec-1.10.jar
 commons-logging-1.1.3.jar
 httpclient-4.5.5.jar
 httpcore-4.4.9.jar
 ion-java-1.0.2.jar
 jackson-annotations-2.10.3.jar
 jackson-core-2.10.3.jar
 jackson-databind-2.10.3.jar
 jackson-dataformat-cbor-2.6.7.jar
 jmespath-java-1.11.418.jar
 joda-time-2.8.1.jar


⚠ Dependency versions may vary depending on the AWS driver version you choose.


Step 2 - Deploy the Driver

Deploy the downloaded JAR files following the standard Semarchy JDBC driver deployment procedure.


For many deployments, especially AWS Marketplace images, JDBC drivers are typically located in:

/var/lib/tomcat9/lib/

After copying the files:

  • Verify file permissions.
  • Ensure all dependencies are present.
  • Restart the application server if required.

Step 3 - Configure the Repository Datasource

Configure the repository connection to use the AWS Secrets Manager JDBC driver.


Example using environment variables:

# Repository datasource
 export XDM_REPOSITORY_DRIVER=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver
 export XDM_REPOSITORY_URL=jdbc-secretsmanager:postgresql://myserver.cdm34ibs42so.us-west-1.rds.amazonaws.com:5432/semarchy
 export XDM_REPOSITORY_USERNAME=semarchy_repository
 export XDM_REPOSITORY_PASSWORD=not_used
 export XDM_REPOSITORY_READONLY_USERNAME=semarchy_repository_readonly
 export XDM_REPOSITORY_READONLY_PASSWORD=not_used

The property XDM_REPOSITORY_USERNAME can be misleading in this configuration.

When using the AWS Secrets Manager JDBC driver:

  • The value is not the database username.
  • The value is the name of the AWS Secret (or its ARN).


Example: export XDM_REPOSITORY_USERNAME=semarchy_repository

Here semarchy_repository is the name of the AWS Secret.


The JDBC driver retrieves the actual database username and password from the secret.


Using the Secret ARN

Instead of the secret name, you may also use the full AWS Secret ARN:

arn:aws:secretsmanager:us-west-1:285620823592:secret:semarchy_repository-VDAlaP

This can be useful when:

  • Multiple secrets have similar names.
  • Cross-account access is configured.
  • Explicit secret identification is preferred.
  • Understanding the Password Parameter


The AWS Secret already contains:

  • Username
  • Password
  • And potentially additional metadata such as:
    • Engine
    • Host
    • Port
    • Database name


As a result XDM_REPOSITORY_PASSWORD is ignored by the JDBC driver.


Step 4 - Restart and Validate

After updating the configuration:

  • Restart the application server.
  • Monitor startup logs.
  • Verify that:
    • The repository connection is established successfully.
    • No authentication errors are reported.
    • The platform starts normally.


If configured correctly, xDM will retrieve repository credentials directly from AWS Secrets Manager.


Additional Considerations


Credential Rotation

One of the primary benefits of this configuration is support for credential rotation.

When the secret is updated in AWS Secrets Manager:

  • The JDBC driver retrieves the updated credentials.
  • Repository passwords no longer need to be manually managed in xDM startup configuration.

Always validate the behavior in a non-production environment before implementing automated password rotation.


Permissions

The application server must have sufficient AWS permissions to:

  • Access AWS Secrets Manager
  • Read the configured secret
  • Retrieve secret values

Typically this is achieved through:

  • IAM roles
  • IAM instance profiles
  • AWS access credentials

Depending on your deployment architecture.