iam-jdbc-driver
iam-jdbc-driver copied to clipboard
A generic JDBC driver wrapper connecting using IAM RDS token authentication
iam-jdbc-driver
A generic JDBC driver wrapper for authenticating using RDS IAM auth.
Preconfigured driver classes are provided for MySQL and PostgreSQL,
however you could use this library to wrap any JDBC driver for use with IAM auth.
Usage
-
Add the library to your application classpath
Two versions of the library are provided in maven central:- A regular version with transitive dependencies resolved via normal means.
implementation("io.magj:iam-jdbc-driver:$version")
- A shaded version with the transitive dependencies bundled into the one jar file under a different namespace.
implementation("io.magj:iam-jdbc-driver:$version:all@jar")
The latter may be more suitable for integrating with applications with which you do not have direct control over the source code/build process.
- A regular version with transitive dependencies resolved via normal means.
-
Ensure you also have the delegate driver loaded onto your classpath.
This library does not bundle any driver implementations.
You will need ensure that the desired MySql/Postgres/etc delegate driver class is loadable. -
Configure the JDBC connection settings:
Many applications resolve driver classes viajava.sql.DriverManager#getDriver(String url)
, if this is the case for your application configuration may be as simple as just changing the scheme in the JDBC url.# Mysql from: jdbc:mysql://host1:33060/exampledb to: jdbc:iammysql://host1:33060/exampledb # Postgres from: jdbc:postgresql://host1:54321/exampledb to: jdbc:iampostgresql://host1:54321/exampledb
Alternatively if your application explicitly configures the JDBC driver class, you can provide
io.magj.iamjdbcdriver.MySqlIamAuthJdbcDriverWrapper
or
io.magj.iamjdbcdriver.PostgreSqlIamAuthJdbcDriverWrapper
If you want to wrap a driver other than the default mysql or postgres drivers, see the properties
delegateJdbcDriverClass
,delegateJdbcDriverSchemeName
and the source code ofio.magj.iamjdbcdriver.IamAuthJdbcDriverWrapper
for more information
Credentials
There are multiple ways to configure the credentials used to obtain the RDS authentication token.
DefaultAWSCredentialsProviderChain
The default and recommended approach is to use credentials sourced from the DefaultAWSCredentialsProviderChain
.
Best practice would be to run your application from an instance/container/lambda
that is configured with an instance profile, which has the appropriate rds-db:connect
IAM actions allowed.
However you may also specify credentials via any of the other numerous ways supported by DefaultAWSCredentialsProviderChain
- Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
- Java System Properties - aws.accessKeyId and aws.secretKey
- Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
- Credentials delivered through the Amazon EC2 container service if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI" environment variable is set and security manager has permission to access the variable,
- Instance profile credentials delivered through the Amazon EC2 metadata service
- Web Identity Token credentials from the environment or container.
Access Key ID and Secret Access Key ID
Rather than using Environment or System properties, you can pass access key as properties to the JDBC connection.
Use of this option is discouraged, as it essentially defeats most of the purpose of using IAM auth in the first place.
See the properties list below for more information.
Aws Profile
You can pass the name of a profile that will be selected from the default location.
See the properties list below for more information.
Assume Role
You can have the driver assume a role before requesting an IAM auth token.
The base credentials used for the assume role request are sourced from the other credential configuration options.
See the properties list below for more information.
Properties
Properties for the driver wrapper can be specified either as URL query parameters or as regular JDBC connection properties. If the same property is specified on both, then the URL query parameter will take precedence.
All properties are passed to the delegate JDBC driver.
The following is the list of wrapper specific properties:
Property | Description | Example |
---|---|---|
delegateJdbcDriverClass |
The JDBC driver class to delegate calls to, if not already configured. Only required if using a wrapper instance with no pre-configured driver class |
com.mysql.jdbc.Driver |
delegateJdbcDriverSchemeName |
The JDBC url scheme of the driver to delegate calls to. This is the portion of the URL after "jdbc:" For example "mysql" or "postgresql" Only required if using a wrapper instance with no pre-configured driver class |
mysql |
awsRegion |
The optional AWS region to use, if not specified, will use the DefaultAwsRegionProviderChain or a region from a configured profile |
us-east-1 |
awsProfile |
The optional name of an AWS profile to source credentials/region configuration from. | default |
awsStsCredentialProviderRoleArn |
An optional role ARN to assume before requesting RDS iam credentials | arn:aws:iam::123456789012:role/DatabaseAccess |
awsStsCredentialProviderSessionName |
An optional session name to use if assuming a role. A random session name will be generated if not specified. This option has no effect if awsStsCredentialProviderRoleArn is not configured |
myapplication-123 |
awsStsCredentialProviderExternalId |
An optional external ID to pass in the assume role call. This option has no effect if awsStsCredentialProviderRoleArn is not configured |
12345678-1234-1234-1234 |
awsAccessKeyId |
An optional AWS access key to use as credentials when requesting an RDS token. This option must be configured in conjunction with awsAccessKeyId or will be ignored |
AKIAIOSFODNN7EXAMPLE |
awsSecretAccessKey |
An optional AWS secret key to use as credentials when requesting an RDS token. This option must be configured in conjunction with awsSecretAccessKey or will be ignored |
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY |