Wiki-Quellcode von Plugin Setup

Zeige letzte Bearbeiter
1 {{content depth="4"/}}
2
3 == Initiale Installation ==
4
5 Das **BürgerService Plugin** muss im System Bereich von {{formcycle/}} installiert werden (Menüpunkt: System > [[Systemplugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins||target="_blank"]]).
6 Es bietet aktuell die Anbindung an folgende Servicekonten:
7
8 * **BundID**
9 * **BayernID**
10 * **ELSTER** //Mein Unternehmenskonto//
11
12 == Migration bestehender Service-Konten-Anbindungen ==
13
14 * Bestehende Anbindungen zu Service-Konten von **BundID**, **BayernID** und **ELSTER** werden bei der Installation des Plugins automatisch auf das neue Plugin umgestellt.
15 * Die veralteten Plugin-Bundles (jar-Dateien) bleiben dabei auf dem System erhalten, werden aber deaktiviert.
16 * Alle zuvor konfigurierten Anbindungen werden als Externe Benutzer im jeweiligen Bereich (System oder Mandant) definiert.
17 * Designer-Vorlagen, die mit den veralteten Plugins in das System gekommen sind, werden entfernt.
18
19 === Migrations-Beispiel für BayernID Anbindung: ===
20
21 Ausgangspunkt ist ein FORMCYCLE System mit mehreren Mandanten. In zwei Mandanten ist jeweils das// AKDB: Bürgerkonto-Service-Plugin //(Anbindung an **BayernID**) installiert.
22 Einer der **BayernID **Mandanten hat die Einbindung des Bürgerkonto Logins als Externer Benutzer konfiguriert.
23
24 Nachdem das** BürgerService Plugin** im [[System Bereich>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins||target="_blank"]] installiert wurde ergibt sich folgendes Bild:
25
26 * Die veralteten //AKDB: Bürgerkonto-Service-Plugins// in den jeweiligen Mandanten sind deaktiviert, aber noch vorhanden.
27 * In beiden Mandanten mit **BayernID **Anbindung befindet sich jetzt ein Externer Benutzer, welcher zukünftig die Authentifizierung mit dem **BayernID**-Portal realisiert.
28 In einem Mandanten wurde dazu im Zuge der Migration der Externe Benutzer neu angelegt. In dem Mandanten, wo bereits ein Externer Benutzer bestand, wurde dieser um notwendige Daten (Zertifikate zur Kommunikation, Anbindungsdaten für den Postkorb-Schnittstelle) erweitert, sodass er auch weiterhin in den bereits bestehenden Formularanbindungen genutzt werden kann.
29 * Der Menüpunkt //AKDB Setup// ist in den Mandanten nicht mehr vorhanden. Die Einstellungen, welche den Postkorb betreffen (z.B.: Zertifikat für Postkorb-Kommunikation) sind jetzt direkt am neu erstellten bzw. migrierten Externen Benutzer zu finden.
30 * Alte Designer-Vorlagen für die Anzeige der Bürgerkonto-Daten wurden durch neue Vorlagen ersetzt.
31 * Die Formulare welche bisher die **BayernID** über den Login-Button eingebunden hatten müssen nicht angepasst werden. Bei Nutzung des Login-Buttons, sowie der Postkorb-Aktion im Workflow erfolgt eine automatische Weiterleitung an die durch das **BürgerService Plugin** bereitgestellte Funktionalität.
32
33 {{info}}
34 Hinweis: Es werden nur fertig konfigurierte **BayernID **Anbindungen migriert. Ist nur das Plugin im Mandaten vorhanden ist, sind aber keine Einstellungen zur Anbindung (Keystore, EntityID etc.) konfiguriert, kann keine Migration in einen [[Externen Benutzer>>doc:Formcycle.UserInterface.UserSettings.ExternalUsers.WebHome||target="_blank"]] erfolgen.
35 {{/info}}
36
37
38 === Migration für BundID Anbindungen ===
39
40 Bei bestehenden **BundID** Anbindungen werden die vorhandenen Externen Benutzer mit der neuen Konfigurationseinstellungen erweitert. Vorhandene Formulare mit BundID Anbindung, können ähnlich, wie bei der BayernId ohne Anpassung genutzt werden. 
41
42 === Migration für ELSTER Anbinungen ===
43
44 Bei bereits im System existenten **ELSTER** Anbindungen werden die vorhandenen Externen Benutzer mit neuen Konfigurationseinstellungen erweitert. Formulare mit einer Zugriffssteuerung über **ELSTER** können ohne weitere Anpassung genutzt werden. Anbindungen an den** ELSTER-Transfer-Client**, welche über die entsprechende //ELSTER Postkorbnachricht// Workflow-Aktion in den Formularen eingebunden sind, werden automatisch auf die **BürgerService Plugin** Funktionalität weitergeleitet. Dadurch ergibt sich auch hier keine notwendige Anpassung der vorhandenen Formulare.
45
46 == Vorüberlegungen zur Anbindung neuer Servicekonten ==
47
48 Neue Anbindungen an Servicekonten müssen im {{formcycle/}} System als [[Externe Benutzer>>doc:Formcycle.SystemSettings.UserInterface.ExternalUsers.WebHome]] (auch als Authentikatoren bezeichnet) angelegt werden. Dabei ist es möglich diese im System- als auch im Bereich des Mandanten anzulegen.
49 Folgende Überlegungen sollten für eine Entscheidung des Bereichs, in welchem die Externen Benutzer angelegt werden, herangezogen werden.
50
51 **Ist ein Multi-Mandanten {{formcycle/}} System mit unterschiedlichen Host-Adressen für die Ansteuerung der Formulare der einzelnen Mandanten vorhanden? (Meist realisiert über Anbindung mehrerer Frontend-Server)**
52
53 In diesem Fall sollte jeweils im Mandanten ein Externer Benutzer angelegt werden, welcher die Anbindung an des Servicekonto realisiert.
54 \\Der Grund für dieses empfohlene Vorgehen ist, dass die aktuellen Anbindungen an die **BundID**, die **BayernID, **sowie an das **ELSTER**-Portal alle auf Grundlage des [[SAML 2.0>>https://en.wikipedia.org/wiki/SAML_2.0||rel="noopener noreferrer" target="_blank"]] - Protokolls arbeiten. Eine Festlegung bei der Kommunikation über das SAML 2.0 Protokoll ist es, dass im Vorfeld zwischen dem jeweiligen Identity Provider (Servicekonto-Portal) und dem Service Provider (FORMCYCLE) Metadaten ausgetauscht werden müssen. In diesen Metadaten sind die Rücksprungziele in das jeweils andere System (per URL) fest definiert.
55 Durch das Anlegen eines Externen Benutzers im Bereich des jeweiligen Mandanten kann hier eine saubere Trennung und damit auch Nutzung in den Formularen stattfinden.
56 Legt man bei dieser Systemkonstellation verschiedene Externe Benutzer im System - Bereich an, so muss der Formularentwickler innerhalb des Formular die für seinen Mandanten korrekte Anbindung auswählen, was eine potenzielle Fehlerquelle sein kann.
57
58 **Ist ein Multi-Mandanten- oder ein Single-Mandat- {{formcycle/}} System mit einer Host-Adresse für die Ansteuerung der Formulare vorhanden?**
59
60 Hier sollten alle Externen Benutzer für die Servicekonten-Ansteuerung im System-Bereich angelegt werden. Der Vorteil ist an dieser Stelle, dass alle Anbindungen zentral an einer Stelle vorhanden sind und alle Formular-Benutzer in den verschiedenen Mandanten Zugriff auf diese erhalten.
61
62 == Allgemeine Informationen zur Anbindung eines Servicekontos ==
63
64 {{figure image="extUser_selection.png"}}
65 Auswahl eines Servicekontos
66 {{/figure}}
67
68 In diesem Abschnitt werden die Schritte, welche für die Anbindung aller Servicekonten gleichermaßen gelten, erläutert.
69
70 Bevor man ein Servicekonto anbindet sollten folgende Voraussetzungen erfüllt sein:
71
72 * Die im Unternehmen verantwortlichen technischen und organisatorischen Ansprechpartner müssen bekannt sein (Namen, E-Mail-Adressen). Diese Informationen werden innerhalb des Registrierungs-Prozesses für die einzelnen Servicekonten an unterschiedlichen Stellen benötigt.
73 * URLs für die Anbindung des FORMCYCLE-Systems müssen eingerichtet und **von außen erreichbar** sein. Dabei ist zu beachten, dass bei Verwendung eines Frontend-Servers die URL zu diesem verwendet wird.
74
75 Die Anbindung eines Servicekontos lässt sich in folgende Schritte gliedern:
76
77 1. Anlegen einen neuen Externen Benutzer (Authentikator) unter dem Menüpunkt System > [[Systemplugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins||target="_blank"]] oder Mandant > [[Plugins>>doc:Formcycle.UserInterface.Client.Plugins||target="_blank"]].
78 1. Spezifische Authentikator Konfiguration über die zur Verfügung gestellte Oberfläche ausführen. Die Konfigurationsoberfläche unterscheidet sich je nach ausgewählten Servicekonto. Auf die Unterschiede bei der Anbindung des jeweiligen Servicekonto-Typs wird in den nachfolgenden Abschnitten näher eingegangen.
79 1. Download und Weiterleitung der festgelegten Konfigurationsdaten (Metadaten), sowie der Vertragsdaten an den jeweiligen Identity Provider (**BundID**, **BayernID**) bzw.
80 selbst durchzuführende Konfiguration auf Seiten des Identity Providers über ein Self-Service Portal (ELSTER)
81 1. Freigabe des Authentikators in {{formcycle/}}, nach erfolgter Rückmeldung über die erfolgte Registrierung der Metadaten durch den jeweiligen Identity Provider bzw. Freigabe durch Prüfungsinstanz (bei ELSTER Self Service Portal Registrierung) und damit Beginn der Einbindung des Servicekontos in Formulare
82
83 == Details für die Anbindung der BundID ==
84
85 Um das Servicekonto der **BundID** anzubinden ist ein neuer Externer Benutzer anzulegen und als Authentifizierungstyp **BundID** auszuwählen.
86
87 === Schritt 1: Konfiguration anlegen ===
88
89 {{figure image="bundID_config1.png"}}
90 Schritt 1: Notwendige Daten für Erzeugung der Service Metadaten festlegen
91 {{/figure}}
92
93 * Im 1. Schritt der Konfiguration erscheint eine Eingabeoberfläche, wo folgende Festlegungen getroffen werden müssen:
94 ** Festlegung, ob Test- oder Live-Umgebung der **BundID** anzubinden ist.
95 ** Erhebung von Zertifikatsinformationen, welche anschließend zur Generierung eines privaten und öffentlichen Schlüssels herangezogen werden. Dieses Schlüsselpaar dient zur Ver- und Entschlüsselung der Kommunikation, zwischen {{formcycle/}} und der **BundID**.
96 ** Angaben zum organisatorischen und technischen Ansprechpartner. Diese Informationen werden im Zuge des Registrierungsprozesses an das **BundID**-Portal innerhalb der generierten SAML-Metadaten weitergegeben.
97 * Speichern der Eingaben. Danach gelangt man zum 2. Schritt der Anbindung.
98
99 === Schritt 2: Metadaten erzeugen und registrieren ===
100
101 {{figure image="bundID_config2.png"}}
102 Schritt 2 und 3: Download der erzeugten Metadaten für eine jeweilige Host-Adresse; Aktivierung der BundID Authentifizierung für Formulare
103 {{/figure}}
104
105 * In diesem Schritt werden die SAML-Metadaten für die Registrierung auf Seiten der **BundID **erzeugt. Dafür steht in der Oberfläche ein Button mit Auswahlfeld zur Verfügung. Das Auswahlfeld enthält alle im {{formcycle/}} System gefundenen Host-Adressen, über die das System erreichbar ist. Auf der Grundlage der jeweiligen Host-Adresse werden dann die Metadaten erzeugt und als Download zurück geliefert. Die jeweilige Host-Adresse bildet dabei einen Teil der Rücksprung-URL, welche später vom Identity Provider (BundID Portal) zur Übermittlung der Authentifizierungsdaten genutzt wird.(((
106 {{info}}
107 Hinweis: Soll der BundID-Login über unterschiedliche Host-Adressen erreichbar sein,
108 so muss für jeden Host die Metadaten-Datei erzeugt und an das BundID-Portal zur Registrierung übermittelt werden.
109 {{/info}}
110 )))
111 * **SAML-Metadaten** sind zusammen mit weiteren Vertragsdaten an das **BundID** Portal (Mail: **bundID@bmi.bund.de**) zu senden, mit der Bitte, um Aufnahme in den Portalverbund. Die genauen Handlungsanweisungen können Sie dem folgenden [[PDF-Dokument>>https://customer.formcycle.eu/index.php/s/B2fsZ9mSwdwGwAX/download?path=%2F&files=BundID_Checkliste.pdf||rel="noopener noreferrer" target="_blank"]] entnehmen.
112 * Damit ist der 1. Teil der Registrierung abgeschlossen und eine Antwort vom **BundID** Portal muss abgewartet werden.
113
114 === Schritt 3: BundID-Login Aktivierung ===
115
116 {{figure image="bundID_config3.png"}}
117 Globale Konfiguration des Anfrageverhalten sowie der Postkorbanbindung
118 {{/figure}}
119
120 * Dieser Schritt sollte erst durchgeführt werden, wenn Sie vom **BundID** Portal Rückmeldung erhalten haben, dass ihre übermittelten Metadaten im Portal registriert und freigegeben sind. Erst mit dem Button //BundId-Login aktivieren// wird der Authentikator im System aktiviert. Er ist damit in den Formularen verfügbar und kann eingebunden werden.(((
121 {{info}}
122 Hinweis: Wenn Sie den Login **vor** einer positiven Rückmeldung des BundID-Portals aktivieren,
123 so kann das die **BundID** zwar bereits in den Formularen eingebunden werden,
124 wird aber beim Aufruf in einem Fehler resultieren,
125 dass der anfragende Service dem Portal nicht bekannt ist.
126 {{/info}}
127 )))
128 * (((
129 Nach Aktivierung des Logins erweitert sich die Konfigurationsoberfläche des Authentikators.* Unter dem Punkt //Erweiterte Einstellungen// > //Konfiguration Identity Provider Anfrageverhalten// kann das Anfrageverhalten für **alle** Formulare, welche diesen Authentikator später über den Formularzugriff angebunden haben, beeinflusst werden. Dabei sind folgende Einstellungen möglich:(((
130 ; Vertrauensniveau
131 : Angaben in dieser Eigenschaft dienen zum Einschränken der Authentisierungsverfahren auf zugelassene Vertrauensniveaus.
132 Einschränkungen dieser Art werden an referenzierende Identity Provider weitergereicht, wenn dies durch den aufrufenden Identity Provider unterstützt wird.
133 ; Login Methoden einschränken
134 : Angaben in dieser Eigenschaft dienen zum Einschränken der Authentisierungsverfahren. Ist kein Wert gesetzt, erfolgt keine Einschränkung und dem Nutzer werden alle, vom Identity-Provider zur Verfügung gestellten, Anmeldeverfahren zur Auswahl angezeigt.
135 ; Pflichtelemente
136 : Über diese Eigenschaft können Attribute als verpflichtende Nutzereigenschaften angefordert werden.
137 Alle Authentisierungsverfahren, welche die geforderten Attribute nicht erfüllen, werden dadurch ausgeblendet.
138 Sofern der Formular-Workflow beispielsweise die Kommunikation mit dem Postkorb zwingend erfordert,
139 kann hier der Wert "Postkorb" angegeben werden, wodurch unter anderem das Ausblenden der temporären Anmeldung erreicht wird.
140 ; Angeforderte Eigenschaften einschränken
141 : Angaben in dieser Eigenschaft dienen zum Einschränken der zurück gelieferten Eigenschaften aus einer erfolgreichen Nutzer-Anmeldung.
142 In erster Linie ist diese Eigenschaft dazu gedacht, dem Grundsatz der Datensparsamkeit aus den Vorgaben der DSGVO (Datenschutz-Grundverordnung) gerecht zu werden.
143 Sind keine Werte gesetzt, erfolgt keine Einschränkung und es werden alle vom Identity-Provider zur Verfügung
144 gestellten Nutzer-Eigenschaften zurück geliefert.
145 )))
146 * Unter dem Punkt //Erweiterte Einstellungen// > //Konfigurtion BundID Postkorbanbindung// können Sie die Daten für einen Proxy-Server hinterlegen, wenn dieser für die Kommunikation zum BundID Postkorb notwendig sein sollte.
147 * Über den Button //Postkorb Verbindung prüfen// kann der Zugriff auf den Postkorb-Webservice getestet werden.(((
148 {{warning}}
149 Folgende URL muss **vom FORMCYCLE Master-Server** **aus erreichbar** sein:
150
151 * Testsystem: https:~/~/int.id.bund.de/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
152 ODER
153 * Livesystem:
154 ** bei Kommunikation über des Netz des Bundes (NdB):
155 https:~/~/prod.id.bmi.in.bund.de/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
156 ** bei Kommunikation über das Verbindungsnetz des Bundes (NdB-VN):
157 https:~/~/prod.bundid.doi-de.net/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
158 ** Achtung: Der Livesystem Postkorb-Webservice ist **nicht** direkt aus dem Internet erreichbar!
159 {{/warning}}
160 )))
161 )))
162
163 == Details für die Anbindung des ELSTER //Mein Unternehmenskontos// ==
164
165 == Details für die Anbindung der BayernID ==
166
167 Um das Servicekonto der **BayernID** anzubinden ist ein neuer Externer Benutzer anzulegen und als Authentifizierungstyp **BayernID** auszuwählen.
168
169 === Schritt 1: Konfiguration anlegen ===
170
171 {{figure image="bayernID_config1.png"}}
172 Schritt 1: Notwendige Daten für Erzeugung der Service Metadaten festlegen
173 {{/figure}}
174
175 * Im 1. Schritt der Konfiguration erscheint eine Eingabeoberfläche, wo folgende Festlegungen getroffen werden müssen:
176 ** Festlegung, ob Test- oder Live-Umgebung der **BayernID** anzubinden ist.
177 ** Erhebung von Zertifikatsinformationen, welche anschließend zur Generierung eines privaten und öffentlichen Schlüssels herangezogen werden. Dieses Schlüsselpaar dient zur Ver- und Entschlüsselung der Kommunikation, zwischen {{formcycle/}} und der **BayernID**.
178 ** Angaben zum organisatorischen und technischen Ansprechpartner. Diese Informationen werden im Zuge des Registrierungsprozesses an das **BayernID**-Portal weitergegeben.
179 * Speichern der Eingaben. Danach gelangt man zum 2. Schritt der Anbindung.
180
181 === Schritt 2: Metadaten erzeugen und registrieren ===
182
183 {{figure image="bayernID_config2.png"}}
184 Schritt 2 und 3: Download der erzeugten Meta- und vorbefüllten Vertragsdaten für eine jeweiligen Host-Adresse; Aktivierung der BayernID Authentifizierung für Formulare
185 {{/figure}}
186
187 * In diesem Schritt werden die SAML-Metadaten für die Registrierung auf Seiten der **BayernID **erzeugt. Dafür steht in der Oberfläche ein Button mit Auswahlfeld zur Verfügung. Das Auswahlfeld enthält alle im {{formcycle/}} System gefundenen Host-Adressen, über die das System erreichbar ist. Auf der Grundlage der jeweiligen Host-Adresse werden dann die Metadaten erzeugt und als Download zurück geliefert. Die jeweilige Host-Adresse bildet dabei einen Teil der Rücksprung-URL, welche später vom Identity Provider (BayernID Portal) zur Übermittlung der Authentifizierungsdaten genutzt wird.(((
188 {{info}}
189 Hinweis: Soll der BayernID-Login über unterschiedliche Host-Adressen erreichbar sein,
190 so muss für jeden Host die Metadaten-Datei erzeugt und an das BayernID-Portal zur Registrierung übermittelt werden.
191 {{/info}}
192 )))
193 * Weiterhin kann eine vorbefüllte Beitrittserklärung für den jeweiligen Host heruntergeladen werden. Die Beitrittserklärung ist bereits mit den im vorherigen Schritt erhobenen Daten vorbefüllt und muss um die noch fehlenden Daten ergänzt werden.
194 * **Beitrittserklärung** und **SAML-Metadaten** sind an das **BayernID** Portal (Mail: **BayernID@akdb.de**) zu senden, mit der Bitte, um Aufnahme in den Portalverbund.
195 * Damit ist der 1. Teil der Registrierung abgeschlossen und eine Antwort vom **BayernID** Portal muss abgewartet werden.
196
197 === Schritt 3: BayernID-Login Aktivierung ===
198
199 {{figure image="bayernID_config3.png"}}
200 BayernID Postkorbanbindung konfigurieren
201 {{/figure}}
202
203 * Dieser Schritt sollte erst durchgeführt werden, wenn Sie vom BayernID Portal Rückmeldung erhalten haben, dass ihre übermittelten Metadaten im Portal registriert und freigegeben sind. Erst mit dem Button //BayernId-Login aktivieren// wird der Authentikator im System aktiviert. Er ist damit in den Formularen verfügbar und kann eingebunden werden.(((
204 {{info}}
205 Hinweis: Wenn Sie den Login **vor** einer positiven Rückmeldung des BayernID-Portals aktivieren,
206 so kann das die **BayernID** zwar bereits in den Formularen eingebunden werden,
207 wird aber beim Aufruf in einem Fehler resultieren,
208 dass der anfragende Service dem Portal nicht bekannt ist.
209 {{/info}}
210 )))
211 * (((
212 Nach Aktivierung des Logins erweitert sich die Konfigurationsoberfläche des Authentikators.* Unter dem Punkt //Erweiterte Einstellungen// > //Konfigurtion BayernID Postkorbanbindung// können Sie das Zertifikat, welches Sie im Zuge der Registrierung ihrer Metadaten vom **BayernID **Portal erhalten haben sollten, hochladen und zusammen mit dem zugehörigen Passwort an der Authentikator-Konfiguration abspeichern.
213
214 * (((
215 Über den Button //Postkorb Verbindung prüfen// kann der Zugriff auf den Postkorb-Webservice getestet werden.
216 Der Webservice muss dabei vom {{formcycle/}} Master-Server aus erreichbar sein (dafür sind im System unter Umständen Firewall Freigaben notwendig).
217
218 (((
219 {{warning}}
220 Folgende URL muss **vom FORMCYCLE Master-Server** **aus erreichbar** sein:
221
222 * Testsystem: https:~/~/infra-pre-bayernid.freistaat.bayern/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
223 ODER
224 * Livesystem: https:~/~/bayernid.freistaat.bayern/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
225 {{/warning}}
226 )))
227
228 (((
229 {{info}}
230 **Fehlerbehebung, wenn die Prüfung des Postkorbverbindung fehl schlägt:**
231
232 Prüfen Sie, ob die Freischaltung in der Firewall erfolgt ist.
233 Der Postkorb-Webservice nutzt das HTTPS Protokoll für die Kommunikation, welches im Transport-Layer das TCP Protokoll benutzt. Deshalb sollte in ihrer Firewall die IP 193.28.249.234 (für das Livesystem **bayernid.freistaat.bayern**) oder IP 193.28.249.228 (für das Testsystem **infra-pre-bayernid.freistaat.bayern**) als TCP-Verbindungen der Port 443 (das ist der Standard-Https-Port) sowohl für die ausgehende als auch eingehende Kommunikation freigegeben sein.
234 {{/info}}
235 )))
236 )))
237 * Sollte für die Kommunikation ein Proxy-Server notwendig sein, so kann dieser in den Eingabefeldern //Proxy Host //und //Proxy Port// konfiguriert werden.
238 )))