Kaay eKaay
Hauptseite | Demo     En
SMART LOGIN

Implementierung ekaay-Engine

Voraussetzungen. Für die eKaay-Engine wird ein Webspace mit PHP und mySQL benötigt. Der Webspace muss unter einen öffentlichen URL http://www.my-ekaay-engine.com erreichbar sein, ebenso wie der Portal-Server http://www.my-portal-server.com (die beiden Server und damit ihre URLs können identisch sein). Es wird erwartet, dass die folgenden Standard PHP-Pakete eingebunden sind: curl, gd, hash, mcrypt, mysqli, und openssl.

Ablauf. Der Standard-Ablauf bei der Integration von eKaay in einen bestehenden Portal-Server ist der Folgende:

1. Schritt: Das SDK einhängen und die Datenbank-Angaben machen

eKaayPackage

SDK. Die von eKaay geschickte Datei ekaay.zip entzippen und dieses Verzeichnis ekaay (''SDK'') in den Webserver legen, am besten unter dessen root. Die Skizze rechts zeigt die Verzeichnis-Struktur des SDK's.

Basis-Angaben. Anschließend bitte Folgendes ausführen:

Stand-Alone Version. Jetzt sollte auf der Test-Seite http(s)://www.my-ekaay-engine.com/ekaay/test/ schon der 2D-Code zu sehen sein, mit einem blinkenden grünen Punkt. Solange auf der Test-Einloggseite und der dortigen Activation Unterseite nicht beide 2D-Codes zu sehen sind oder nicht beide Pünktchen blinken, stimmt etwas noch nicht.

Mögliche Problemursachen. Falls die Datenbank noch nicht richtig angeschlossen ist, sollte das durch entsprechende Fehlermeldungen am Browserbildschirm sofort zu erkennen sein. Durch Aufruf des Scripts https://www.my-ekaay-engine.com/ekaay/test/checkenv/ (ist als link ''checkenv'' auf der Test-Seite zu finden) kann geprüft werden, ob alle erforderlichen PHP-Pakete aktiviert sind.

Testen. Wenn alles blinkt, testen Sie das jetzt auf Ihrem Webserver laufende eKaay: Aktivieren Sie eKaay auf Ihrem Smartphone, indem Sie den Activation 2D-Code mit der eKaay App scannen, und loggen Sie sich dann in diesen mitgelieferten Test-Portalserver ein, via Scannen des Login 2D-Codes. Es sollte also so funktionieren wie hier: http://www.ekaay.com/dev/ekaay/test/

Zwischenstand. Nach abgeschlossenem Schritt 1 läuft eKaay also auf dem Portal Webserver, allerdings dort nur mit dem Test-Portalserver (''test''), der als Teil des SDK's dorthin mitgeliefert wurde. eKaay muss jetzt also noch mit dem richtigen Portal-Server ''verheiratet'' werden. Das geschieht in den Schritten 2 und 3.

Anleitungen/Plugins. Bevor Sie mit Schritt 2 und 3 weitermachen, prüfen Sie bitte auf der Seite Integration, ob Ihr Software System dort in der Liste auftaucht. Wenn es dort Anleitungen oder sogar ein Plugin für Ihr System gibt, dann sollten Sie sich an die Anleitungen, die Sie dort verlinkt finden, halten und diese Seite für die Schritte 2 und 3 ignorieren.

2. Schritt: Den Login Aufruf zum Portal-Server hin umleiten

Portal-Server. Auf der Webseite Vorbereitung Portal-Server gibt es die Spezifikationen (L-1) und (L-2) für ein Script und ein Codeschnipsel, die vom Implementierungs-Team beim Portal-Server für den Login bereitgestellt werden müssten.

eKaay-Engine. Auf ekaay-Engine Seite sind in der Datei ekaay/settings.php die Einstellungen für den Aufruf des Login-Scripts beim Portal-Server Seite zu machen, siehe Erklärungen darunter.

define('OS_CALL_SCRIPT','http://www.my-portal-server.com/login.php?q=node'); 
define('OS_POST_PARNAME_USERNAME','user'); 
define('OS_POST_PARNAME_PASSWORD','passwd'); 
define('OS_POST_EXTRA_PARNAME1','ekaay'); 
define('OS_POST_EXTRA_VALUE1','1'); 

Login-Script URL. Mit OS_CALL_SCRIPT wird die URL des Login-Scripts festgelegt. Dabei können feste GET Parameter gleich mit angegeben werden, siehe Beispiel ''q=node''.

