How To: Implementierung einer CA API Gateway Custom Assertion in wenigen Schritten

CA Technologies - Partner von APIIDA AG

CA Technologies - Partner von APIIDA AG

von Lucas Lenz, APIIDA AG

Verwenden Sie ein API Gateway von CA? Wenn ja, dann hatten Sie bereits Kontakt mit den Assertions, die von den CA API Gateways verwendet werden, um spezifische Aufgaben/Prozesse umzusetzen. Mithilfe der Assertions können verschiedenste Szenarien und Prozesse implementiert werden. Es gibt sie in Hülle und Fülle und sie decken die gängigsten Szenarien ab. Doch was können Sie tun, wenn es keine passende Assertion für Ihren Anwendungsfall gibt? Die Antwort lautet: Custom Assertion, das heißt, Eigenentwicklung einer Assertion. Eine Custom Assertion gibt Ihnen die Möglichkeit, Ihre Prozesse zu implementieren und diese in das CA API Gateway zu integrieren. Das hört sich vielversprechend an. Dieser Blogbeitrag ist Ihr Einstieg in die Thematik.
Entwicklungsumgebung
Bevor wir beginnen, müssen wir unsere Entwicklungsumgebung aufsetzen. Hierfür benötigen wir die aktuelle Version von Eclipse, welche hier heruntergeladen werden kann.
Neben Eclipse benötigen wir noch das Java SDK, da das CA API Gateway in Java entwickelt wurde und Assertions demnach auch in Java entwickelt werden müssen.
Zum Schluss benötigen wir ein Plug-In für Eclipse. Dieses Plug-In hilft uns bei der Erstellung der Custom Assertion. Das Plug-In ist hier zu finden. An dieser Stelle sei gesagt, dass das Plug-In kein offizielles Produkt von CA ist. Es wurde von der Community entwickelt, weshalb diese auch der Ansprechpartner bei etwaigen Problemen ist. Obwohl es nicht offiziell vertrieben wird, ist es doch die beste Methode, um sich an die Entwicklung heranzutasten.
Nachdem Eclipse aufgesetzt und konfiguriert ist, wird das Plug-In eingebunden. Suchen Sie das Installationsverzeichnis von Eclipse. Navigieren Sie nun in den Ordner „dropins“ und platzieren Sie dort die JAR-Datei des Plug-Ins („CA_APIM_CustomAssertionPlugin_X.jar“). Wenn Sie Eclipse nun starten, steht das Plug-In zur Verfügung.
Projekt erstellen
Erstellen Sie nun ein neues „CA API Management Custom Assertion“ - Projekt (Menü>Project>New Project).
Im nächsten Schritt folgt die Erstellung der wichtigsten Metadaten, beziehungsweise Eigenschaften, des Projekts. Im Folgenden werden die einzelnen Felder kurz beschrieben:

Project Name
Dieser Wert stellt den Namen des Projekts dar. Er ist nur innerhalb der IDE sichtbar.
Assertion Package
In dieser Zeile wird der Package Namespace der Assertion festgelegt. Hierbei ist darauf zu achten, dass „com.l7tech.custom.“ als Präfix genutzt werden muss!
Assertion Code Name
Dabei handelt es sich um den Namen der Assertion innerhalb des Codes. Die Klassen, die durch das Plug-In erstellt werden, werden nach dieser Zeile benannt.
Assertion Display Name
Dies ist der Name, der in der Oberfläche des API Gateways zu sehen ist.
Assertion Description
Dies ist die Beschreibung, die in der Oberfläche des API Gateways zu sehen ist.
Assertion Category
Hier wird die Kategorie der Assertion angegeben. In unserem Fall handelt es sich um eine Custom Assertion. Für alle weiteren Einträge lesen Sie bitte die offizielle Dokumentation von CA.
Include Custom UI
Es gibt die Möglichkeit, ein eigenes UI für die Assertion zu implementieren. Wenn dies erwünscht ist, setzt man hier einen Haken. Die UI-Implementierung wird in diesem Beitrag allerdings nicht behandelt.

Klicken Sie auf „Finish“ um die Assertion zu erstellen. Nun haben Sie erfolgreich eine Custom Assertion erstellt.
Klassenbeschreibung
Assertion Code Name_Assertion.java
Diese Klasse stellt die Schnittstelle zwischen der Funktionalität Ihrer Assertion und dem Gateway dar. Hier werden Ein- und Ausgabe-Parameter verarbeitet und veröffentlicht. Der Name der Klasse hängt von dem Metaparameter „Assertion Code Name“ ab.

Variablen

OUTPUT_STRING_VARIABLE_NAME
Dieser Wert ist eine Kontextvariable, die von der Assertion gesetzt werden kann. Kontextvariablen dienen als Rückgabewert der Assertion. Nachdem Ihre Assertion bspw. Daten verarbeitet hat, kann sie das Ergebnis in dieser Variable veröffentlichen. Innerhalb des Gateways ist sie dann unter ${OUTPUT_STRING_VARIABLE_NAME} erreichbar. Hier ist es zwingend notwendig, eine Konstante zu verwenden, da die Variable ansonsten als Parameter der Assertion angesehen wird.

