Software development kit

New in version 6.0: SDK for external mode

New in version 8.0: SDK for external and local mode

Current SDK Version: 18.0

Hint

  • The SDK comes preinstalled on every IACBOX with the custom logon page/custom webserver.

  • If a central installation (for many systems) is needed, the SDK can be installed on an external webserver.

The SDK provides a small PHP framework which abstracts all the tiny details away and lets you easily make customization and/or create new plugins and extensions.

The SDK written in PHP provides you with a sample login page and plugins for many different authentication methods. Starting with version 2 the SDK is also used for the local custom webserver.

Downloads

You will find the SDK for external use in the download section of our homepage or in the my.iacbox partner-portal.

Login-API operation modes

Ahead of any other decisions that have to be made, you have to be aware of two very different operation modes of the Login-API. You have to choose which one serves your needs:

1. External Mode: this is the normal mode of version 1.x. The Login-API SDK is hosted on an external webserver by yourself.

  • Advantages:
    • Allows to point any number of IACBOXes to this login page.

    • One single place to make changes.

    • Centralized data storage possible.

  • Disadvantages:
    • You have to host the SDK on an external webserver which has to be maintained and configured by yourself.

    • Slower than local mode and consumes uplink bandwidth.

    • Without any failover architecture this external server is a single point of failure.

2. Local Mode: Since version 8.0 an IACBOX comes equipped with a custom logon webserver with PHP 5.6 and the preinstalled SDK replacing the traditional loginpage. So this can also be used to just change the look of the login page like it wasn’t possible before.

  • Advantages:
    • The login page ist fast no matter how slow or unreliable your uplink is.

    • The traffic to your login page is only local and does not utilize your upstream.

    • Make easy and fast changes with the built-in code editor.

    • Fewer redirects compared to the external mode, less complex plugins.

  • Disadvantages:
    • If you are using multiple systems you have to make your changes on every IACBOX separately.

    • If you want to manage a central database with authentication data and having logs of logins the local mode still allows that but it is harder to achive

    • Currently no local database available.

Login-API SDK architecture

../_images/loginapi2_plugin_architecture.png

Configuration

The configuration of the Login-API SDK is handled in two different places. The main configuration can be found in conf/main.config. Everything important regarding the Login-API is handled there.

Configuration key

Since

Default

profile-desc

2.0

[profilename]

Name of the profile

company-name

2.0

Will be the title of the logon page

company-name-legal

2.0

Shown on the end of the logon page

logo

2.0

login_logo.png

Logo which should be used

background-image

17.0

login_bg_full.jpg

Backgroundimages shown on the logon page

show-welcome-header

17.0

true

Should the Headermessage be shown

show-lang-select

17.0

true

Should the language selection be shown

template

17.0

index_view.php

Determines which template will be the default tempalte

plugins

2.0

Plugins which should be used for the logon.

languages

2.0

en

Available languages for the logon page. Only needed for the external version

fallback-language

2.0

en

Will be used if a language could not be found

location-based

2.0

false

Enable location based configuration

location-id-fields

2.0

iacbox

Fields to determine different locations

base-url

2.0

https://hotspot.internet-for-guests.com

Should not be changed except you use another base-URL for the Surf-LAN

webserver-url

2.0

Url of your Webserver used for plugins with callbacks from externel servers

sender-name

2.0

Name of the sender (used in payment plugin only)

sender-email

2.0

Email address which will be shown in email (used in payment plugin only)

log-level

2.0

INFO

Determines the log level for the Login-API

redirect-url

2.0

Redirect after the login

show-terms

2.1

true

Show the terms of use (no checkbox)

show-privacy-policy

2.1

true

Show the privacy policy (no checkbox)

force-terms

2.0

true

Force to accept the terms of use

force-privacy-policy

2.1

false

Force to accept the privacy policy

encryption

2.0

Has to match the configuration in Module/Interfaces/Login-API on the IACBOX

encryption-shared-secret

2.0

The shared secret can be found in Module/Interfaces/Login-API on the IACBOX

use-browser-auto-settings

2.0

The Browser should use autocomplete, autocapitalization, spellcheck and autocorrect features

custom-services

2.0