Username und Token. Mit den Einstellungen OS_POST_PARNAME_USERNAME und OS_POST_PARNAME_PASSWORD werden die Namen der beiden Parameter für Username und Token, die das Script beim Portal-Server erwartet, festgelegt.

Extra-Parameter. Mit OS_POST_EXTRA_PARNAME1 und OS_POST_EXTRA_VALUE1 kann ein weiterer Paramter an das Login-Script mitgeschickt werden. Es können bis zu 6 solcher Parameter mitgeschickt werden (bis OS_POST_EXTRA_PARNAME6/OS_POST_EXTRA_VALUE6).

Page-ID. Es ist möglich, per URL Parameter 'pageidname' und 'pageidvalue' einen Parametername/-wert Paar gleich beim Aufruf des Login-iframes mitzugeben, der dann als weiterer Parameter an das Login-Script beim Portal-Server mitgeschickt wird - das ist nützlich, wenn die Login-Seite des Portal-Servers eine Page-ID hat, die jedesmal eine andere ist. Der Aufruf des iframes sieht dann so aus (Beispiel Drupal):

<iframe frameborder='0'
  src='https://www.my-ekaay-engine.com/ekaay/ekaaycore/proxy/www/?
  pageidname=form_build_id
  &pageidvalue=form-j3pm-uSN9hl4S8gVQtSh2Ei35J7oMICW6qlWD7ZGrm4' 
  style='margin:5px;width:275px;height:325px'> 
</iframe>
Im Beispiel wird also später beim eKaay-Login der weitere Parameter
''form_build_id=form-j3pm-uSN9hl4S8gVQtSh2Ei35J7oMICW6qlWD7ZGrm4'' an das Login-Script beim Portal-Server mitgeschickt.

Methode. POST ist die Standard Methode für die Parameter des Login Scripts, aber mittels define('OS_CALL_METHOD', 'GET'); können alle Parameter auch als GET Parameter mitgeschickt werden. Bitte das Fragezeichen ? und ggfs. ein abschließendes & in den String OS_CALL_SCRIPT mit hineinnehmen.

Testen des Zusammenspiels. Wenn auf beiden Seiten (Portal-Server, eKaay-Engine) die Änderungen und Einstellungen gemacht worden sind, dann bitte das Zusammenspiel auf der Seite http://www.my-ekaay-engine.com/ekaay/demo/ testen: rechts einen eKaay Account mit einem existierenden Usernamen aus dem Portal-Server anlegen, und dann links den Login in das Portal damit testen.

Current State. Nach abgeschlossenem Schritt 2 kann man sich also mit einem für eKaay aktivierten User beim Portal-Server einloggen. Man kann bislang für einen beliebigen oder zufälligen Usernamen eKaay aktivieren. Diese Möglichkeit muss aber abgestellt werden - das wird im folgenden Schritt 3 gemacht.

Token

3. Schritt: Die Registrierungsseite nicht-öffentlich machen

Problem. Bis jetzt kann jeder Benutzername registriert werden. Natürlich sollten aber nur Benutzernamen registriert werden können, die es beim Portal-Server schon gibt. Und außerdem sollte sich natürlich nur ein Benutzer für eKaay registrieren können, der sich für seinen Account schon erfolgreich beim Server authentisiert hat (per Passwort).

Lösung. Das wird dadurch erreicht, dass die eKaay Aktivierungsseite nur im eingeloggten Zustand angezeigt wird und an sie der Benutzername als Parameter weitergegeben wird. Außerdem wird beim Aufruf der Seite, die die eKaay Aktivierungsseite als iframe enthält, vom Portal Server ein zufälliges ''Reverse-Token'' erzeugt, das - neben dem Benutzernamen - beim Aufruf des iframes an die eKaay Aktivierungsseite mitgegeben wird und dann von der ekaay Engine geprüft wird, indem er eine interne Rückfrage an den Portal-Server stellt, ob das Reverse-Token für den Benutzer gültig ist. Die Idee mit dem Reverse-Token ist also die gleiche wie beim eKaay Login, nur in umgekehrter Richtung, siehe Skizze rechts (zum Vergrößern anklicken).

Portal-Server. Beim Portal Server sind also die Änderungen (A-1) bis (A-4) für die Aktivierung zu machen, siehe die Seite Vorbereitung Portal-Server.

