Automatic Connector Credential Encryption

Overview

The Connector Credential Encryption Migrator is an internal system component that automatically encrypts legacy connector credentials stored in plaintext. This one-time, idempotent process runs at application startup to enhance security by ensuring sensitive credential data is encrypted at rest.

The migrator targets specific plaintext credential fields associated with F5 and DataPower connector instances:

• s2r_f5_instance.password
• s2r_f5_instance.managed_password
• s2r_f5_instance.relay_service_account_json
• s2r_datapower_instance.password

This process is designed as an application-level task rather than a database migration script. This is because the necessary encryption key, provided via the S2R_CREDENTIAL_KEY environment variable, is only available within the application's runtime environment and must not be exposed to other systems or stored in SQL.

The migration is safe to run in multi-replica environments and is resilient to failure. If a run is interrupted or fails, it will be automatically retried on the next application startup. The system can read both plaintext and encrypted credentials, so a failed migration does not impact connector functionality.

How it works

The credential encryption process is triggered automatically when the application becomes fully operational.

flowchart TD
    subgraph Application Startup
        A[Application Ready Event] --> B{Credential Encryption Migrator};
    end

    B --> C{Iterate all tenants};
    C -- For each tenant --> D{Encrypt F5 secrets};
    D --> E{Encrypt DataPower secrets};
    E --> C;
    C -- Iteration complete --> F[Migration Finished];

    D -- On failure --> G[Log warning, continue];
    E -- On failure --> H[Log warning, continue];

1. Trigger: The migrator's onReady method listens for the ApplicationReadyEvent, which the application framework emits once initialization is complete.
2. Tenant Iteration: The migrate method is called, which uses the PerTenantJobRunner to execute the encryption logic for each tenant in the system. In a single-tenant deployment, this process runs once for the default tenant.
3. Encryption: For each tenant, the migrator performs two main operations:
   • It invokes f5InstanceRepository.encryptLegacyPlaintextSecrets() to find and encrypt any plaintext credentials in the s2r_f5_instance table.
   • It invokes dataPowerInstanceRepository.encryptLegacyPlaintextSecrets() to do the same for the s2r_datapower_instance table.
4. Idempotency: The process is idempotent. On each run, it checks if a credential value is already encrypted using a CredentialsCipher.isEnvelope check. If a value is already in the encrypted format, it is skipped. This ensures that subsequent application restarts or concurrent runs in a multi-replica cluster do not re-encrypt data or cause errors.
5. Logging: If the migrator successfully encrypts any credentials, it logs a message indicating the number of values updated for each connector type and tenant.

Expected Log Output

When the migrator runs and finds plaintext credentials to encrypt, it will output informational logs. Administrators can monitor the application logs at startup to verify that the migration has occurred.

The following are examples of log messages you might see if one F5 secret and two DataPower passwords were encrypted for a tenant with ID example-tenant-id.

INFO S2R connector credentials: re-encrypted 1 legacy plain-text F5 secret value(s) tenant=example-tenant-id
INFO S2R connector credentials: re-encrypted 2 legacy plain-text DataPower password(s) tenant=example-tenant-id

If no plaintext credentials are found, no messages will be logged.

Configuration

The migrator relies on a single environment variable for the encryption key.

API Reference

The Connector Credential Encryption Migrator is an internal component that runs automatically at startup. It does not expose any user-facing API endpoints or CLI commands.

Troubleshooting

The migrator is designed to be resilient. Failures are logged as warnings, and the operation is automatically retried on the next application startup. System functionality is not affected because credential readers are backward-compatible with the legacy plaintext format.

All SOAP-to-REST docs