Kontakt	Adresse
Phone	+49 (821) 25967-0
E-Mail	info@manage.de
Web	www.manage.de
LinkedIn	manage.it GmbH

---

1. Einführung und Erläuterung

Die dragon.XPF (Foundation) Applikation ist eine ORACLE APEX basierende Lösung um sog. „Custom“ Authentifizierung und Autorisierung umzusetzen. Darüber hinaus ist es für die Lizensierung des manage.it Produkt-Portfolios zuständig.

Authentifizierung

Wenn man das Standard Anmeldeverfahren umgehen möchte um eine eigene Anmeldeprozedur zu etablieren, wird dies in einer ORACLE APEX Anwendung bei den „Shared Components“ im Bereich „Security“ im Menüpunkt „Authentication Schemes“ realisiert.

Sobald eine ORACLE APEX Anwendung die Standard-Funktion apex_authentication.login aufruft, wird die Funktion aufgerufen, die hier unter „Settings“ definiert wird.

Hierbei wird der Benutzername (USERNAME) und das Benutzerpasswort (PASSWORD) an die Funktion übergeben. Die dragon.XPF kann hierbei 2 unterschiedliche Verfahren anwenden.

• FORMS Anmeldung
  Der Anwender wird über eine Lokale Tabelle (XPF_USERS) Authentifiziert d.h. USERNAME/PASSWORD werden über diese Tabelle abgeglichen.
• LDAP-Anmeldung
  Der Anwender wird über seinen Domänen Benutzer Authentifiziert d.h. es wird versucht über Microsoft Active Directory eine Anmeldung durchzuführen. Die Einstellungen hierfür finden im Bereich des dragon.XPF LDAP (Connection) Setup statt.

Alternativ kann eingestellt werden, dass zuerst eine FORMS Anmeldung versucht wird. Scheitert dies, wird versucht über LDAP eine Anmeldung durchzuführen (Forms & LDAP).

Hinweis: Bedenken Sie bitte, dass für eine LDAP basierende Anmeldung die ACL für die Active Directory (Server-IP) Verbindung zugelassen werden muss.

Autorisierung

Wenn man das Standard-Berechtigungsverfahren ersetzen und eine eigene Autorisierung etablieren möchte, wird dies in einer Oracle-APEX-Anwendung unter den Shared Components im Bereich Security im Menüpunkt Authorization Schemes konfiguriert.

Beim Aufrufen der Funktion wird erwartet, dass entweder TRUE oder FALSE zurück geliefert wird d.h. ist der Benutzer berechtigt, die Oberflächen (UI-Elemente) zu sehen oder nicht.

Hinweis: Aktuell wird das Feld :APP_COMPONENT_ID nicht genutzt.

Beim „Evaluation Point“ ist die Einstellung „Always (No Caching)“ zu aktivieren d.h. das kontinuierlich die Autorisierungsprüfung durchgeführt wird. Dies ist zwar ein wenig Performance intensiver, aber man kann schon zur Design-/Laufzeit von Berechtigungen überprüfen, ob diese funktionieren ohne sich neu Anmelden zu müssen.

Authorization aktivieren

Um nun eine Page oder Oberflächen-Element an das dragon.XPF Authorization Framework anzuschließen, muss unter den Eigenschaften des Elements im Bereich „Security“ der dragon.Foundation Authorization Controller ausgewählt werden.

Sobald ein UI-Element nun an den dragon.Foundation Authorization Controller „angeschlossen“ wurde, muss im Bereich „privileges“ das sog. Privileges Set neu erzeugt werden, um das neue Element (Berechtigungsobjekt) zu erstellen um es dann z.B. einem Benutzer oder einer Rolle zuzuweisen.

---

2. Installation (Entwicklungsumgebung)

Über das manage.it GitLab zuerst die Anwendung herunterladen:

dragon.XPF GitLab Repository

