🆕 Video Course Out Now: Rapid Docker on AWS

Passwordless database authentication for AWS Lambda

Andreas Wittig – 19 Oct 2017

Does your serverless application need to access an RDS database? Where do you store the username and the password required to authenticate with the database? Storing the password in plain text within your source code should not be an option. Same is true for the environment variables of your Lambda function. Using KMS to encrypt the database password is possible but cumbersome. Lucky you, there is an elegant solution to the problem of authenticating a Lambda function with an RDS database.

Instead of using a conventional database user with password make use of IAM Database Authentication for MySQL and Amazon Aurora. As shown in the following figure using an IAM role to authenticate at an RDS database is possible. You no longer have to cope with a database password, you are using the IAM role of your Lambda function instead.

Overview of passwordless database authentication

The following instructions guide you through configuring IAM database authentication for a Lambda function written in Node.js accessing an RDS database cluster with Aurora (MySQL) engine.

Before we start, let’s talk about the restrictions when using IAM database authentication:

  • Using the MySQL or Aurora RDS engine is required (MySQL >=5.6.34, MySQL >=5.7.16, Aurora >1.10).
  • A Secure Sockets Layer (SSL) database connection is needed.
  • Smallest database instance types do not support IAM database authentication. db.t1.micro and db.m1.small instance types are excluded for MySQL. The db.t2.small instance type is excluded for Aurora.
  • AWS recommends creating no more than 20 database connections per second when using IAM database authentication.

Step 1: Enabling IAM database authentication

First of all, you need to enable IAM database authentication. Type in the following command into your terminal to enable IAM database authentication for your Aurora database cluster. Replace <DB_CLUSER_ID> with the identifier of your Aurora database cluster.

aws rds modify-db-cluster --db-cluster-identifier <DB_CLUSTER_ID> --enable-iam-database-authentication --apply-immediately

See Enabling and Disabling IAM Database Authentication if you need more detailed information.

Step 2: Preparing a database user

Next, you need to connect to your database and create a user using the AWS authentication plugin.

The following SQL statement creates a database user named lambda. Instead of specifying a password, the AWSAuthenticationPlugin is used for identifying the user. Replace <DB_NAME> with the name of the database you want to grant the user access to.

The DynamoDB Book

Stop fighting your database.

DynamoDB is exploding in popularity. It's fast, scalable, and fully-managed. But it's not your father's database. Data modeling in DynamoDB is different than the relational data model you're used to.

Learn how to properly design your data model with DynamoDB to avoid problems later.

The DynamoDB Book by Alex DeBrie is available now!

Get The DynamoDB Book now
CREATE USER 'lambda' IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS';

I’m using a database named lambda_test. Therefore, my SQL query looks as follows.

CREATE USER 'lambda' IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS';
GRANT ALL PRIVILEGES ON lambda_test.* TO 'lambda'@'%';

Step 3: Creating an IAM role

Probably, you have already configured an IAM role for your Lambda function. To be able to authenticate with the RDS database you need to add an IAM policy to the IAM role.

The following snippet shows a policy granting access to authenticate with an RDS database. Replace <REGION> with the region the database is running in, <AWS_ACCOUNT_ID> with the account id of your AWS account and <DB_RESOURCE_ID> with the resource id of your database cluster. Also, don’t forget to replace <DB_USERNAME> with the username lambda created in step 2.

"Version": "2012-10-17",
"Statement": [
"Effect": "Allow",
"Action": "rds-db:connect",
"Resource": "arn:aws:rds-db:<REGION>:<AWS_ACCOUNT_ID>:dbuser:<DB_RESOURCE_ID>/<DB_USERNAME>"

My IAM policy looks like this, for example.

"Version": "2012-10-17",
"Statement": [
"Effect": "Allow",
"Action": [
"Resource": [

Warning: It might take a few minutes until changes to your IAM role are in effect. Be careful when debugging authentication issues. Sometimes getting a cup of coffee or tea is solving the problem. ;-)

Step 4: Connecting to the database

Finally, you can write the source code for your Lambda function. Install the mysql2 module used to establish a database connection to Aurora.

npm install mysql2@1.4.2

The following snippet contains the source code needed to access the RDS database from your Lambda function. Note you have to edit the database connection details as well as the query (see TODO).

'use strict';

const mysql = require('mysql2');
const AWS = require('aws-sdk');

// TODO use the details of your database connection
const region = 'eu-west-1';
const dbPort = 3306;
const dbUsername = 'lambda'; // the name of the database user you created in step 2
const dbName = 'lambda_test'; // the name of the database your database user is granted access to
const dbEndpoint = 'lambdatest-cluster-1.cluster-c8o7oze6xoxs.eu-west-1.rds.amazonaws.com';

module.exports.handler = (event, context, cb) => {
var signer = new AWS.RDS.Signer();
signer.getAuthToken({ // uses the IAM role access keys to create an authentication token
region: region,
hostname: dbEndpoint,
port: dbPort,
username: dbUsername
}, function(err, token) {
if (err) {
console.log(`could not get auth token: ${err}`);
} else {
var connection = mysql.createConnection({
host: dbEndpoint,
port: dbPort,
user: dbUsername,
password: token,
database: dbName,
ssl: 'Amazon RDS',
authSwitchHandler: function (data, cb) { // modifies the authentication handler
if (data.pluginName === 'mysql_clear_password') { // authentication token is sent in clear text but connection uses SSL encryption
cb(null, Buffer.from(token + '\0'));
// TODO replace with your SQL query
connection.query('SELECT * FROM lambda_test.test', function (err, results, fields) {
if (err) {
console.log(`could not execute query: ${err}`);
} else {
cb(undefined, results);


The IAM database authentication is superseding handling the database password within your serverless application. All you need is to attach an IAM role to your Lambda function.

Using an authentication token instead of a password increases security:

  • You don’t have to store the password in your source code or the Lambda function’s environment variables.
  • The authentication token is a generated secret (Signature Version 4 signing process).
  • The authentication token has a limited lifetime (15 minutes).
Andreas Wittig

Andreas Wittig

I’m an independent consultant, technical writer, and programming founder. All these activities have to do with AWS. I’m writing this blog and all other projects together with my brother Michael.

In 2009, we joined the same company as software developers. Three years later, we were looking for a way to deploy our software—an online banking platform—in an agile way. We got excited about the possibilities in the cloud and the DevOps movement. It’s no wonder we ended up migrating the whole infrastructure of Tullius Walden Bank to AWS. This was a first in the finance industry, at least in Germany! Since 2015, we have accelerated the cloud journeys of startups, mid-sized companies, and enterprises. We have penned books like Amazon Web Services in Action and Rapid Docker on AWS, we regularly update our blog, and we are contributing to the Open Source community. Besides running a 2-headed consultancy, we are entrepreneurs building Software-as-a-Service products.

We are available for projects.

You can contact me via Email, Twitter, and LinkedIn.

Briefcase icon
Hire me