APM Cookbook: Two-Factor Authentication using YubiKey OTP with iRulesLX.

Introduction

It’s been a number of years since I penned my first DC article: Two-Factor Authentication using YubiKey, YubiCloud and APM. A lot has changed over the years, BIG-IP versions and features, new YubiKey models and the YubiCloud Validation API has changed significantly rendering my older article obsolete. This article is a rewrite of the original with a number of improvements, such as:

• No need for HTTP Auth agent
• No need to Reverse Proxy the HTTP connection to the YubiCloud API
• “yub” NPM package used with iRulesLX. This does all the hard work for us, such as signing the message, validating the response and decoding the YubiKey serial.
• HMAC-SHA1 signed message
• Signed response validation
• VPE improvements to protect AD Account Lockouts

YubiKey 2-Factor Authentication Process with APM

The authentication process can be broken down into a few simple steps which is illustrated below and explained in more detail.

Step 1 – The user is presented with a login page. The login page in my example asks for a Username, Password and YubiKey OTP. After entering your username and password, you simply plug in the YubiKey to the USB port and press the button. The YubiKey will generate the unique OTP followed by the enter key.

Step 2 & 3 – APM sends the YubiKey OTP to the YubiCloud validation service. If the YubiCloud API returns “Status=OK”, the signature and the nonce is verified, then we know the YubiKey OTP is valid. This is performed by the “yub” NPM package using iRulesLX.

Step 4 & 5 – Check to make sure the user has been provisioned a YubiKey and the Serial number assigned to that user matches. I store the 8-digit YubiKey serial number to an Active Directory attribute: “employeeID”. Obviously you can use any attribute field you like or you can modify the policy to query a data group.

Step 6 & 7 – The Username and Password is verified by Active Directory/LDAP or what ever is your preference.

Step 8 - On success, grant the user access to the resource.

An explanation of the validation protocol can be found here: https://developers.yubico.com/yubikey-val/Validation_Protocol_V2.0.html. The “yub” NPM module uses this API and simplifies the validation and signing process.

Before we get started

I have a pre-configured Active Directory 2012 R2 server which I will be using as my LDAP server with an IP address of 10.1.30.101. My BIG-IP is running TMOS 12.1.2 and the iRules Language eXtension has been licensed and provisioned. Make sure your BIG-IP has internet access to download the required Node.JS packages.

This guide also assumes you have a basic level of understanding and troubleshooting at a Local Traffic Manager (LTM) level and your BIG-IP Self IP, VLANs, Routes, etc.. are all configured and working as expected.

You have obtained a Client ID and API Key from: https://upgrade.yubico.com/getapikey/ to validate the YubiKey OTP.

Step 1 – iRule and iRuleLX Configuration

1.1  Create a new iRulesLX workspace

Local Traffic >> iRules >> LX Workspaces >> “Create”

Supply the following:

• Name: yubikey_auth_workspace

Select “Finished" to save.

You will now have any empty workspace, ready to cut/paste the TCL iRule and Node.JS code.

1.2  Add the iRule

Select “Add iRule” and supply the following:

• Name: yubikey_auth_apm_event_irulelx
• Select OK

Cut / Paste the following iRule into the workspace editor on the right hand side. Select “Save File” to save.

# Author: Brett Smith @f5

when RULE_INIT {
    # Debug logging control.
    # 0 = debug logging off, 1 = debug logging on.
    set static::yubikey_debug 0
}
 
