In this article I will explain what multi-factor authentication is, why you should be using it and how to easily implement it with Couchbase Server.  We’ll look at using both software and hardware implementations, which offer a tradeoff between cost, convenience and security.

What is
Multi-Factor Authentication ? 

Authentication on a Couchbase cluster is secured with a combination of user passwords, Role Based Access Control (RBAC) and, optionally, x.509 certificates.  Passwords have been around a long time and have served their purpose well but using them alone leaves you open to various hacking techniques.  The good news is that passwords can be augmented with additional user information for higher levels of security in what is known as Multi-factor authentication (MFA).  You may sometimes also see this referred to as 2nd factor authentication (2FA), though 2FA is really just a subset of the wider capabilities of MFA, which can combine not just two factors, but many varied forms.  

The basics of Multi-factor authentication is authenticating a user by validating two or more claims presented by the user, each from a different category of factors. Let’s look at an example that you’ve been using for years and probably never even realised; using an Automated Teller Machine (ATM) to withdraw money. 

MFA Factors

ATM multi-factor authentication

Your bank will require you to insert your smart chip equipped bank card into the machine and input a pin code.  You are going to be recorded on video, which could be used for facial recognition and they will have limits on how much you can withdraw per day.  The bank will also use fraud detection algorithms which will block your transaction if you are located somewhere physically different to where your last transaction was recorded, if it’s impractical to travel that distance in the intervening time period.  If the transaction is from a location that is highly suspect, where you aren’t normally located, you might even get a phone call from the bank to confirm.  Let’s review the different authentication factors that are available.

Something you Know
(Knowledge factors)
  • ATM Pin
  • Password
Something you have
(Possession factors)
  • EMV Bank Card with a chip
  • Mobile Phone push notification
Something you are
(Inherence factors)
  • Facial Identification
  • Fingerprint
Somewhere you are
(Location factors)
  • GPS location
  • IP Address
When you act
(Time factors)
  • ATM daily withdrawal limits
  • Temporary passcodes that auto-expire

Why is MFA important ? 

Multi-factor authentication (MFA) is important to protect your confidential information from getting accessed, which could result in trade secrets being stolen, service outages, lost revenue, breach of trust with your customers which might result in regulatory fines and penalties.  

This higher level of security is required for many recognised security standards such as the payment card industry, PCI-DSS and NIST 800-171 which is used to protect Controlled Unclassified Information (CUI) at US government defence contractors.  MFA is actually more important than the strength of your password in securing your account, and in fact Microsoft researchers  have reported that an account is only 0.01% as likely to be compromised if it is using MFA vs using just a password alone !

How does MFA provide additional security ? 

Multi-factor authentication (MFA) creates some additional roadblocks to hackers when they attempt to infiltrate your account. Just creating roadblocks will cause a hacker to move onto the next account, unless you are a high value target. Sometimes an organization will require MFA only for higher risk activities, taking into account a balance of risk and convenience. For example a bank might allow a customer to login to their online banking app using a username and password but require the customer to use biometric authentication such as a fingerprint to additionally authenticate each time the customer tries to transfer money.   Let’s look at some common attacks and how MFA prevents them. 


  • Credential Stuffing – the most common online attack that hackers use is to reuse usernames and passwords leaked in previous attacks, which are readily traded online by criminals. What they are looking for is to see if you’ve used the same username / password combination across multiple systems.  MFA systems protect against this as the other factors are usually not static and a leaked password alone isn’t enough to gain access to your account.
  • Password Leak – Imagine you are about to login to your Couchbase administrator console and type in your password, then hit return.  Only then you realize that you accidentally just typed that into your slack window and provided your password to a public room full of people.  With MFA, you are still secure as the password alone isn’t enough to compromise your account.
  • Malware / Keystroke Logging – an attacker who has managed to load malicious software onto your system can monitor your keypresses and steal your password, but without the MFA which is usually on a separate device such as a mobile phone.  This code is always changing so they are unable to utilize the stolen credentials. 
  • Brute Force –  this where an attacker will systematically try every combination of username and password, usually relying on dictionaries of commonly used passwords as a first pass.  The use of dynamically changing time limited pass-codes, which MFA can provide, makes this attack exponentially more difficult as the time window in which to correctly guess both your password and the dynamic MFA code is tiny.  Additionally, intrusion detection systems (IDS) can spot this unusual behaviour and prevent these types of attacks.