Nach dem entpacken des ZIP Archives nun das Visual Studio Code starten und den Ordner öffnen. Im Verzeichnis „src“ befinden sich nun der Ordner mit der aktuellen Version des dragon.XPF und das „install“ Verzeichnis.

Stellen Sie sicher, dass die folgenden Dateien für das zu installierende System richtig konfiguriert sind:

• config_package_xape.sql
• config_package.sql
• config_xape.ps1
• config.ps1

Wechseln Sie nun in das Terminal Fenster des Visual Studio Code.

Wechseln Sie in den Ordner SRC und dann in den Ordner INSTALL. Führen Sie die PowerShell Datei install.ps1 aus.

Hinweis: Bei der Installation wird zuerst eine Löschung durchgeführt d.h. sollte die Anwendung bereits installiert worden sein, werden die Objekte gelöscht und anschließen initial neu angelegt.

---

3. Übersicht der installierten Objekte

Tabellen

• MIT_LOGS
• XPF_CONNECTORS
• XPF_CUSTOMERS
• XPF_GROUP_ROLES
• XPF_GROUPS
• XPF_LDAP_IMPORT
• XPF_LICENSES
• XPF_MAIL_SETUP
• XPF_PASSKEYS_REQUESTS
• XPF_PASSKEYS_USERS
• XPF_PRIVILEGES
• XPF_PRIVILEGES_SET
• XPF_PRODUCTS
• XPF_ROLES
• XPF_USER_GROUPS
• XPF_USER_ROLES
• XPF_USERS

Views

• VW_XPF_APEX_AUTHORIZATIONS
• VW_XPF_GROUP_ROLES
• VW_XPF_PRIVILEGES
• VW_XPF_USER_GROUPS
• VW_XPF_USER_ROLES

Packages

• MIT_CLK (wird nicht ausgeliefert im Standardumfang)
• MIT_LOG (Standard Logging Package)
• XPF_AUTH (Service-Package „wrapped“)

Trigger

• XPF_CONNECTORS_CIUD
• XPF_CUSTOMERS_CIUD
• XPF_GROUP_ROLES_CIUD
• XPF_GROUPS_CIUD
• XPF_LDAP_IMPORT_CIUD
• XPF_LICENSES_CIUD (wird nicht ausgeliefert im Standardumfang)
• XPF_MAIL_SETUP_CIUD
• XPF_PASSKEYS_REQUESTS_CIUD
• XPF_PASSKEYS_USERS_CIUD
• XPF_PRIVILEGES_CIUD
• XPF_PRIVILEGES_SET_CIUD
• XPF_PRODUCTS_CIUD
• XPF_ROLES_CIUD
• XPF_USER_GROUPS_CIUD
• XPF_USER_ROLES_CIUD
• XPF_USERS_CIUD

Application Express (APEX) Anwendung

---

4. Konfiguration (connection setup)

Nachdem die dragon.XPF Applikation erfolgreich installiert wurde, muss das APEX Frontend (App-Id 500) angepasst werden. Unter den „Application Properties“ auf dem Tab „Security“ das Datenbank Schema entsprechend anpassen.

Bei der Installation wird ein dragon.XPF Administrator angelegt (User-Id=0). Der Benutzername ist „admin“ (genauso wie das Passwort). Es wird dringend empfohlen das Initial-Passwort nach der ersten Anmeldung zu ändern. („send passwort mail“)

Melden Sie sich nun am dragon.XPF an und wechseln Sie in den Bereich „connection setup“. Bei der Installation wird Standardmäßig ein Eintrag „XPF Forms“ erzeugt. Die Autorisierungsart (Con Authent) ist nach der Installation die „FORMS“ Anmeldung, damit sich der dragon.XPF Administrator anmelden kann.

Prüfen Sie die dort aufgeführten Verbindungsinformationen. Wählen Sie nun eine Authentifizierungsart aus.

Standardmäßig wird kein Secure LDAP Protokoll eingestellt. Dies setzt diverse administrative Tätigkeiten voraus z.B. Anforderungen für ein LDAPS-Zertifikat.