when ACCESS_POLICY_AGENT_EVENT {
    if { [ACCESS::policy agent_id] eq "yubikey_auth" } {
        # Get the YubiKey OTP from APM session data
        set yubiotp [ACCESS::session data get session.logon.last.yubiotp]
        if { $static::yubikey_debug == 1 }{ log local0. "YubiKey OTP: $yubiotp" }
 
        # Basic error handling - don't execute Node.JS if session.logon.last.yubiotp is null   
        if { ([string trim $yubiotp] eq "") } {
            # The YubiKey OTP is not valid
            ACCESS::session data set session.yubikey.valid 0
            if { $static::yubikey_debug == 1 }{ log local0. "YubiKey OTP is not valid!" }
        } else {
            # Initialise the iRulesLX extension
            set rpc_handle [ILX::init yubikey_auth_extension]
       
            # Need to change the default RPC timeout from 3 sec to 30 sec to 
            # allow for the HTTPS request to the Yubico API
            set timeout 30000
           
            # Pass the YubiKey OTP to Node.JS and save the iRulesLX response
            set rpc_response [ILX::call $rpc_handle -timeout $timeout yubikey_auth $yubiotp]
            if { $static::yubikey_debug == 1 }{ log local0. "rpc_response: $rpc_response" }
            
            # Loop through each key/value pair returned from "yub.verify"
            foreach {key value} $rpc_response {
                # Assign the key/value pair to an APM session variable so it 
                # can be referenced in the Access Policy
                ACCESS::session data set session.yubikey.$key $value
                if { $static::yubikey_debug == 1 }{ log local0. "$key $value" }
            }
        }
    }
}

1.3  Add the Extension

Select “Add extenstion” and supply the following:

• Name: yubikey_auth_extension
• Select OK

Cut / Paste the following Node.JS and replace the default index.js. Select “Save File” to save. Update the “client_id” and “secret_key” variables with your Yubico Client ID and API Key.

// Author: Brett Smith @f5
// index.js for yubikey_auth_apm_event_lx

// Includes
var f5 = require('f5-nodejs');
var yub = require('yub');
 
// Create a new rpc server for listening to TCL iRule calls.
var ilx = new f5.ILXServer(); 
 
// Start listening for ILX::call and ILX::notify events.
ilx.listen();

// YubiKey Auth
ilx.addMethod('yubikey_auth', function(yubiotp, response) {

    // Get a Yubico Client ID and API Key from here: https://upgrade.yubico.com/getapikey/
    var client_id = 'XXXX';
    var secret_key = 'XXXXXXXXXXXXXXX';

    // Initialise the yub library
    yub.init(client_id, secret_key);

    // Attempt to verify the OTP
    yub.verify(yubiotp.params()[0], function(err,data) {
        if (err) {
            console.log('Error: YubiKey OTP Verify Failed!');
            response.reply('valid 0');
        } else {
            response.reply(data);
        }
    });
});

1.4  Install the “yub” package

• SSH to the BIG-IP as root
• cd /var/ilx/workspaces/Common/yubikey_auth_workspace/extensions/yubikey_auth_extension
• npm install yub -save

You should expect the following output from the above command:

[root@big-ip1:Active:Standalone] ldap_modify_extension # npm install yub -save

yub@0.11.1 node_modules/yub

1.5 Create a the iRulesLX plugin

Local Traffic >> iRules >> LX Plugin >> “Create”

Supply the following:

• Name: yubikey_auth_plugin
• From Workspace: yubikey_auth_workspace

Select “Finished" to save.

If you look in /var/log/ltm, you will see the extension start a process per TMM for the iRuleLX plugin.

big-ip1 info sdmd[16339]: 018e000b:6: Extension /Common/yubikey_auth_plugin:yubikey_auth_extension started, pid:975
big-ip1 info sdmd[16339]: 018e000b:6: Extension /Common/yubikey_auth_plugin:yubikey_auth_extension started, pid:976
big-ip1 info sdmd[16339]: 018e000b:6: Extension /Common/yubikey_auth_plugin:yubikey_auth_extension started, pid:977
big-ip1 info sdmd[16339]: 018e000b:6: Extension /Common/yubikey_auth_plugin:yubikey_auth_extension started, pid:978

Step 2 – APM Configuration

2.1  Create a new Authentication Server or reuse an existing server

2.1.1  Access Policy >> AAA Servers >> Active Directory >> “Create”

Supply the following:

• Name: f5.demo_ad_aaa (something sensible)
• Domain Name: f5.demo (Domain Name)
• Server Connection: Direct or Use Pool depending on your setup.
• Domain Controller: <FQDN> or (AD server) or leave blank and APM will use DNS.
• Admin Name and Password

