👉 AWS Debug Games (Beta) - Prove your AWS expertise by solving tricky challenges.

👉 AWS Debug Games - Prove your AWS expertise.

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.

Looking for a new challenge?


    Cloud Operations Lead

    DEMICON • AWS Advanced Consulting Partner • Remote (Europe)
    service-delivery-management hiring devops platform

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).

Become a cloudonaut supporter

Andreas Wittig

Andreas Wittig ( Email Twitter LinkedIn Mastodon )

We launched the cloudonaut blog in 2015. Since then, we have published 365 articles, 68 podcast episodes, and 68 videos. It's all free and means a lot of work in our spare time. We enjoy sharing our AWS knowledge with you.

Please support us

Have you learned something new by reading, listening, or watching our content? With your help, we can spend enough time to keep publishing great content in the future. Learn more

Amount must be a multriply of 5. E.g, 5, 10, 15.

Thanks to Alan Leech, Alex DeBrie, Christopher Hipwell, Jason Yorty, Jeff Finley, jhoadley, Johannes Konings, John Culkin, Jonathan Deamer, Juraj Martinka, Ken Snyder, Markus Ellers, Oriol Rodriguez, Ross Mohan, sam onaga, Satyendra Sharma, Simon Devlin, Todd Valentine, Victor Grenu, and all anonymous supporters for your help! We also want to thank all supporters who purchased a cloudonaut t-shirt.