Column | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IntroductionBuypass 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 solutionThe 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 PrerequisitesIn order to use Buypass Code with IBM Security Access Manager (ISAM) you need the following:
Setup and configuration of IBM Security Access Manager is outside the scope of this document. Adding your keystore fileWhen 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
Deploying the authentication mechanismImport bundleThe 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 MechanismNow 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 PolicySelect 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 PolicySelect 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. Upload template filesSelect Secure Access Control→Template Files Navigate to the C folder Then select Manage→Import Zip. Browse to the buypass-code-api-template-files-<version>.zip file in the Import a file dialog and click the Import button. Load the Buypass endpoint certificateThe Authentication Mechanism use HTTPS for communicating with the Buypass Code Authentication service. The SSL certificate for Buypass endpoint must be loaded into the IBM Security Access Manager. The first step is to export the certificate from the endpoint. 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. Verify Network ConfigurationIn 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 mechanismThere are two different approaches for testing the authentication mechanism. Use a direct linkThis method requires that an enabled authentication policy is configured. The link below will invoke the authentication mechanism. https://<reverse-runtime-ip>/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:buypass_code_api Access a protected resourceThis method requires that a policy is attached to a resource. By accessing a protected resource, the authentication mechanism will be invoked. https://<reverse-proxy-ip>/test/<resource> TroubleshootingFor 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. |
Downloadable resources
Maven project for Buypass Code API ISAM Authentication Mechanism
code-authentication-api-isam-v1.0.4.zip
Buypass Code Authentication API Client Library for Java
code-authentication-api-client-1.0.3-jar-with-dependencies.jar
Maven project for Buypass Code Authentication API Client Library for Java
code-authentication-api-client-v1.0.3.zip