Configure Toopher 2 Factor Authentication to work with APM

Toopher is a 2 Factor Authentication provider (https://www.toopher.com/) that can be configured to work with the F5 Access Policy Manager for authenticating users.  Please visit the Toopher website to find out more information about all the products they offer and how they can possibly help you and your company.

For this article I will demonstrate how to setup Toopher 2 Factor Authentication using an iPhone 6, a Ubuntu server, and an BigIP running Access Policy Manager (APM).  To integrate with APM you will need to select a Toopher-RADIUS implementation strategy.  Toopher-RADIUS is support on both Linux and Windows as the server.  Please check the Toopher documentation for a system that best meets your needs.

Things you will need before you start:
- BigIP licensed for APM (I have tested with 11.5.1 and 11.6.0)
- Ubuntu Server (I used Ubuntu 12.04.5 LTS)
- Mobile Device (I used iPhone 6 running iOS 8.2)
- Toopher iPhone App
- Toopher Developers account (https://dev.toopher.com/account/signup/) Accounts are free if you have less than 10 users.

 

Create Toopher Requestor

The first step is to sign up for a Toopher Developers account and then create a new requestor.  When creating a requestor you will give it a name and a description that will be used by your end users to identify your service.  I named my requestor “Cooper VPN” and used the same for the description.  You will want to use something meaning for your implementation.

After you create your requestor you will be able to see the consumer key and consumer secret.  These values will be needed in the next step as we setup or RADIUS server.

 

Install and configure the Toopher RADIUS server

To configure Toopher to work with APM we will configure Toopher-RADIUS.  The Toopher download site has a package that installs FreeRADIUS and provides the configuration files needed to hook into the Toopher API.  This RADIUS server is acting as a proxy between the APM and the Toopher web service that communicates with your iPhone.  The code and installation instructions are posted on GitHub. (https://github.com/toopher/toopher-radius)  Please download and configure according to your environment.  The following step detail the process for installing and configuring on Ubuntu 12.04 LTS.  We will configure the Toopher RADIUS server to run in Toopher-Only mode.

- Install the package using the install script.  This script will download all packages and dependencies needed to run FreeRADIUS and perl.  If you have issues with the please contact Toopher Support.
- Configure your clients in the clients.conf file.  This will be the Self IP address of the BigIP.  If running in HA then you will use your Floating Self IP.
- Update the toopher_radius_config.pm file with your “key” and “secret” you received in the previous step.
- Update the toopher_users file to enable Toopher-Only mode.
- Start the RADIUS server

 

Configure RADIUS AAA Server in APM

Now that we have the Toopher RADIUS server and the Toopher API setups completed we need to configure the APM.

Create a new RADIUS AAA Object:

1. Navigate to “Access Policy” > “AAA Servers” > “RADIUS”
2. Click “Create”
3. The following settings are what I used but you can change these to fit your needs.
   Mode: Authentication
   Server Connection: Direct
   Server Address: IP Address of Linux RADIUS server.
   Authentication Service Port: 1812
   Secret: Enter secret from when you created your client. (this is the RADIUS client secret not the API secret)
   Confirm Secret:  Enter secret again.
   Timeout: 35 seconds (this was increased from 5 seconds as instructed in the Toopher Install guide)
4. Click “Finished”

We now have a RADIUS AAA object created and we can select it in our VPE Policy.

 

Configure AD AAA Server in APM

Toopher recommends that you use the Toopher service in an authentication chain.  This means that we need to authenticate the user to our Active Directory (or any other provider) before we use Toopher to authenticate.  For this example we will use AD to authentication the user first and then we will send the authentication request to Toopher.  I will assume that you already have your AD server setup and you can authenticate to it from the APM.  If you have problems there are a lot of resources on AskF5 and DevCentral to help you out.

NOTE: If you need to have your users reset their pairing and you have AD auth in front of the RADIUS auth you will not be able to send the RADIUS server the “reset” password.  You will need to have a way for users to do this or setup a way for the helpdesk to reset pairings.  This is outside the scope of this document.

 

Configure the APM VPE

Now we have the AAA objects created it is time to build out our policy.  I have a very basic policy here to demonstrate functionality.  You will need to modify your policy to fit your needs.

Here I have a Logon Page, AD Auth, RADIUS Auth, a Message Box for demo purposes and then Allow.  All of these actions have the default settings except where you have to select your AAA object created above in the AD Auth and RADIUS Auth actions.  I also modified the wording the message boxes to help identify if I was successful or if I failed.

You will need to attach this policy to a virtual server.

 

Test Access

We are now ready to test our access.

1. Open Toopher App on your Mobile Device
2. Open your browser and navigate to the VS that is hosting the policy created earlier.
3. Enter your AD credentials
4. You will be prompted to register your device (if you have not done so already)
5. Allow Access in the Toopher App
6. You will see the successful message box.

If you fail along the way you need to check the APM logs to determine where you failed.  You can also enable debug logging on the Toopher RADIUS server if needed.

NOTE: After you click “Logon” the APM goes to AD to authenticate and after that is successful it then send a request to RADIUS.  The RADIUS request then sends a request to the Toopher API (which is out side your network) and then the user has to approve the access on their phone.  The API then has to reply back to the RADIUS server and then RADIUS replies back to APM.  This process will take a little bit more time than if you were using traditional authentication methods that are local to your datacenter.

 

Customize the Logon Process

The authentication process can take some time as the user has to approve the access on the mobile device.  To let the user know that we are working to authenticate them using Toopher we can customize the logon process.

To customize the logon process will will need to upload the spinner graphic and make modifications to three pages in the advanced customization editor.  We will modify the footer.inc, logon.inc, and apm_full.css pages.

Upload the spinner graphic

1. Save the image below to your PC.

2. Navigate to the Hosted Content section.
     Access Policy > Hosted Content
3. Click “Upload” in the upper right hand corner.
4. Select the graphic above and leave the rest of the fields on the default.  Make sure to leave the Secure Level as public.
5. Click “OK” and the file will be uploaded to the Hosted Content Section
6. We need to associate the Access Policy we created with the Hosted Content so we need to click on “Manage Profile Access” flyout under Hosted Content.
7. Check the box next to the access policy created and click “OK”

Modify files

1. Navigate to the advanced customization editor
     11.6.0 : Access Policy > Customization > Advanced
     11.5.1 : Access Policy > Customization > Advanced : Then change edit mode to “Advanced”
2. Open the “Common” folder in the policy we created.
     Customization Settings > Access Profiles > /Common/cooper-toopher_ap > Common
3. Click on the footer.inc file to load it into the editor window.
4. Add the following code at the bottom of the file.

<div id="loading-div-background">
  <div id="loading-div" class="ui-corner-all">
    <br>
    <br>
    <br>
  <div style="background: #fff; padding:20px; line-height:136%; width: 30%; border-radius: 25px; margin: 0 auto; text-align: center;">
    <h1 style="text-align: center;">Toopher Authentication</h1>
    <br>
    <p>
      <strong>
        We're now contacting your mobile device to authenticate.
      </strong>
    </p>
    <p>
      Please wait...
    </p>
    <img src="/public/share/ajax-loader2.gif" />
  </div>
  </div>
</div>

5. Click “Save Draft” in the upper right hand corner then click “Save” in the editors toolbar.
6. Click on the apm_full.css file to load it into the editor window.
7. Add the following code at the bottom of the file.

div#loading-div-background{
    display: none;
    position: fixed;
    top: 0;
    left: 0;
    background: #c4c2be;
    width: 100%;
    height: 100%;
    font: 75% sans-serif;
} 

8. Click “Save Draft” in the upper right hand corner then click “Save” in the editors toolbar.
9. Navigate to logon.inc file and click on it.
     Customization Settings > Access Profiles > /Common/cooper-toopher_ap > Access Policy > Logon Pages > Logon Page > logon.inc
10. Add the following code inside the head tags on the page.  I placed this above the head close tag (</head>) which should be around line 463.

<script src="//code.jquery.com/jquery-1.9.1.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script> 

<script type="text/javascript">
    $(document).ready(function (){
        $("#loading-div-background").css({ opacity: 1.0 });
    }); 

    function ShowProgressAnimation(){
        $("#loading-div-background").show();
    }
</script>

11. The last little bit of code change we need to make is to find the submit buttons on the page and add an onclick event to them.  There are two buttons on the logon page (depends on how you layout your page which one gets used) and they will be around line 620 after the code addition above.

Change:
<input type=submit class="credentials_input_submit" value="%[logon]">
to 
<input type=submit class="credentials_input_submit" value="%[logon]" onclick="ShowProgressAnimation();">

As you can see we just added an onclick event to the button.  This event along with the JavaScript above, the css in the apm_full.css file and the HTML that we placed in the footer will take over the screen while the form is being submitted.  When the request has been responded to the page will refresh and either show a error message or the next page in the VPE you configured.  In my case it will show a message box that says successful and then click that will take you to my web page (APM+LTM) mode or could take you to a webtop.

A drawback to this is that if a user fails the AD auth then they will see the popup and then get an error message on the logon page.  You will need to make sure the error messages are somewhat meaningful for the users as they might think that the AD auth was successful since they see the “Toopher” popup.

I hope this guide has been helpful and as always if you see any improvements or problems please comment below.

Regards,

Seth Cooper