Skip to content

Latest commit

 

History

History
132 lines (96 loc) · 4.74 KB

README.adoc

File metadata and controls

132 lines (96 loc) · 4.74 KB
Raw

AWS RDS IAM Authentication Token generator

License Apache%202.0 blue badge javadoc

Generates tokens which can be used as passwords when connecting to an AWS RDS instance with IAM authentication enabled.

See Amazon’s documentation for more information.

An RDS IAM Token is a short-lived password which can be used to authenticate to a RDS instance for example in a JDBC connection. A token is generated from a set of input data, namely information which uniquely identifies the RDS instance (the hostname, the port, the AWS region where it is located, the db user inside the database you want to authenticate as, etc) as well as some AWS credentials.

The advantage to using RDS IAM Tokens compared to a traditional password is:

  • The token is temporary, it is only valid (by default) for 15 minutes. Even compared to putting your username/password into a password vault, such as AWS Secrets Manager, the RDS IAM Token method is still superior, for the exact reason that the credential has a limited time-to-live.

  • When the host accessing the RDS instance is also hosted in AWS you don’t have to specify any database credentials in the parameters to your environment. It is easy for an operator to view these parameters from the AWS Console and thereby the password is revealed. With RDS IAM Token authentication there’s nothing visible in the environment’s parameters thus nothing to 'steal'.

 

💡
 Generating a token is a purely local process. It doesn’t involve any network traffic. It does, however, involve some fairly lightweight cryptograhpic calculations. Generating a token typically require less than 1 millisecond. Since the token is valid for 15 minutes there’s no point in repeatedly generating the same token until it is really necessary to generate a new token. For this reason the library includes constructs which makes it easier to cache the result, although the library does not itself include a cache implementation.

 

This is a no-deps implementation. The library is meant as a base for more sophisticated libraries, but can also be used on its own.

 
 

Usage

  1. Add the following dependency to your project:

<dependency>
    <groupId>net.lbruun.aws</groupId>
    <artifactId>rds-iam-auth-token</artifactId>
    <version>  ---latest-version---  </version>
</dependency>

  1. You can now generate tokens (passwords) as follows:

String awsAccessKeyId = "AKIAIOSFODNN7EXAMPLE";
String awsSecretKey = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY";
String rdsHostname = "mypsql.ca8biuyqt0qc.eu-central-1.rds.amazonaws.com";
int rdsPortNo = 5432;
String dbUsername = "mary";

RdsIamToken rdsIamToken = RdsIamTokenGenerator.getRdsIamToken(
        RdsIamTokenGenerator.Parameters.builder()
            .awsAccessKeyId(awsAccessKeyId)
            .awsSecretKey(awsSecretKey)
            .dbUsername(dbUsername)
            .hostname(rdsHostname)
            .portNo(rdsPortNo)
            .build());

// That's all !

// Now use the token to establish a database connection
// (in this case for PostgreSQL)

String url = "jdbc:postgresql://" + rdsHostname + ":" + rdsPortNo + "/sales2020";
Properties props = new Properties();
props.setProperty("user", dbUsername);
props.setProperty("password", rdsIamToken.getToken());
Connection conn = DriverManager.getConnection(url, props);
ℹ️
 It is outside the scope of the library how the values for awsAccessKeyId and awsSecretKey are obtained.

 

Documentation

 
 

Alternatives

Both the AWS SDK v1 and the AWS SDK v2 include helpers for generating an RDS IAM token. However, they pull in a lot of baggage and lack the ease-of-use and documentation of this library.

Project information

Bugs and Feature Requests

Simply add a ticket here.

Testing

Tests are based on comparing to output from AWS SDK v1 as well as AWS SDK v2. Tests pass when the generated token is exactly equal to the token generated by those two implementations.