inputStringOne, inputStringTwo
Diese Werte stellen die Parameter der Assertion dar. Je nach Anwendungsfall können diese Variablen umbenannt, hinzugefügt oder gelöscht werden. Wichtig ist, dass Getter und Setter für jede Variable implementiert werden, da man sie ansonsten im weiteren Verlauf nicht verwenden kann.

Methoden

public String getName()
Diese Methode teilt dem Gateway den Namen der Assertion mit.

public String[] getVariablesUsed()
In dieser Methode werden die Variablen an das Gateway übermittelt. Die Methode überprüft zunächst, ob die Werte bereits initialisiert sind. Ist dies der Fall, so werden diese zurückgegeben, ansonsten wird ein leeres Array zurückgegeben. Diese Methode ist entsprechend der Parameter zu überarbeiten.

public VariableMetada[] getVariableSet()
Diese Methode teilt dem Gateway die Kontextvariable(n) mit, die von der Assertion gesetzt werden.

Assertion Code Name_ServiceInvocation.java
Diese Klasse ist das Herzstück der Assertion. Hier wird die Applikationslogik implementiert. Die Methode „checkRequest“ ist hierfür vorgesehen. Die Klasse enthält einen „Logger“, mit dem Logeinträge der Assertion erstellt werden können. Die Logeinträge können anschließend im Policy Manager eingesehen werden. Für weitere Informationen ist die offizielle Dokumentation die beste Anlaufstelle.

public CustomAssertionStatus checkRequest(final CustomPolicyContext customPolicyContext)
Diese Methode enthält die Businesslogik. Die Methode gibt den Status der Assertion zurück. Dieser kann einer der folgenden Werte sein:
- AUTH_FAILED
- FAILED
- FALSIFIED
- NONE
- UNAUTHORIZED.
Um die Variablen der Assertion zu referenzieren, verwendet man den „CustomPolicyContext“, der als Parameter in die Assertion gegeben wird. „customPolicyContext.expandVariable(assertion.getInputStringOne())“ liefert den Wert für „inputStringOne“. Es können nur Werte referenziert werden, die Getter und Setter in der Assertion.java besitzen.
Weiterhin ist es möglich, Kontextvariablen aus dem Gateway zu beziehen. „customPolicyContext.expandVariable("${ssgnode.id}")“ liefert bspw. die Node-Id des Gateways. Für weitere Kontextvariablen siehe offizielle Dokumentation.
Build
Um die JAR-Datei der Assertion zu bauen, wird der sogenannte „And-Build“ gestartet, wie im Screenshot zu sehen (Rechtsklick „build.xml“ > „Run As“ > „1 Ant Build“). Anschließend liegt die JAR-Datei im „build“-Ordner des Projekts.

Nun wissen Sie alles, um mit der Entwicklung Ihrer eigenen Custom Assertion zu beginnen.
Installation
Nachdem Sie Ihre Custom Assertion erstellt haben müssen Sie diese noch auf dem Gateway installieren. Hierfür gibt es verschiedene Methoden.

Manuell
Dies ist zwar ein umständlicher Weg eine Custom Assertion zu installieren, erlaubt es allerdings, dass die Custom Assertion vorher nicht von CA signiert wird. Für Entwicklungszwecke ist diese Methode daher von Vorteil.
Hinweis: Man könnte den Vorgang durch ein Script automatisieren.

a. SSH Verbindung zum Gateway aufbauen
b. Menüpunkt 3: Privilegierte Shell
c. cd /home/ssgconfig
d. Datei per SCP an Gateway schicken (WinSCP oder Kommandozeile))
e. cp DATEINAME /opt/SecureSpan/Gateway/runtime/modules/lib/
f. chown layer7:layer7 DATEINAME
g. service ssg restart

Wir kopieren unsere Custom Assertion in das vorgesehene Verzeichnis und ändern die Zugriffsrechte für den User layer7. Anschließend starten wir den Service vom API Gateway neu. Nun steht die Assertion im Policy Manager zur Verfügung.

Server Module File
Diese Methode ist am besten für das Rollout beim Kunden geeignet. Die Server Module File kann bequem über den Policy Manager auf dem Gateway installiert werden. Der einzige Haken hierbei ist es, dass die Assertion von CA signiert werden muss. Dies kann beim CA Support beantragt werden.

SolutionKit
Dies ist die letzte Methode, auf die wir aber an dieser Stelle nicht näher eingehen werden. Auch hier ist für weitere Informationen die offizielle Dokumentation zu empfehlen.
Übrigens: Mit dem APIIDA API Gateway Manager können Sie ihre CA API Gateways bequem und komfortabel überwachen und kontrollieren. Lesen Sie doch mal rein: APIIDA API Gateway Manager

Diese Webseite verwendet Cookies um die Benutzerfreundlichkeit dauerhaft zu verbessern. Wenn Sie diese Webseite besuchen, stimmen Sie dieser Tatsache automatisch zu. Weitere Informationen finden Sie unserer Datenschutzerklärung.

Die Cookie-Einstellungen auf dieser Website sind auf "Cookies zulassen" eingestellt, um das beste Surferlebnis zu ermöglichen. Wenn du diese Website ohne Änderung der Cookie-Einstellungen verwendest oder auf "Akzeptieren" klickst, erklärst du sich damit einverstanden.

Schließen