eKaay Engine. Bei der ekaay Engine sind nur folgende Einstellungen zu machen:

define('OS_CHECK_REV_TOKEN', true); 
define('OS_CHECK_REVERSE_TOKEN_SCRIPT_URL',
       'http://www.my-portal-server.com/ekaayCheckReverseToken.php?');
Mit OS_CHECK_REV_TOKEN wird die Prüfung des reverse-tokens eingeleitet (damit verschwindet auch die Warnanzeige im Aktivierungs-iframe). OS_CHECK_REVERSE_TOKEN_SCRIPT_URL gibt die öffentliche URL des beim Portal-Server implementierten Prüf-Skripts an. Bitte wie im Beispiel das Fragezeichen ? bzw. ein & hinten anhängen.

Testen des Zusammenspiels. Wenn beim Portal-Server alle Änderungen (A-1) bis (A-4) und die Einstellungen bei der eKaay Engine gemacht worden sind, dann bitte das Zusammenspiel testen: Wenn in dem rechten iframe auf der Test-Seite http://www.my-ekaay-engine.com/ekaay/demo/ noch ein 2D-Code zu sehen ist, dann ist was schiefgegangen. Aber andererseits sollte - eingeloggt im Portal - das eKaay Aktivierungs-iframe für diesen eingeloggten Benutzer zu sehen sein und die Aktivierung bzw. Neu-Aktivierung durchführbar sein.

Notwendigkeit. Auf keinen Fall darf Schritt 3 ausgelassen werden - ansonsten stehen für Angreifer die Benutzer-Accounts des Portals da wie offene Scheunentore.

Zwischenstand. Nach abgeschlossenem Schritt 3 läuft eKaay in der Grundversion auf dem Portal-Server.

4. Schritt: Einstellungen festlegen

Wenn das ekaay Verfahren durch die Schritte 1 bis 3 in der Grundversion implementiert ist, kann es durch Einstellungen (''Stellschrauben'') noch weiter gestaltet werden. Die beiden wichtigsten Einstellungen sind die folgenden:

Weitere Einstellungen. Viele weitere Stellschrauben sind in der Datei mit den default-Einstellungen ekaay/ekaaycore/server/system/config/settings_default.php

Eine Liste mit allen Konstanten zum Einstellen von eKaay steht hier.

Überschrieben werden die default Einstellungen durch define() Befehle in ekaay/settings.php. Bitte nicht in ekaay/ekaaycore/server/system/config/settings_default.php überschreiben, denn dann sind die Einstellungen nach einem Update weg.

Sprache. Mit ''define('OS_LANG', 'en');'' und ''define('OS_LANG', 'de');'' können Sie auf englische bzw. deutsche Texte umschalten.

Texte. Änderungen der Texte können in ekaay/settings.php gemacht werden, Die Namen der zu setzenden Konstanten und deren Default-Werte sind in ekaay/ekaaycore/server/system/config/texts_de_default.php zu finden. Hier sind ein paar Texte-Definitionen, jeweils mit den default Werten:

//login iframe: 
    define('TEXT_HOME_ekaay_login', 'eKaay Login (<a href="http://www.ekaay.com" target="_top">Info)');
// main subpage activation iframe
    define('TEXT_REGISTER_welcome_left', 'Willkommen Benutzer <b>'); 
    define('TEXT_REGISTER_welcome_user_name', true); // show username 
    define('TEXT_REGISTER_welcome_right', '</b> !'); 