Das dragon.XPF kann sowohl aus dem Oracle APEX als auch über das angeschlossene Active Directory (LDAP) einen User Import ausführen.

LDAP Search: Über die die eingestellten Parameter search base, scope und filter kann ein bestimmter Active Directory Bereich ausgelesen werden. Im Tab „Result as string“ kann man sich die LDAP Suche als reine Text-Ausgabe anzeigen lassen.

APEX Users: Es werden die im aktuellen Workspace angelegten Oracle APEX Benutzer ausgelesen.

Im „Result as xpf import“ Tab sehen Sie nun die gefundenen Benutzer. Im Feld „xpf import“ kann man sehen, ob der Benutzer bereits in den users vorhanden ist (Imported) oder nicht. Steht das Feld auf „No“ kann man den Schalter auf „Yes“ stellen. Stellen Sie nun alle Schalter auf „Yes“ deren Benutzer importiert werden sollen und speichern Sie die Einstellung.

Wird der Schalter „use SAM Account“ auf „Yes“ gestellt, wird nicht der userPrincipalName bei der Anlage verwendet, sondern der sAMAccoutName.

Es werden diverse Prüfungen durchgeführt ob z.B. die E-Mail Adresse bereits vorhanden ist oder ob der Benutzer/Domänen Name bereits vorkommt zu einem Konnektor. Duplikate sind hier nicht erlaubt wegen der eindeutigen Zuweisung.

---

5. Bereich der Produkt Lizensierung

Customers

Um die Kundenlizenzen zu verwalten, ist es notwendig, einen Eintrag in der Kundentabelle zu erstellen. Besonders wichtig ist die registrierte Kunden E-Mailadresse, da diese E-Mailadresse Teil des generierten Lizenzschlüssels ist.

Products

Legen Sie hier die registrierten Applikationen fest. Geben Sie den Produktnamen, die Anwendungskennung, die Beschreibung (optional) und die Produktversion (optional) an, die Sie verwalten und lizenzieren möchten. Für das manage.it Produkt-Portfolio sind einige spezielle Einstellungen vorzunehmen.

