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 IAC-BOX 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 seperately.
    • 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 handeled in two different places. The main configration can be found in conf/main.config. Everything important regarding the Login-API is handeled 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 changend in htdocs/index_view.php. It is also possible to creae 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 alle 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 seperated 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 an 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 propably 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>