Register one or more custom services (separated by commas)

test-template

2.0

Creates a fake session for testing purposes

refresh-id-mapping

2.0

Refresh call to a certain page

lgnapi-version

2.0

Version of the API / protocol

use-rdbms

2.0

Loads the RdbmsConnector to hold and manage a connection to your database.

Attention

  • Please note that the configuration use-rdbms can only be used with an external DB

  • Create a secure connection to your DB! (e.g.: VPN)

The second part of the configurations are the plugin specific configurations. This files can be found in Iacbox/LoginApi/Plugin/[Plugin]/[plugin].conf. Which configurations have to be done depends on the plugins you have activated in conf/main.conf. For further informations which configurations are possible read the Plugin configuration documentation.

Existing plugins

Pluginname

Since

Type

Usage

Ticket

1.0

AuthPlugin

loc, ext

Ticket/ Voucher Login

Pms

1.1

AuthPlugin

loc, ext

PMS Login

PwdOnly

1.4

AuthPlugin

loc, ext

Password only Login

Free

2.0

AuthPlugin

loc, ext

Free login coupled with Free Logon or Take online

Social

2.0

AuthPlugin

loc, ext

Social login (Facebook, Google+, Twitter)

Payment

2.0

AuthPlugin

loc, ext

Payment plugin (PayPal, Sofortüberweisung)

Email

2.0

AuthPlugin

loc, ext

Email Login coupled with Email Messaging Module

Sms

17.0

AuthPlugin

loc, ext

SMS Login coupled with SMS Messaging Module

Status

2.0

Others

loc, ext

Status information of the client

Ads

2.0

Others

loc, ext

Show advertisement before logon

Socialshare

2.0

Others | loc, ext

Show sociale like/share buttons

loc = available in local mode, ext = available in external mode

Styling

Template changes can be made on two different places. The structure of the main page can be changed in htdocs/index_view.php. It is also possible to create your own page and include it in the htdocs/index.php. The main CSS file can be found in htdocs/css/style.css. We recommend to use the overlay file htdocs/css/style_overlay.css for changes to the CSS because the style.css will be updated regularly.

Some plugin specific CSS classes can be found in the corresponding CSS file Iacbox/LoginApi/Plugin/[Pluginname]/css/. If there is a need to change the template structure of a plugin this can be done in the file [pluginname](_local).php. Please note that if you create your own plugin you are not bound to the naming convention for templates we are using in the already existing plugins.

Translations

General translations are stored in conf/lang/[language].lang. Plugin specific translations can be found in Iacbox/LoginApi/Plugin/[Pluginname]/lang/. The LoginApi provides translations for all 23 languages of the normal logon page but not all languages are fully translated.

Hint

  • Since version 17 it is possible to add translations for the selection of gender and building mapping in the PMS configuration.

  • The translation-keys need to be lowercase and separated per “-” (dash)

  • Example: building-mapping = 1:house-a; 2:house-b

Logging

System log

Externale Mode

As default the SDK logs to your syslog - depending on your Linux distribution this is /var/log/syslog or /var/log/messages. On newer systems which use systemd you can see your logs with jounalctl -f. All messages start with LGNAPI which makes it simple to filter (adding | grep LGNAPI). If you encounter any errors (especially white pages what means PHP had an fatal error) then you should look into your webserver log - for apache this is very often /var/log/apache2/error.log or similar.

Local Mode

The SDK logs per default to the syslog of the IACBOX. All messages start with LGNAPI which makes it simple to filter. The System logs can be downloaded in the menu Reporting/System.

If you encounter any errors (especially white pages what means PHP had a fatal error) then you should look into the log of the Login-API webserver. This log can be accessed if you connect via FTP with the user sysop.

Database

If you want to log the messages in a database, which is available in both modes, there is already a custom service called DBLogger part of the SDK. This is made for external Login-API but theoretically possible in local mode too when writing to an external database (But this is probably a performance issue). Be sure to have this config lines in your main.config

conf/main.config
1
2
3
4
5
6
use-rdbms = true
db-type = <database type like pgsql or mysql>
db-host = <database host>
db-name = <database name>
db-user = <database user>
db-pwd = <database password>