AJAX SSL-Wizard Referenz
Werbung
AJAX SSL-­‐Wizard Referenz Version 1.0.2+ -­‐ 04.04.2011 Präambel Die vorliegende Dokumentation beschreibt den AJAX basierten SSL-­‐Wizard der CertCenter AG. Der SSL-­‐Wizard kann mit wenigen Handgriffen nahtlos in die Website des CertCenter Partners integriert werden, sodass kostspielige Eigenentwicklungen auf der Seite des Partners nicht nötig sind. Über den SSL-­‐Wizard können Kunden des Partners SSL-­‐Zertifikate bequem und in wenigen Schritten bestellen. Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 1 Inhaltsverzeichnis Präambel ............................................................................................................................................ 1 1 Inhaltsverzeichnis .................................................................................................................... 2 2 Systemanforderungen ............................................................................................................ 3 2.1 Anforderungen an den Webserver .......................................................................................... 3 2.2 Anforderung an den Client .......................................................................................................... 3 3 Download-­‐Paket ....................................................................................................................... 3 4 Basis-­‐Integration auf der Webseite .................................................................................... 4 4.1 Einbindung der SSL-­‐Wizard PHP-­‐Library .............................................................................. 4 4.2 Einbindung der JavaScript-­‐ und CSS-­‐Libraries .................................................................... 4 4.3 Einbindung des Wizard-­‐Containers ......................................................................................... 5 4.4 API Benutzerdaten hinterlegen ................................................................................................ 6 5 Erstellung der Preisliste für den SSL-­‐Wizard .................................................................. 6 6 Nutzung der Callback-­‐Funktionen ...................................................................................... 7 6.1 Methode wizard_on_initialize() ................................................................................................ 7 6.2 Methode wizard_on_ajax_request() ......................................................................................... 7 6.3 Methode wizard_on_recaluclate($price) ............................................................................... 7 6.4 Methode wizard_on_order_succeed($report) ...................................................................... 8 6.5 Methode wizard_on_order_failed($report) ........................................................................... 9 7 Statusabfrage und Zertifikatsübermittlung .................................................................... 9 Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 2 Systemanforderungen 2.1 Anforderungen an den Webserver Serverseitig basiert der SSL-­‐Wizard auf PHP (5.1+) und nutzt SOAP, um mit CertCenter zu kommunizieren. Anforderung PHP Modul soap json Mindestversion 5.1+ Ab PHP 5.2 enthalten, ansonsten json >= 1.2.0 aus PECL. 2.2 Anforderung an den Client Der SSL-­‐Wizard nutzt AJAX (Asynchronous JavaScript & XML), um mit der auf dem Webserver des Partners zur Verfügung gestellten SSL-­‐Wizard-­‐Library zu kommunizieren. Ein Browser der AJAX unterstützt ist somit die Mindestanforderung an die Clientseite. Jeder moderne Browser unterstützt AJAX. Genauere Informationen zur Verbreitung von AJAX in Webbrowsern stellt Wikipedia bereit: http://de.wikipedia.org/wiki/Ajax_%28Programmierung%29#Status.2FVerbreitung Zur korrekten Darstellung des SSL-­‐Wizards wird eine Bildschirmauflösung von mind. 1024x768 Pixeln empfohlen. Der Wizard kommt mit einer Browser-­‐Breite von mind. 800 Pixeln aus. 3 Download-­‐Paket Der SSL-­‐Wizard kann im Partner-­‐Extranet unter https://www.certcenter.de/my/ heruntergeladen werden. Das Download-­‐Paket enthält nach dem Entpacken eine Beispielsdatei (/index.php) und den eigentlichen Wizard, der im Unterordner /sslwizard liegt. Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 4 Basis-­‐Integration auf der Webseite Die Datei index.php im Download-­‐Paket stellt ein Beispiel für die Einbindung in Ihre Website dar. Zur korrekten Einbindung muss spezieller Quelltext an verschiedene Positionen Ihrer Website kopiert werden. 4.1 Einbindung der SSL-­‐Wizard PHP-­‐Library Ganz oben im Quelltext der Website in der der Wizard integriert werden soll muss die Library „sslwizard/library.php“ eingebunden werden (siehe Abbildung 1). Erfolgt die Einbindung nicht in der ersten Zeile, kann der SSL-­‐Wizard unter Umständen nicht korrekt initialisiert werden und meldet Fehler. Abbildung 1 4.2 Einbindung der JavaScript-­‐ und CSS-­‐Libraries Nachdem die Library eingebunden wurde, fügen Sie in der <head></head>-­‐Sektion der Website die nötigen JavaScript-­‐ und CCS-­‐Libraries ein (siehe Abbildung 2). Derzeit benötigt der SSL-­‐Wizard die Prototype Library v1.7, die effects.js aus der script.aculo.us Library, sowie die SSL-­‐Wizard-­‐Library der CertCenter AG. Alle erforderlichen Scripts und CSS-­‐Dateien werden im Download-­‐Paket mitgeliefert und sollten unverändert verwendet werden. Abbildung 2 Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 4.3 Einbindung des Wizard-­‐Containers Mit der Platzierung des Wizard-­‐Containers können Sie bestimmen, an welcher Position und mit welchen Dimensionen der SSL-­‐Wizard dargestellt wird. Platzieren Sie den <div id=“cc_ssl_wizard“></div>-­‐Container einfach an der gewünschten Stelle (siehe Abbildung 3). Abbildung 3 Wie in Abbildung 3 ersichtlich, können die Parameter „product“ und „tax“ angegeben werden. Der Parameter tax legt den MwSt.-­‐Satz fest, der verwendet werden soll. Der Parameter product legt fest, welches Produkt im Wizard konfiguriert und gekauft werden soll. Folgende Werte können als ProductCode verwendet werden: • • • • • • • • • • • • • • • QuickSSLPremium RapidSSL RapidSSLWildcard TrueBusinessID TrueBusinessIDWildcard TrueBusinessIDEV SecureSite SecureSitePro SecureSiteEV SecureSiteProEV SSLWebServer SGCSuperCerts SSL123 SSLWebServerWildcard SSLWebServerEV Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 4.4 API Benutzerdaten hinterlegen Im letzten Schritt müssen noch Benutzerdaten für den API-­‐ und Datenbankzugriff des Partners in der PHP-­‐Library /sslwizard/inc/conf.inc.php hinterlegt werden. Öffnen Sie die Library in einem Editor und passen Sie die Konstanten DB_* sowie CC_API_USERNAME und CC_API_PASSWORD entsprechend an (siehe Abbildung 4) Abbildung 4 Jetzt – nach der korrekten Einbindung aller nötigen Libraries – lädt der SSL-­‐Wizard automatisch beim Aufruf der Website. Sollte er dies nicht tun, prüfen Sie die Schritte erneut und gehen Sie sicher, dass alle Anforderungen an das System (Punkt 2.1) erfüllt werden. 5 Erstellung der Preisliste für den SSL-­‐Wizard Die Preise, die Sie Ihren Kunden über den SSL-­‐Wizard anbieten möchten, können über das CertCenter Partner-­‐Extranet konfiguriert werden. Loggen Sie sich hierzu auf das Extranet ein und wählen Sie in der Navigation „Partner-­‐Ressourcen“ -­‐> „SSL-­‐Wizard Preiskonfiguration“. Direkt-­‐Link zum Preiskonfiguration: https://www.certcenter.de/my/resources/sslwizard/pricelist Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 6 Nutzung der Callback-­‐Funktionen Zur individuellen Integration in vorhandene Systeme des Partners eignet sich die Nutzung der Callback-­‐Methoden in der mitgelieferten /sslwizard/callback.php. Diese Methoden eignen sich insbesondere für die Authentifizierung der Nutzer und die Sitzungsverwaltung, aber auch für die Übernahme von Bestelldaten in lokale Datenbanken des Partners. 6.1 Methode wizard_on_initialize() Diese Methode wird beim Start des Wizards aufgerufen und kann zum Abbruch der Initialisierung oder z.B. zur Weiterleitung auf eine Login-­‐Seite genutzt werden, insofern der Nutzer über keine aktive oder über keine gültige Sitzung verfügt. Es werden keine Parameter übergeben. 6.2 Methode wizard_on_ajax_request() Diese Methode wird bei jedem Aufruf einer AJAX-­‐Funktion aufgerufen. Auch hier kann z.B. geprüft werden, ob eine gültige Sitzung vorliegt, damit keine unautorisierten Bestellungen durchgeführt werden können. 6.3 Methode wizard_on_recaluclate($price) Bei jeder Änderung in der Produktkonfiguration die eine Änderung des Preises zur Folge hat wird die Funktion wizard_on_recalculate aufgerufen. Als Parameter wird der neue Preis übermittelt. Als Rückgabewert wird true/false aktzeptiert. „true“ sorgt dafür, dass die Konfiguration fortgeführt werden kann, wird hingegen „false“ zurückgegeben, erhält der Nutzer einen Hinweis darüber, dass das aktuelle Kostenlimit überschritten wurde und die zuletzt durchgeführte Änderung rückgängig gemacht werden muss, bevor der Bestellvorgang fortgesetzt werden kann. Die Fehlermeldung kann über die callback.php individuell gestaltet werden. Abbildung 5 Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 6.4 Methode wizard_on_order_succeed($report) Nach erfolgreicher Übermittlung einer Bestellung über den SSL-­‐Wizard wird die Methode wizard_on_order_succeed mit dem Parameter $report aufgerufen. $report ist ein PHP-­‐Objekt und enthält alle Informationen, die sich für die Datenbank des Partners eignen. Folgende Daten sind enthalten: $report-­‐>timestamp $report-­‐>payload $report-­‐>CertCenterOrderID Aktueller Zeitstempel in Sekunden (= mktime()) Enthält alle Auftragsdaten als weiteres Objekt Eindeutige CertCenter-­‐Bestellnummer Weitere Details über den genauen Inhalt des payload-­‐Objekts erhalten Sie, wenn Sie sich über die Callback-­‐Methode zum Test eine E-­‐Mail mit dem Inhalt zustellen (siehe Abbildung 6) oder es mitloggen lassen. Abbildung 6 Falls die db.inc.php (bzw. die Klasse CC_DB) eingebunden wurde und die MySQL-­‐ Benutzerdaten korrekt in der conf.inc.php hinterlegt wurden, werden grundlegende Auftragsdaten direkt in Ihre MySQL-­‐Datenbank ZERTIFIKATE geschrieben (SQL-­‐Skript zum Anlegen der Tabelle siehe sslwizard/database/SSLWIZARD.sql). Der SQL INSERT-­‐ Befehl kann von Partner eigenständig angepasst werden, um z.B. Kundenummer oder weitere Daten in die Tabelle zu übernehmen. Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich 6.5 Methode wizard_on_order_failed($report) Nach nicht erfolgreicher Übermittlung einer Bestellung über den SSL-­‐Wizard wird die Methode wizard_on_order_failed mit dem Parameter $report aufgerufen. $report ist ein PHP-­‐Objekt und enthält alle Informationen, die sich für die Datenbank des Partners eignen. Folgende Daten sind enthalten: $report-­‐>timestamp $report-­‐>payload $report-­‐>errors Aktueller Zeitstempel in Sekunden (= mktime()) Enthält alle Auftragsdaten als weiteres Objekt Enthält ein Array mit Fehlermeldungen Weitere Details über den genauen Inhalt des payload-­‐Objekts erhalten Sie, wenn Sie sich über die Callback-­‐Methode zum Test eine E-­‐Mail mit dem Inhalt zustellen (siehe Punkt 6.4) oder es mitloggen lassen. 7 Statusabfrage und Zertifikatsübermittlung Die Statusabfrage und Übermittlung des ausgestellten Zertifikats übernimmt der CertCenter Partner. Zur Abfrage des Status stehen diverse API-­‐Funktionen zur Verfügung. Dem SSL-­‐Wizard liegt unter sslwizard/scripts/statuscheck.php eine simple Version eines Abfragetools bei, das als Vorlage dienen soll. Mit diesem Skript lassen sich alle Statusänderungen abfangen und programmatisch verarbeiten. Das Skript statuscheck.php sollte nach vorheriger manueller Prüfung in regelmäßigen Abstanden automatisch gestartet werden und die Kunden des Partners über die Fertigstellung des Zertifikats informieren (und das fertige Zertifikat ausliefern). Dies kann z.B. automatisch per Cronjob erfolgen. Für weitere Fragen zur Integration wenden Sie sich bitte an den Partnersupport ([email protected]). Copyright © 2011 CertCenter AG. Alle Rechte vorbehalten. Dokument vertraulich
