Introduction

Buypass Code is a Multi-factor One-Time Password authentication solution. The first factor is the hardware device in which the Buypass Code app is activated and the second factor is a PIN code or a fingerprint scan.

While activating the Buypass Code app on a hardware device the end user must enter his mobile phone number. An activation code is sent to the end user's phone, which establish a binding between the mobile phone number and the hardware device. The end user must set a PIN code the first time he activates a Buypass Code app.

Overview of the solution

The Buypass Code authentication mechanism for IBM Security Access Manager combines LDAP lookup of the user and verfication of One-Time Passwords generated with a Buypass Code app.

The user must exist in the LDAP directory under the configured ldapBaseDn and the username must be in the LDAP attribute as in the configured ldapUserAttrName. It is required that the user mobile phone number is present in the LDAP user registry in the attribute corresponding to the configured ldapPhoneNumberAttrName.

If the user is found in the LDAP user directory a HTML page is presented to the user. On this page, the user must enter a One-Time Password from his Buypass Code app. The Authentication Mechanism sends the One-Time Password to the Buypass Code Authentication API, which returns either a success or a failure message.

The following sequence diagram shows the authentication flow

Prerequisites

In order to use Buypass Code with IBM Security Access Manager (ISAM) you need the following:

1. IBM Security Access Manager version 9.0.2.1
2. The Buypass Code Authentication Mechanism bundle (buypass-code-api-isam-<version>-bundle.jar)
3. The HTML pages which must be imported in ISAM (buypass-code-api-template-files-<version>.zip)
4. A PKCS12 keystore file containing your client certificate issued by Buypass (p12 file)
5. The password protecting the PKCS12 keystore file
6. Knowledge about IBM Security Access Manager

Setup and configuration of IBM Security Access Manager is outside the scope of this document.

Adding your keystore file

When registering to use Buypass Code you will recieve a client certificate. The certificate is delivered as a PKCS12 keystore file with .p12 extension. You will also recieve a password, which is required to open the keystore file.

The p12 file must be added to the authentication mechanism bundle jar file

1. Open the authentication mechanism bundle jar file with a ZIP File Opener like WinZip or 7-zip.
2. Drag the p12 file into the archive.

Deploying the authentication mechanism

Import bundle

The first step is to import the Buypass Code Authentication Mechanism bundle. Logon to the IBM Security Access Manager and select Secure Access Control->Extensions. Click the Import button and browse to the buypass-code-api-isam-<version>.jar.

Then click the Import button in the Import Bundle view. The bundle is now registered as an extension as shown below.

New Authentication Mechanism

Now select Secure Access Control->Authentication. Then select the Mechanism tab and click New Authentication Mechanism. Finally select Buypass Code API Authentication as shown below.

Fill in the New Authentication Mechanism view as shown below.

Then select the Properties tab.

The properties are explained in the table below.

Click the Save button and the Authentication Mechanism shows up in the Mechanism tab.

New Authentication Policy

Select the Policies tab and click New Authentication Policy. Fill in the values as shown below.

Click the Add Step button and select Buypass Code API from the list.

Then click the Save button.

Create Policy

Select Secure Access Control→Access Control. On the Policies tab click Create Policy.

Fill in the name of the Policy and click the Add Rule down arrow.

Select Permit with Authentication from the first dropdown list and Buypass Code API from the second.

Click the OK button followed by the Save button.

Now select the Resources tab.

Here you should configure the resources that you want to protect with the Authentication Mechanism. Consult the IBM Security Access Manager documentation for details.

Select the resource you want to protect and click the Attach button.

In the Attach Policies view, select the Buypass Code API policy.

Then click the OK button.

The Buypass Code API policy is now attached to the resource.

Click the Publish button to make the changes take effect.

Browse to the buypass-code-api-template-files-<version>.zip file in the Import a file dialog and click the Import button.

Open a Chrome browser window and enter https://api.buypass.no

Then press F12 to open the Chrome developer tools.

Select the Security tab and click the View certificate button.

In the Certificate window select the Details tab and click the Copy to File... button.

Finish the Certificate Export Wizard by saving the certificate to a buypass.cer file.

Select Manage System Settings→SSL Certificates.

Select the rt_profile_keys entry and click Manage→Edit SSL Certificate Database.

In the Import Signer Certificate dialog browse to the buypass.cer file.

Then choose a Certificate Label, for instance "Buypass" and click Import.

Now the Buypass endpoint certificate is loaded in the IBM Security Access Manager.

In order to assure network connectivity with the Buypass endpoint we should inspect the Network Configuration.

Select Manage System Settings→Static Routes

If there is no default route click the New button.

Type default in the Destination field and your default gateway in the Gateway field.

Then click the Save Configuration button.

Testing the authentication mechanism

There are two different approaches for testing the authentication mechanism.

https://<reverse-proxy-ip>/test/<resource>

Troubleshooting

For troubleshooting the Authentication Mechanism you can enable logging.

Select Monitor Analysis and Diagnostics→Runtime Tracing.

Enter no.buypass=ALL in the Tracing Specification.

Then click the Save button.

The log output is written to a trace file. Select Monitor Analysis and Diagnostics→Application Log Files. Under access_control/runtime the trace.log file is located.