Select “Finished" to save.

2.2  Create an Access Profile and Policy

2.2.1  Access Policy >> Access Profiles >> Access Profiles List >> “Create”

Supply the following:

• Name: yubikey_otp_2fa_iruleslx_ap
• Profile Type: All
• Profile Scope: Profile
• Languages: English (en)
• Use the default settings for all other settings.

Select “Finished" to save.

2.2.2  Access Policy >> Access Profiles >> Access Profiles List >> “Edit”

On the “fallback” branch after the “Start” object, add a “Logon Page” object.

Add a third field:

• Type: text
• Post Variable Name: yubiotp
• Session Variable Name: yubiotp
• Read Only: No

In the “Customization” section further down the page, set the “Form Header Text” to what ever you like and change “Logon Page Input Field #3” to something meaningful, see my example below for inspiration. Leave the “Branch Rules” as the default. Don’t forget to “Save”.

2.2.3  On the “fallback” branch after the “Logon Page” object, add an “iRule Event” object.

This step verifies the YubiKey OTP by passing “session.logon.last.yubiotp” from the ”Logon Page” to the iRuleLX created in Step 1.

Supply the following Properties:

• Name: YubiKey Auth
• ID: yubikey_auth

2.2.3.1  Under “Branch Rules”, add a new one, by selecting “Add Branch Rule”.

Update the Branch Rule settings:

Name: YubiKey OTP Valid

Expression (Advanced): expr { [mcget {session.yubikey.valid}] == "1" }

Select “Finished”, then “Save” when your done.

2.2.4  On the “YubiKey OTP Valid” branch after the “YubiKey Auth” object, add an “AD Query” object.

This step checks if the user has a YubiKey provisioned in their Active Directory account and the Serial number assigned to that user matches. I’ve added the serial number of the YubiKey to the “employeeID” attribute in Active Directory for each user. I used the “employeeID” attribute for simplicity, but I would recommend creating a custom AD attribute for the YubiKey serial number.

Supply the following Properties:

• Name: YubiKey Serial Match
• Server: /Common/f5.demo_ad_aaa (select your AD Server)
• SearchFilter: sAMAccountName=%{session.logon.last.username}
• Required Attributes: employeeID

2.2.4.1  Under “Branch Rules”, delete the default and add a new one, by selecting “Add Branch Rule”.

Update the Branch Rule settings:

• Name: Not Provisioned
• Expression (Advanced): expr { [mcget {session.ad.last.attr.employeeID}] == "" }

Select “Finished.

2.2.4.2  Add another Branch Rule by selecting “Add Branch Rule”.

Update the Branch Rule settings:

• Name: Match Found
• Expression (Advanced): expr { [mcget {session.yubikey.serial}] eq [string trim [mcget {session.ad.last.attr.employeeID}] 0] }

Select “Finished”, then “Save” when your done.

2.2.5  On the “Match Found” branch after the “YubiKey Serial Match” object, add an “AD Auth” object.

This step verifies the username and password is correct against Active Directory.

Supply the following Properties:

• Name: AD Auth
• AAA Server: /Common/f5.demo_ad_aaa (select your AD Server)

Leave the “Branch Rules” as the default. Select “Save” when your done.

2.2.6 On the “Successful” branch after the “AD Auth” object, change the branch end from “ Deny” to “Allow”.

This competes the Access Policy. It should resemble something similar to this:

Step 3 – Virtual Server Configuration

Attach the Access Policy (yubikey_otp_2fa_iruleslx_apldap_modify_ap) to a HTTPS virtual server.

Attach the iRuleLX (yubikey_auth_apm_event_irulelx) under the Resources section.

Conclusion

This is another great example how you can easily add a 2nd factor of authentication to any application using the power of Access Policy Manager (APM). F5 provides a 10 Concurrent User trial version of APM with every BIG-IP licensed with LTM. APM is one of my favourite pieces of technology, it amazes me every day what I can create with this flexible tool. Why not give it a try today.