When should you use MFA ? 

Hackers will use every bit of information they can get their hands on to target a victim.  Many times they’ll figure out how to use this information in novel ways that you may never have thought of as being a risk.

The easiest way to secure yourself is to always use MFA when it is presented as an option.  This encourages good security hygiene and protects you even if you don’t think a particular platform requires higher levels of security.  

Implementing different types of multi-factor authentication with Couchbase Server

Common MFA schemes come in several forms, each providing varying levels of security.  Let’s look at each method from least secure to most secure.  And let’s see how we can implement some of the strongest authentication security with Couchbase Server.

Well respected security researcher Troy Hunt calls this order the Hierarchy of Auth.

Password Meh
Password + SMS Okay
Password + Software Token Better
Password + Hardware Token Great
Password + Universal 2nd Factor (U2F) Uber


Password auth is the most basic form of authentication and when used alone it is what is referred to as a Single Factor authentication.  Passwords are required for every user that you create in Couchbase Server, and they can be configured to specific password policies.  Using a strong password, even with MFA in use, is essential. 

This password is normally static, so if it is misplaced or stolen, you are at risk that someone will login to your account and potentially steal your data. You can utilize tools such as the Hashicorp Vault Couchbase integration to generate temporary accounts and passwords that are short-lived and are automatically removed, these are at less risk if they are accidentally exposed. Using x.509 certificates for user authentication is more secure than passwords, but they cannot be used to login to the UI.

Password + SMS

The lowest level of MFA security is to combine a login password with a unique One Time Password (OTP) that arrives to your mobile device over SMS. Unfortunately there’s several well known security holes with using SMS based security.  One of the most known risks that frequently gets mentioned in the press is something known as a SIM Swap Scam.  This is where an attacker, usually through social engineering techniques, convinces your mobile phone carrier to change your phone number over to a new sim card in which they control.  Then the attacker receives any future SMS to their device, including your MFA One Time Passwords.  Recently an organized criminal gang, dismantled by authorities, were able to steal over $100 million USD from victims using this scam.  There are also other methods to eavesdrop on mobile phone communication such as IMSI catchers and SS7 protocol security vulnerabilities.

MFA CellTower

“Cell Tower Vultures” by StephenGA is marked under CC0 1.0.

 The biggest risk with using SMS is if the SMS is used as a single method for account recovery in the event of a lost password, in which case the SMS becomes a single factor that is unfortunately not strongly secure.  

While Password + SMS MFA is more secure than just a password alone, it should generally be avoided so we’ll skip the implementation of this method.

Password + Software Token

Using a software token MFA should be the goal for most MFA deployments as a starting point.  This is a combination of a password (“Something you know”) with a software token (“Something you have”).  The only prerequisite required is that each of your users has a smartphone and a free app such as Google Authenticator or Authy to generate a temporary passcode.    A user will typically scan a QR code into their mobile phone application as a one-time activity when setting up their account.  The mobile phone application will then constantly generate a new code that are time-based and only valid for a short time period such as 30 seconds.  This MFA is known as Time-based One-Time Password or TOTP and is what Couchbase Cloud uses for account security.  Alternatively, some solutions aren’t based on time, and use an incrementing counter with a HMAC-based One-time Password (HOTP) instead.

MFA SmartPhone 2

“hands-coffee-smartphone-technology” by CCØBAY is marked under CC0 1.0