• Show Pw Reset Button: Wenn ja, wird die Schaltfläche „Passwort vergessen“ (bzw. „forgot my password“) auf dem Anmeldebildschirm angezeigt, um den Reset Password Key Prozess zu verwenden. Falls in der Kundenumgebung LDAP aktiv ist, wird empfohlen diese Schaltfläche auszublenden.
• MFA Active: Das dragon.XPF kann mit einer „2-Faktor-Authentifizierung“ Implementierung betrieben werden. Wenn ja, müssen Sie die richtige manage.it MFA Server URL dort eintragen. Nähere Informationen finden Sie im Bereich „Multi-Factor-Authentication (MFA)“.
• PASSKEY Active: Das dragon.XPF kann auch mit PASSKEY betrieben werden. In der PASSKEY URL muss das Python Backend (z.B. http://127.0.0.1:9443/webauthn) definiert werden. Im PASSKEY Origin muss der zu betreibende Namensraum eingetragen werden (z.B. https://my.system.de). Um sich mit PASSKEY anzumelden, muss der authentifizierte Benutzer den PASSKEY Registrierung-Prozess durchlaufen (oben rechts unter dem User-Menu).

Licenses

Zunächst können Sie die registrierte Kunden-E-Mail auswählen. Wählen Sie eine Anwendung (App. Id), legen Sie das Ablaufdatum und wie viele Benutzer (max. Oracle-Benutzerlizenzen) die Anwendung nutzen können.

Sie müssen den genauen Host (Name) und Datenbank (Name) des Zielrechners kennen. Wenn Sie Ihre Dateneingaben speichern, werden ein Lizenzschlüssel (Code) und ein sog. Key Byte (Code) generiert. Sie können diese Werte manuell in der Kundendatenbank direkt eingeben oder die beiden Codes entsprechend in der Oberfläche auf der Registrierungsmaske eingeben.

Jedes manage.it Produkt hat einen definierten Button auf dem Anmeldebildschirm, der für die Registrierung des Produktes notwendig ist (Weiterleitung zur dragon.XPF Lizenzierungsmakse). Der Button wird nur angezeigt, wenn die Prozedur XPF_AUTH.show_license_key_registration den Wert TRUE zurückgibt, weil kein gültiger Lizenzschlüssel vorhanden ist (null) oder das Gültigkeitsdatum überschritten wurde.

Jedes manage.it-Softwareprodukt verfügt über diese Seite zur Registrierung der Software. Dieses Fenster erscheint, wenn kein gültiger Lizenzschlüssel hinterlegt wurde oder wenn beispielsweise das Ablaufdatum überschritten ist. Der Benutzer bzw. Besitzer der manage.it-Software gibt hier seine registrierte E-Mail-Adresse, das entsprechende Ablaufdatum und die Anzahl der maximal lizenzierten Benutzer ein.

Anschließend gibt der Benutzer den generierten Produktlizenzschlüssel (License Key) sowie das zugehörige Schlüsselbyte (Key Byte) ein und klickt auf die Schaltfläche „save product license“. Wenn alle Eingaben korrekt sind, wird eine Erfolgsmeldung angezeigt und der Benutzer kann sich an der Applikation anmelden.

Hinweis: Vergessen Sie nicht, die dragon.XPF Benutzergruppe/Rolle/Privilegien für jeden Benutzer und jede Anwendung festzulegen.

---

6. Vorbereitung Berechtigungsobjekte (authorization privileges)

Wechseln Sie nun in den Bereich „privileges“. Um Rollen und Gruppen für eine Anwendung zu erzeugen, müssen zuerst die sog. Berechtigungsobjekte erzeugt werden. Hierzu wird über den dragon.XPF View VW_XPF_APEX_AUTHORIZATIONS nun ein Set aller APEX Objekte erzeugt, die den ‚dragon.Foundation Authorization‘ Controller im Security definiert haben.

Hinweis: Beachten Sie bitte, dass die zu berechtigende Applikation zuerst im Bereich „products“ hinzugefügt werden muss, bevor hierfür Berechtigungsobjekte erzeugt werden können.

Klicken Sie nun auf die Schaltfläche „update privileges set“ (dies kann einige Sekunden dauern). Nun werden zum aktuellen Workspace applikationsübergreifend alle Komponenten erzeugt.

Der View erzeugt beim COMPONENT_TYPE APEX_APPLICATION_PAGES immer den Seitennamen als COMPONENT_NAME. In einer nachgelagerten Verarbeitung wird dann aber der Seitentitel überschrieben falls die beiden Werte unterschiedlich sind, da beim Authority Check für APEX_APPLICATION_PAGES immer der Seitentitel übergeben wird.

Später, nachdem Sie Rollen und Gruppen erzeugt haben, können Sie auf eine Komponente (Privilege) klicken, um zu sehen, in welchen Rollen und Gruppen diese verwendet wird.

---

7. Berechtigungsrollen (authorization roles)

Wechseln Sie nun in den Bereich „roles“ und legen Sie über die Schaltfläche „Add Role“ eine Berechtigungsrolle an. Vergeben Sie einen Rollennamen und eine Beschreibung und weisen Sie der Rolle eine Applikation zu. Die Zuweisung der Applikation stellt sicher, dass nur Berechtigungsobjekte mit dieser Applikations-ID angezeigt werden.

Klicken Sie auf die „role id“, um dieser Rolle Berechtigungsobjekte zuzuweisen. Auf dem Tab „privilege assignment“ erhalten Sie eine Übersicht über die zugewiesenen Berechtigungen (Assigned Privileges) sowie über die verfügbaren Berechtigungen (available privileges).

Beim Zuweisen von Berechtigungen macht es Sinn ggf. den Filter so einzustellen, dass nur relevante Objekte eingeblendet werden (z.B. Page Id setzen).

Wählen Sie nun die Check-Boxen der entsprechenden Berechtigungsobjekte aus und klicken Sie auf die Schaltfläche „assign selected privileges to role“ die sich am oberen und unteren Ende befindet.

Sie sehen nun im Bereich „assigned privileges“ die zugewiesenen Berechtigungsobjekte. Zum entfernen von Berechtigungsobjekten, wählen Sie diese über die Check-Boxen aus und klicken dann auf die Schaltfläche „remove selected privileges from role“. Die Einträge verschwinden und sind dann wieder im rechten Bereich „available privileges“ zu sehen.

Wenn Sie auf den Tab „role members“ klicken, sehen Sie eine Übersicht über alle Benutzer die dieser Rolle zugewiesen sind. Dort können Sie direkt die Rolle den Benutzer zuweisen, sofern nicht eine Berechtigungsgruppe (groups) verwendet werden soll.

In dem Tab „role used in group“ sehen Sie eine Übersicht, in welchen Berechtigungsgruppen (authorization groups) die aktuelle Rolle verwendet wird.

---

8. Berechtigungsgruppen (authorization groups)

Sollte es notwendig sein (z.B. bei großen Anwendungsszenarien) Gruppen von Rollen zu erzeugen, klicken Sie auf den „groups“ und legen Sie eine Berechtigungsgruppe an.

Klicken Sie auf „group id“, um in die Gruppendetails zu gelangen und die entsprechenden Rollen und Benutzer zuzuweisen.

Sie können – ähnlich wie bei den Rollen und Berechtigungen – nun eine Auswahl der Rollen sehen, die zugewiesen sind bzw. die Rollen, die Sie zuweisen können. Wählen Sie die Rollen aus die Sie der Gruppe zuweisen möchten und klicken Sie auf die Schaltfläche „assign selected roles to group“. Die ausgewählten Rollen werden dann der Gruppe zugewiesen.

Über den Tab „group members“ erhalten Sie Übersicht, welche Benutzer dieser Gruppe zugewiesen sind. Über den Tab „group privileges“ erhalten Sie eine Übersicht, welche Berechtigungsobjekte in dieser Gruppe enthalten sind.

---

9. Benutzer (users)

Nachdem die Berechtigungsobjekte erzeugt, Rollen und Gruppen entsprechend ausgeprägt wurden, können diese nun Benutzern zugewiesen werden. Wechseln Sie in den Bereich „users“.

Über die Schaltfläche „Add User“ können Forms Benutzer angelegt werden (keine LDAP-Anmeldung möglich, wenn diese nicht in der Ausprägung in der Domäne vorkommen).

Füllen Sie die Felder username, first name last name und email aus und wählen Sie den gewünschten Konnektor aus und klicken Sie die Schaltfläche „Save“. Dem Benutzer wird nun eine Willkommen-E-Mail mit Instruktionen zum Erstellen des Passwortes generiert und zugeschickt.

Nun haben Sie die Möglichkeit dem Benutzer entweder Gruppen (user groups), Rollen (user roles) oder sogar ein explizites Berechtigungsobjekt (user privileges) zuzuweisen. Das zuweisen und entfernen folgt der gleichen Logik wie bei den Rollen und Gruppen bereits erläutert.

Über den Tab „effective privileges“ können Sie die Summe aller Berechtigungsobjekte sehen und aus welchen „Quellen“ diese stammen (Gruppe, Rolle, Einzelberechtigung).

---

10. Multi-Factor-Authentication (MFA)

Wurde im manage.it Produkt Portfolio für eine Applikation das MFA aktiviert, können Sie zu jedem Benutzer explizit einstellen, ob dieser die Token Id eingeben muss bei der Anmeldung oder nicht, indem Sie den Schalter MFA Auth. auf „Yes“/„No“ einstellen und speichern.

Voraussetzungen im dragon.XPF:

• Die entsprechende Applikation ist im Bereich „product licensing“ entsprechen für die MFA konfiguriert.
• Der Benutzer benötigt eine gültige E-Mail Adresse.
• Das geschützte Feld MFA_AUTO_PW enthält eine generierte GUID.

Im Folgenden werden die einzelnen MFA Prozess-Schritte erläutert:

1. Benutzer an der MFA registrieren: Selektieren Sie einen oder mehrere Benutzer und klicken Sie auf die Schaltfläche „register user to MFA“. Die selektierten Benutzer werden der manage.it MFA bekannt gemacht. Hierbei sendet das dragon.XPF eine sog. GUID and die MFA und erhält bei erfolgreicher Registrierung eine UUID zurück die gespeichert wird und für künftige Prozesse verwendet wird.
2. Nachdem der/die Benutzer an der MFA registriert wurden, müssen als nächstes MFA QR-Code E-Mails generiert werden, damit diese einen Eintrag im Google Authenticator hinzufügen. Selektieren Sie einen oder mehrere Benutzer und klicken Sie auf die Schaltfläche „generate MFA QR E-Mail“. Die Benutzer erhalten eine E-Mail mit QR-Code den sie im Google Authenticator einscannen können (manageit-mfa). Hinweis: Das generieren eines QR-Codes macht den vorherigen/alten Eintrag im Google Authenticator ungültig!
3. Benutzer an der MFA de-registrieren: Falls Sie Benutzer von der MFA abmelden/austragen möchten, selektieren Sie einen oder mehrere Benutzer und klicken Sie auf die Schaltfläche „deregister user from MFA“. Bedenken Sie, dass ein abmelden zu Folge hat, dass der Eintrag im Google Authenticator nicht mehr gültig ist.
4. Ist der Benutzer nun registriert und hat den QR-Code eingescannt, kann zukünftig bei der nächsten Anmeldung (login) der 6-stellige Authenticator Code eingegeben werden. Das Feld ist „Enter“ sensitive und lässt max. nur 6 Zeichen zu.

5. Der Benutzer muss nun zuerst seinen Benutzernamen und sein Passwort eingeben. Anschließend gibt er der 6-stelligen Code ein. Beim anschließenden Prozess wird die Funktion validieren ausgeführt. Wurde alles korrekt ausgeführt und es kamen keine Fehlermeldungen, wurde der Benutzer an der Applikation angemeldet.

---

11. Berechtigen der DML Buttons eines Interactive Grids

Da es keine APPLICATION Variable gibt, die sog. EDIT_OPERATIONS zu einem Interactive Grid liefert, ist wie folgt vorzugehen.

Aktivieren Sie unter den Interactive Grid Attributen welche Operationen erlaubt sein sollen (z.B. nur UPDATE). Hierbei ist es nicht notwendig unter den Edit Authorization den dragon.Foundation Authorization auszuwählen.

Nun muss im Interactive Grid Attribut READ ONLY ein „Function Body“ aktiviert werden der den dragon.XPF Custom Authorization Controller aufruft.

-- WENN DIE AUTHORISIERUNGSPRÜFUNG TRUE ZURÜCK LIEFERT,
-- DANN WIRD READ ONLY AUF FALSE GESETZT
IF XPF_AUTH.AUTHORIZATION_CONTROLLER(
      P_COMPONENT_TYPE => XPF_AUTH.CON_APEX_APPL_IG_EDITABLE,
      P_COMPONENT_NAME => 'ig_users', -- CHANGE TO GRID NAME!
      P_PAGE_ID        => :APP_PAGE_ID,
      P_APPLICATION_ID => :APP_ID,
      P_USERNAME       => :APP_USER) = TRUE THEN
   RETURN FALSE; -- BENUTZER IST BERECHTIGT
ELSE
   RETURN TRUE; -- BENUTZER IST NICHT BERECHTIGT
END IF;