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.
- Peter_BaumannCirrostratus
Hi @Moonlit,
Maybe F5 can give us some information about the future of FIDO2 support in APM?
Best regards,
- MoonlitCirrus
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 :)
Sincerely,
Dag, F5 customer
- SmithyCirrostratus
Thanks Peter. trimleft is a better.
- Peter_BaumannCirrostratus
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.
Peter
- Manuel_Cristob2Nimbostratus
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
- forsanAltostratus
Hi, great guide! Are there any work with a guide for Feitian ePass FIDO -NFC ? Br Andréas