AWS Secrets Manager JDBC Library

The AWS Secrets Manager JDBC Library enables Java developers to easily connect to SQL databases using secrets stored in AWS Secrets Manager.

License

This library is licensed under the Apache 2.0 License.

Features

Provides wrappers to common JDBC drivers enabling simple database connectivity
Provides database connection pooling support through c3p0

Building from Source

After you've downloaded the code from GitHub, you can build it using Maven. To disable GPG signing in the build, use this command: mvn clean install -Dgpg.skip=true

Usage

The recommended way to use the SQL Connection Library is to consume it from Maven. The latest released version can be found at: https://mvnrepository.com/artifact/com.amazonaws.secretsmanager/aws-secretsmanager-jdbc

<dependency>
    <groupId>com.amazonaws.secretsmanager</groupId>
    <artifactId>aws-secretsmanager-jdbc</artifactId>
    <version>1.0.12</version>
</dependency>

To use the latest build (pre-release), don't forget to enable the download of snapshot jars from Maven.

<profiles>
  <profile>
    <id>allow-snapshots</id>
    <activation><activeByDefault>true</activeByDefault></activation>
    <repositories>
      <repository>
        <id>snapshots-repo</id>
        <url>https://aws.oss.sonatype.org/content/repositories/snapshots</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
      </repository>
    </repositories>
  </profile>
</profiles>

Usage Example

We provide database drivers that intercept calls to real database drivers and swap out secret IDs for actual login credentials. This prevents hard-coding database credentials into your application code. This can be integrated into your app through a few configuration file changes. Here is an example for making this work with your c3p0 config:

# c3p0.properties

# MySQL example
c3p0.user=secretId
c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMySQLDriver
c3p0.jdbcUrl=jdbc-secretsmanager:mysql://example.com:3306

# PostgreSQL example
# c3p0.user=secretId
# c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerPostgreSQLDriver
# c3p0.jdbcUrl=jdbc-secretsmanager:postgresql://example.com:5432/database

# Oracle example
# c3p0.user=secretId
# c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerOracleDriver
# c3p0.jdbcUrl=jdbc-secretsmanager:oracle:thin:@example.com:1521/ORCL

# MSSQLServer example
# c3p0.user=secretId
# c3p0.driverClass=com.amazonaws.secretsmanager.sql.AWSSecretsManagerMSSQLServerDriver
# c3p0.jdbcUrl=jdbc-secretsmanager:sqlserver://example.com:1433

The only changes that need to happen in the c3p0 config are to:

change the jdbc url to one that our driver will intercept (starting with jdbc-secretsmanager),
change the c3p0 user to be the secret ID of the secret in secrets manager that has the username and password,
and change the driverClass to be our driver wrapper.

The secret being used should be in the JSON format we use for our rotation lambdas for RDS databases. E.g:

{
	"username": "user",
	"password": "pass",
	...
}

Credentials

This library uses the Default Credential Provider Chain. The following options exist to override some of the defaults:

Set a PrivateLink DNS endpoint URL and a region in the secretsmanager.properties file:

drivers.vpcEndpointUrl= #The endpoint URL
drivers.vpcEndpointRegion= #The endpoint region

Override the primary region by setting the 'AWS_SECRET_JDBC_REGION' environment variable to the preferred region, or via the secretsmanager.properties file:

drivers.region= #The region to use.

If this driver is running on EKS, the library could pick up the credentials of the node it is running on instead of the service account role (issue). To address this, add version 1 of com.amazonaws:aws-java-sdk-sts to your Gradle/Maven project file as a dependency.