TOTP is easy to set up with Couchbase Server using external authentication.  Using external authentication means we can set up our authentication system once and reuse it across multiple Couchbase clusters.  We’ll use LDAP to make TOTP MFA mandatory in addition to the user providing their password.  Before we get started, first install the TOTP MFA mobile application of your choice onto your smartphone. Again, Google Authenticator and Authy are great choices.

I’ll give an easy example using a simple Go-lang LDAP Authentication Server (GLAuth).  

I will be using Couchbase Server 7.0 Beta but the method shown here will work with any Enterprise Editions of Couchbase 6.5 and later.  The first step is to download the pre-built package from the GLAuth GitHub releases page, which is available across Windows, Linux and MacOS for both x86 and ARM platforms.  I’ll be using the Mac OS version, but you can adjust the binary name for your platform in the example commands.  Also download the sample  configuration file

The sample LDAP configuration includes a user who is configured for TOTP called otpuser and has a password of mysecret. We’ll use this username and password, but we’ll modify the sample configuration file to change the other secrets to new secrets of our own.

I first generated a random string from the MacOS or Linux shell, but you can use any tool you like that generates a 32 character base32 string.  This will be the otpsecret.
$ LC_ALL=C tr -dc 'A-Z2-7' </dev/urandom | head -c 32; echo

Now generate a couple more 16 character random strings, these will be used as backup codes to login in-case the user loses their mobile device or needs to programmatically connect to Couchbase Server and bypass the MFA.  

For each backup code we also need the sha-256 hash


We’ll modify the ldap configuration file to change the otpsecret line and include these SHA256 backup codes with a new line in the configuration starting with passappsha256.

These backup pass-codes must be kept in a safe place, ideally offline. And you wouldn’t want to have plain-text comments in your configuration file which expose passwords like I’ve shown here for demonstration purposes.

I will also disable TLS/SSL for this demo, you will want to enable this in a production environment though !
Change the [ldaps] section to change enabled to false, 

Next we’ll generate a QR code for our phone application,


MFA QR Code from FreeOTP

Change the type from Counter to Timeout
We’ll call the account name Couchbase Cluster otpuser
And use our generated otpsecret string for the secret. 

Now I scan this QR code with my mobile phone app, and it has started generating temporary passwords. 


MFA TOTP App Output

I will then startup my LDAP server with the configuration file. 

Now I will configure my Couchbase Cluster to connect to the LDAP Server, under the security settings of the UI. 

MFA LDAP Settings

MFA – LDAP Settings in Couchbase Server

The LDAP Host is the hostname or IP where the LDAP server is running and the Port is 3893. 

I will configure my cluster to connect to the LDAP server with credentials.

Bind DN = cn=serviceuser,ou=svcaccts,dc=glauth,dc=com
Password = mysecret

Click “Check Network Settings” to test the connectivity to the LDAP server.

Now I will enable LDAP User authentication and test my otpuser account. 

Template is cn=%u,ou=superheros,dc=glauth,dc=com

The username to test with is otpuser

And the password is mysecretXXXXXX  and where XXXXXX is the 6 digit OTP from your mobile app.

Additional MFA LDAP Settings

MFA LDAP Settings User Auth

If that is working and returns a positive result when you test it, then save your LDAP configuration.  If you need more information, please review the documentation on configuring LDAP with Couchbase Server.   You can now add the user otpuser to your Couchbase Cluster as an external user and provide the user some RBAC credentials.

Congratulations, when you login with this user, you will need to provide your OTP MFA appended to the end of the ‘mysecret’ password each time.   Alternatively you can login with the username otpuser and one of the backup pass-codes such as WBMVOM6F4YAQPDBV which will bypass the MFA requirement.

You can repeat the steps to add several more users to your Couchbase cluster.


Password + Hardware Token

The next step up in security is to use a hardware token instead of a mobile app software token. 

