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



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

// 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 {

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


    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.

    Published Feb 07, 2017
    Version 1.0

    Was this article helpful?


    • Hi, great guide! Are there any work with a guide for Feitian ePass FIDO -NFC ? Br Andréas


    • Hi


      I get an error when trying to execute the LXIrule:


      Executed agent '/Common/yubikeyprocess_act_logon_page_ag', return value 0 Following rule 'fallback' from item 'YubiKey Logon Page' to item 'YubiKey Auth' Executed agent '/Common/yubikeyprocess_act_irule_event_ag', return value 3


      I enabled debugging at the irule but I get no output to the LTM log


      any ideas?


      Much appreciated


    • Great guide, thanks for this!

      I found a small bug in the "YubiKey Serial Match" block, the "Match found" branch has the following expression:

      expr { [mcget {session.yubikey.serial}] eq [string trim [mcget {session.ad.last.attr.employeeID}] 0] }

      should be:

      expr { [mcget {session.yubikey.serial}] eq [string trimleft [mcget {session.ad.last.attr.employeeID}] 0] }

      according to http://wiki.tcl.tk/10174:

      "trim removes characters from the beginning and end of a string"

      We could verify that a yubikey serial with a ending of "0" would not be accepted.


    • Hi Peter,


      I got a FIDO2 capable "Security Key by Yubikey" today, and I'm wondering if it's possible to do first-step authentication of users via FIDO2/Webauthn. Does APM support this?


      I envision being able to log on to e.g. the F5 Access VPN app just by touching an NFC-enabled key to my mobile phone, and authenticating WITHOUT typing in a username by simply using a FIDO2/CTAP2-enabled token to sign whatever the APM portal wants me to sign.


      Not sure if it's relevant to this script, so I'll create a support case if I need to, but you seem like the right guy to answer this :)




      Dag, F5 customer


    • Hi @Moonlit,


      F5 APM does not support FIDO2 yet but this can change in the future :-)


      What you would need is this feature in the VPE (Visual Policy Editor) as a block where you could receive the WebAuthn.


      Sure you could do this maybe with iRulesLX but this would be a full project which need time to develop.


      Maybe F5 can give us some information about the future of FIDO2 support in APM?


      Best regards,