ActiveAuth

Documentation

Documentation > Integrations > Perl

Perl integration

0. Before you start

0.1 Download the ActiveAuth Perl package

ActiveAuth-Perl-master.zip

Package contains:

  • js - ActiveAuth javascript library, to be hosted by your webserver.
  • ActiveAuth.pm - ActiveAuth Perl SDK to be integrated with your web application
0.2 Make sure you have an ActiveAuth account

Make sure you have active ActiveAuth account. If not you can register one for free.

0.3 Make sure you have an integration

Make shure you have an integration configured in your ActiveAuth control panel.

0.4 Generate application key

Your application key (or akey) is a string that you should generate and keep secret from ActiveAuth. It should be 40 characters long and stored alongside your integration key, secret key, integration account and integration server in configuration. This should be done once.

You can generate a random string in Perl with:

perl -e 'print join "", map { sprintf "%08X", rand(0xffffffff) } 1 .. 5'

1. Sign your request

After you perform primary authentication (username and password), you should prepare signature for the secondary authentication process by calling ActiveAuth::sign method:

my $secret = ActiveAuth::sign($username, $ikey, $skey, $akey);

Where:

  • $username is the e-mail of the already first-step-authenticated account
  • $ikey is the integration key you get from ActiveAuth's control panel
  • $skey is the server key you get from ActiveAuth's control panel
  • $akey which is the application key you generated

2. Show the IFRAME

After generating the signed request, your server should now display an IFRAME used for secondary authentication.

ActiveAuth’s JavaScript handles the setup and communication between the IFRAME, the user, and your server. All you need to do is include a short snippet of JavaScript in the page:

<iframe src="" id="acaframe"></iframe>
<script type="text/javascript">
  var ACASecret = '$secret';
  var ACAServer = '$server';
  var ACAAccount = '$iaccount';
  var ACAAction = '';
</script>
<script type="text/javascript" src="js/activeauth.js"></script>

Where:

  • $secret is the signature generated in the previous step
  • $server is the address of ActiveAuth server (activeauth.me)
  • $iaccount is the e-mail of the integration account, whch owns the integration (NOT the authenticated user) in the ActiveAuth service control panel.
  • In the ACAAction variable you can specify the FORM action to POST to where the second-step authentication is to be verified.

4. Verify the response

After the user authenticates (e.g. via mobile push, phone call, SMS passcode, etc.) the IFRAME will generate a signed response and will send it back to the JavaScript. It will make a POST call to ACAAction, specified in the previous step. Your server-side code should then call ActiveAuth::verify() to verify that the signed response is legitimate:

my $response = $q->param("2fa-verify");
my $status = ActiveAuth::verify($response, $skey, $akey);

Where:

  • $response is the signed response received from the ActiveAuth server
  • $skey is the server key you get from ActiveAuth's control panel
  • $akey which is the application key you generated

If sucessfully authenticated the returned value ($status) should be the e-mail of the authenticated user. Otherwise the method will return undef. After getting user's e-mail, you can create your application session for the sepcified user.