This technique is generally more secure than a software token as it is offline and even more difficult for a hacker to acquire.  Other security benefits are that the temporary password length is longer and it helps avoid some misconfigurations that can make software tokens less secure.  The hardware token devices also keep the underlying cryptographic secrets inside their hardware without any interfaces to access them directly, so it’s extremely difficult to accidentally leak this information.  The downside is that each user will need to acquire a physical token to generate their pass-codes.

These hardware tokens come in a few different forms. 

MFA Security Tokens 1

“RSA Tokens” by EdwinMSarmiento is licensed with CC BY-SA 2.0.

MFA Security Tokens 2

“Hardware Authentication Security Keys (Yubico Yubikey 4 and Feitian MultiPass FIDO)” by Tony Webster is licensed with CC BY 2.0.

The first photo is showing devices which have a small LCD screen and will require an internal battery.  They require a user to type a short pass-code that is presented on the screen, into their application.  The pass-code on the screen is ever changing, similar to the software based token earlier.  The most common version of this type of device is the RSA SecureID token.  

The second photo is showing newer style hardware tokens which connect into a host machine or mobile phone via USB, Bluetooth or NFC.  These devices act like a keyboard and directly send the one-time password when they are physically present and a button is pressed, but often do not require an internal battery.  The OTP is typically a long string of random characters, making them very secure.  The most common version of this type of hardware token is a Yubikey from Yubico. 

Let’s look at how to use a Yubikey 5 NFC as a hardware token OTP MFA. Currently as of Feb 2021 these cost around $45 in the US, €45 in the EU and £45 in the UK each, but the same token can safely be used for a wide variety of applications.

We’ll use the earlier software token MFA setup as a starting point, re-using the same LDAP system and adding additional configurations.  Again, the technique shown here will work with Couchbase Server versions 6.5.0 and later.

The first step is to go to  to generate a shared symmetric key for use with the Yubico Web Services.  This will generate a Client ID and Secret Key which we will provide to the LDAP server.  The web form will request an email address and a OTP.  I just inserted my yubikey into the USB and pressed the button while the OTP field of the web-form had focus, letting the device act like a keyboard and type in the passcode.  The first 12 characters that are generated are your yubikey’s unique id, save these as well as the generated yubico clientid and secret for later. 

Next, modify the LDAP configuration file,  uncommenting the lines that start with “yubikeyclientid” and “yubikeysecret”, changing the values to the clientdid and secret provided by Yubico.

Then add the unique yubikey id to the otpuser’s configuration in the LDAP config file.  Remembering that this is the first 12 characters generated when the yubikey button is pressed.

Now stop and restart the LDAP server if it was already running, otherwise just start it up.

Now you can login to the Couchbase cluster as the otpuser.  You will just need to input the password “mysecret” then while the password field is still active press the button on the yubikey with it inserted into the USB interface.  The yubikey will provide a very long and secure OTP appended to the end of the password “mysecret”.  Once you are logged in, you can remove the yubikey from your device.

Password + Universal 2nd Factor (U2F)

The final and most secure method of MFA we’ll look at is Universal 2nd Factor, known as U2F.  The U2F MFA model has all the benefits of the hardware token in the previous example, but one key difference is it is also protected against phishing, where an attacker tricks you into providing the one-time password, usually by creating a fake website that mimics the original one. 

U2F was created as an open standard by Google and Yubico to provide strong protections against phishing, session hijacking, man-in-the-middle, and malware attacks.  It achieves this by having your browser directly interact with the device over USB or NFC interfaces in a 2 way communication when the physical button is pressed on the key. This secure communication is using asymmetric cryptography with public-key authentication.  The key pair created by the U2F device during registration is origin specific.  This embeds a combination of protocol, hostname and port into the key pair. This means, if a phishing site attempts to trick you and isn’t from the same origin, the U2F key will instantly spot the mismatch and the attempt will be thwarted.  The U2F standard is now managed by the FIDO alliance. 

Let’s see how to set up U2F MFA with Couchbase Server.  We could set this up using the same Yubikey 5 NFC from the previous examples, but this time I want to show you that cheaper options are also available.  I picked up a HyperFIDO PRO U2F mini USB key online for only £8, here’s a photo of a similar device from Key-ID.   