// page activation iframe containing 2D Code
    define('TEXT_REGISTER_online_act', 'Aktivieren Sie hier Ihren eKaay 
            Zugang (<a href="http://www.ekaay.com" target="_top">Info). 
            Ihr Passwort-Login bleibt parallel bestehen.');
An den Beispielen erkennt man, dass man auch Formatierungen und weblinks in die Texte hineinnehmen kann.

Styles. Änderungen der html Darstellung können in ekaay/settings.php gemacht werden. Die Namen der zu setzenden Konstanten und deren Default-Werte sind in ekaay/ekaaycore/server/system/config/styles_default.php zu finden. Die wichtigsten Einstellungen sind die folgenden, jeweils mit den default Werten.

//login iframe: 
    define('STYLE_HOME_body', 'background-color:white;color:#00A;margin:5px;');
    define('STYLE_HOME_tbl_login', 'background-color:#F0F0FF;width:180px;min-height:250px;
            border:1px solid black;align:center;margin:3px;padding:3px;font-size:80%;');
// activation iframe:
    define('STYLE_REGISTER_body', 'background-color:white;color:#00A;margin:5px;');
    define('STYLE_REGISTER_main_div', 'background-color:#F0F0FF;width:425px;min-height:204px;
            border:1px solid black;margin:10px;padding:10px;font-size:85%;');
// the blinking dot - turn it off via display:none 
    define('STYLE_HOME_polling', 'padding:3px;display:inline;'); 
    define('STYLE_REGISTER_polling', 'padding:3px;color:#F0F0FF;display:inline;'); 

QR-Code. Die Farbe, die Hintergrundfarbe und die Größe des QR-Codes kann in ekaay/settings.php eingestellt werden, ebenso wie das kleine Logo auf dem QR-Code.

define('STYLE_HOME_color_qr_code_r', '8'); //color qr code
define('STYLE_HOME_color_qr_code_g', '114');
define('STYLE_HOME_color_qr_code_b', '192');
define('STYLE_HOME_bgcolor_qr_code_r', '246'); //background color qr code
define('STYLE_HOME_bgcolor_qr_code_g', '246');
define('STYLE_HOME_bgcolor_qr_code_b', '242');
define('STYLE_HOME_size_qr_code', '111'); // size qr code
define('STYLE_HOME_size_qr_code_rsa', '195'); //size offline login qr code
define('STYLE_REGISTER_size_qr_code', '198'); //size activation qr code
define('STYLE_HOME_show_portal_logo_on_qr_code', true);

Logo. Das Logo ekaay/logo.png erscheint als Icon für diesen Account auf der ''Account Liste'' auf dem Handy des Benutzers. Ersetzen Sie also die bestehende logo.png Datei durch Ihr quadratisches Logo (z.B. Ihr Favicon) im PNG-Format. Optimale Größe des PNG-Bildes: ca. 80x80 Pixel - bitte nicht viel größer, sonst dauert beim Aktivierungs-Vorgang der Download des Bildes auf das Handy des Benutzers zu lange. Mit ''define('STYLE_HOME_show_portal_logo_on_qr_code', true);'' erscheint dieses Logo auch auf dem QR Code.

Webserver. Falls der Portal-Server einen Apache Webserver hat, werden die Zugangsberechtigungen schon von den mitgelieferten .htaccess Dateien geregelt. Falls ein anderer Webserver läuft, sollten die folgenden Berechtigungen für die jeweiligen Verzeichnisse vergeben werden (und deren rekursive Unterverzeichnisse - das gilt aber bei den meisten Webservern implizit.)

ekaay/ deny from all
ekaay/ekaaycore/proxy/www/ allow from all
ekaay/ekaaycore/proxy/www/config deny from all
ekaay/ekaaycore/server/wwwsrv/_srv allow from all

5. Schritt: Polieren, Testen und Übertragen

Testen. Wenn alle Einstellungen gemacht sind, heisst das Motto ''testen, testen, testen ...'' - wie bei jedem IT-Projekt.

Übertragung Live System. Wenn alles getestet ist und läuft, kann das Verfahren vom Testsystem ins Live System übertragen werden (copy+paste+adjust).

SDK Update

Ein neue Versions des SDK wird eingespielt, indem folgendes Verzeichnis ersetzt wird:

Im SDK sollte nie woanders geändert werden als in den settings Dateien im obersten Level von ekaay/. Auf diese Weise bleiben bei einem Update alle Einstellungen erhalten.

Upward-Kompabilität. eKaay verpflichtet sich zur Upward-Kompabilität des SDK's. D.h., wenn Sie einmal eKaay implementiert haben, wird das Verfahren auch ohne SDK-Updates weiterhin laufen, auch bei einem Update der eKaay App auf den Handys der Benutzer. Einschränkung: Die Upward-Kompabilität für das eKaay SDK kann natürlich nur garantiert werden, solange sich die ursprüngliche PHP Version auf dem Webspace, auf dem die eKaay-Engine läuft, nicht ändert.

Über eKaayeKaay VariantenSicherheitLizenzImplementierungKontakt
Über uns
Entwicklung Smart Login
Aktuelles
eKaay original
eKaay PIN
eKaay NFC
eKaay light
eKaay PIN light
eKaay Sign
SicherheitsvergleichLizenz
Preisliste
Referenzen
Integration
Implementierung
Kontakt
Impressum