MFA Security Tokens 3

© User:Mayopuk / Wikimedia Commons / CC-BY-SA-3.0

Also this time, instead of using LDAP, we’ll use the Linux Pluggable Authentication Module (PAM) method of externally authenticating users, just to show how a different external authentication source can work.   I’m going to do this with the Couchbase Server 7.0 Beta and Ubuntu 18, but the same steps will work on all currently supported versions of Couchbase Server Enterprise Edition and all supported Linux distributions.

The first step is to follow the steps in the Couchbase Server documentation on setting up a PAM authenticated user.

Ensure /etc/default/saslauthd has START=yes

And modify /etc/default/saslauthd adding “ -t 10” to the options string, to add a 10 sec timeout.  For example, 

Also make sure your /etc/pam.d/couchbase file looks like this

After following the steps on configuring PAM you should have a user called “linuxuser” which is defined in your operating system and in the Couchbase Server cluster.  Using the same host in your cluster where you configured PAM, you should be able to login to the cluster’s UI with the username and password.

Next install the U2F PAM module, on ubuntu it’s as easy as this:

Next plug in your U2F device to the USB if it isn’t already.  And make sure that the system running Couchbase Server can see it at an OS level. In my case I have Couchbase Server running on a Ubuntu Linux VM which is running on my mac, so I have to configure my virtualization software to allow the USB device to directly attach to the VM. 

Running lsusb I can see the USB U2F key from my Linux OS. 

Next we need to perform a one-time U2F registration operation and store the output for the pam module to use.  It will tie the linuxuser to a specific U2F key and on a specific hostname. 
sudo pamu2fcfg --username=linuxuser > /tmp/u2f_keys
Enter PIN for /dev/hidraw1: xxxxxxxx

My U2F device is flashing the light until I press the button, and actually my device also requires a PIN code, so it is yet another MFA factor. 

Next change the file permissions, ownership and location.

Now uncomment the last line in the /etc/pam.d/couchbase file, so it looks like this.

And restart saslauthd 

Now when you login to your cluster as the linuxuser account in the Couchbase cluster UI, it will wait for the U2F device’s button to be pressed.  Mine has a light that flashes to indicate it is active and waiting.  After I press this, instantly the U2F keys are exchanged and verified, I am authenticated and can remove the USB device. 

Bonus: Password-less Authentication ! 

If you wanted to try out passwordless authentication, you can now easily do this. 

Obviously this is less secure than using a U2F + password, but it is great for a development Couchbase cluster where you do not store sensitive data and is running locally or firewalled to allow only your IP address to connect.  

In your pam configuration file, from the previous example, comment out the first 2 lines and only leave the U2F requirement,  so your configuration looks like this.

Next restart saslauthd 

Now you can login to the Couchbase Server UI with the linuxuser account by providing the username, any random string in the password field, even just a single character.  Then press on the U2F button when prompted.   Passwordless authentication !


In this article I’ve shown you what Multi-Factor Authentication is, why you should use it and several ways to implement it with Couchbase Server.  

If security is important to you, I recommend reading a few additional blog posts about our various features that help keep your Couchbase data protected. 

And I’ll also share with you some of my favourite sites to keep on top of security topics in general, 


Posted by Ian McCloy, Director Product Management

Ian McCloy is the Director of the Platform and Security Product Management Group for Couchbase and lives in the United Kingdom. His dedicated team is responsible for the Reliability, Availability, Serviceability and Security architecture of Couchbase Server and the SaaS Database, Capella. This team also own cloud-native platforms like the Couchbase Kubernetes Autonomous Operator. Ian has a vast range of experience as a Software Engineer, Technical Support Engineer, Quality Assurance Engineer and Systems Administrator. Ian has led global technical teams for the majority of his 20 year professional career and holds several patents in the areas of information security, virtualisation and hardware design.

Leave a reply