Bürgerservices-Plugin: Anbindung BundID

Geändert am Fr, 5 Sep um 3:41 NACHMITTAGS

Inhalt

Um das Servicekonto der BundID anzubinden ist ein neuer Login Dienst anzulegen und als Authentifizierungstyp BundID auszuwählen.

Notwendige Vorarbeiten im BundID Self Service Portal (SSP)

Bevor mit der Einrichtung der Anbindung begonnen werden kann, muss eine Registrierung der eigenen Organisation im BundID Self Service Portal (SSP) (https://ssp.id.bund.de/ip) erfolgen.

Im weiteren Verlauf ist dann über dieses Portal im ersten Schritt ein Antrag Komponente Authentifizierung (zu finden im Menü unter Leistungen) zu erstellen.

Wenn dieser Antrag durch die BundID genehmigt wurde, ist im zweiten Schritt eine Leistung Upload und Aktualisierung der Metadaten zu erstellen. In deren Konfigurationsverlauf sind Daten zu hinterlegen, welche aus der nachfolgend beschriebenen Konfiguration des BundID Login-Dienstes in Xima® formcycle entstehen.

Nähere Informationen zu den einzelnen Konfigurationsmöglichkeiten im BundID SSP können Sie auch den Videoanleitungen der BundID entnehmen, welche Sie unter https://ssp.id.bund.de/ip?id=downloads finden können.

Schritt 1: Konfiguration anlegen

Schritt 1: Notwendige Daten für Erzeugung des öffentlichen Zertifikates definieren

Im 1. Schritt der Konfiguration erscheint eine Eingabeoberfläche, wo folgende Festlegungen getroffen werden müssen:

Festlegung, ob Test- oder Live-Umgebung der BundID anzubinden ist.
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 Xima® formcycle und der BundID.
Angaben (z.B. der Fachanwendungsname) welche später für die Anzeige auf Seiten der BundID dienen.

Nach dem Speichern der Eingaben gelangt man zum 2. Schritt der Anbindung.

Hinweise zum Anzeigenamen der Fachanwendung

Der Anzeigename der Fachanwendung wird dem Nutzer im BundID-Portal angezeigt, bevor die Nutzerdaten an formcycle zurück übermittelt werden. Standardmäßig wird der Wert "XIMA FORMCYCLE" gesetzt. Ein Überschreiben des Wertes ist jederzeit möglich, wobei maximal 50 Zeichen für den neuen Namen erlaubt sind. Hier könnten Sie beispielweise Ihren Amtsnamen eintragen.

Der Anzeigename der Fachanwendung wird global in allen Formularen des Mandanten verwendet. Weiterhin kann der Anzeigename auch direkt am Login-Button definiert werden. Dieser Wert überschreibt den globalen Anzeigenamen und ermöglicht die Angabe eines eigenen Namens pro Formular.

Schritt 2: Metadaten erzeugen und registrieren

Schritt 2 und 3: Bereitstellung der notwendigen Informationen für die Konfiguration des Anbindungsvorhaben im BundID SSP; Aktivierung der BundID Authentifizierung für Formulare

In diesem Schritt werden die notwendigen Daten zum Ausfüllen der Leistung Upload und Aktualisierung der Metadaten auf Seiten der BundID erzeugt.

Wenn auf Seiten der BundID die Leistung Upload und Aktualisierung der Metadaten konfiguriert wird, so sind folgende Angaben aus der Konfiguration zu entnehmen und zu hinterlegen:

die Service Provider Entity ID
das genutzte Signier- und Verschlüsselungsverfahren
die Assertion-Consumer-Service-URL(s)
das Gültigkeitsdatum für das öffentliche Zertifikat
das öffentliche Zertifikat

Hinweis zu den Assertion-Consumer-Service-URLs:

In der Oberfläche werden alle im formcycle System gefundenen Host-Adressen, über die das System aktuell erreichbar ist, als Assertion-Consumer-Service-URLs aufgeführt.
Im BundID SSP müssen anschließend nur die URLs als vertrauenswürdige URLs hinterlegt werden, über welche später auch die Authentifizierung mi der BundID erfolgen soll. 
In vielen Fällen ist / sind dies nur die Frontend-Server URL(s), da nur diese auch über das Internet erreichbar sind.

Die Online-Service ID (BMI ID) muss aus dem BundID SSP in die formcycle Oberfläche übertragen werden.

Anschließend muss der Login-Dienst gespeichert werden.
Die BMI ID wurde beim Erstellen der Authentifizierungs-Komponente auf Seiten der BundID erzeugt und wird später bei jeder Authentifizierungs-Anfrage übermittelt. Auf Seiten der BundID ist damit ein Rückschluss auf die entsprechende Anbindung möglich.

Nach dem Hinterlegen und Absenden der Daten der Leistung auf Seiten der BundID ist der 1. Teil der Registrierung abgeschlossen und eine Freigabe des Anbindungsvorhabens auf Seiten der BundID muss abgewartet werden.

Schritt 3: BundID-Login Aktivierung

Globale Konfiguration des Anfrageverhaltens

Dieser Schritt sollte erst durchgeführt werden, wenn im BundID SSP, die Meldung vorhanden ist, dass dem Antrag des Anbindungsvorhabens stattgegeben wurde. 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.

Hinweis:
Wenn Sie den Login vor einer positiven Rückmeldung im BundID SSP aktivieren, so kann der BundID Login zwar bereits in Formulare eingebunden werden, wird aber beim Aufruf in einem Fehler resultieren, da der anfragende Service im BundID Portal nicht bekannt ist.

Optionale Limitierung erlaubter Origins: Bei Einbindung der Formulare innerhalb abweichender Domänen können hier die jeweiligen Origins nach dem Muster (https://www.xima.de) angegeben werden. Diese dienen zur Verifizierung der Anfragen innerhalb des Authentifizierungs-Workflows. Die durch das System zur Verfügung gestellten Mandant- und Frontend-Server-URLs müssen dabei nicht explizit angegeben werden.
Sind hier keine Werte definiert werden alle Origins zugelassen.

Konfiguration Identity Provider Anfrageverhalten

Nach Aktivierung des Logins erweitert sich die Konfigurationsoberfläche des Authentifikators. Unter dem Punkt Erweiterte Einstellungen > Konfiguration Identity Provider Anfrageverhalten kann das Anfrageverhalten für alle Formulare, welche diesen Authentifikator später über den Formularzugriff angebunden haben, beeinflusst werden. Dabei sind folgende Einstellungen möglich:

Vertrauensniveau: Angaben in dieser Eigenschaft dienen zum Einschränken der Authentisierungsverfahren auf zugelassene Vertrauensniveaus.
Einschränkungen dieser Art werden an referenzierende Identity Provider weitergereicht, wenn dies durch den aufrufenden Identity Provider unterstützt wird.
Login Methoden einschränken: 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.
Pflichtelemente: Über diese Eigenschaft können Attribute als verpflichtende Nutzereigenschaften angefordert werden.
Alle Authentisierungsverfahren, welche die geforderten Attribute nicht erfüllen, werden dadurch ausgeblendet.
Sofern der Formular-Workflow beispielsweise die Kommunikation mit dem Postkorb zwingend erfordert,
kann hier der Wert "Postkorb" angegeben werden, wodurch unter anderem das Ausblenden der temporären Anmeldung erreicht wird.
Angeforderte Eigenschaften einschränken: Angaben in dieser Eigenschaft dienen zum Einschränken der zurück gelieferten Eigenschaften aus einer erfolgreichen Nutzer-Anmeldung.
In erster Linie ist diese Eigenschaft dazu gedacht, dem Grundsatz der Datensparsamkeit aus den Vorgaben der DSGVO (Datenschutz-Grundverordnung) gerecht zu werden.
Sind keine Werte gesetzt, erfolgt keine Einschränkung und es werden alle vom Identity-Provider zur Verfügung
gestellten Nutzer-Eigenschaften zurück geliefert.

Konfiguration BundID Postkorbanbindung

Unter dem Punkt Konfiguration BundID Postkorbanbindung kann zwischen einer Anbindung der Postkorb Webservice-Schnittstelle über SOAP oder REST gewählt werden.

Hinweis:
Die Anbindung des Postkorbs über die SOAP-Schnittstelle wird nur noch bis 30.06.2025 durch die BundID unterstützt. Nach diesem Zeitpunkt ist zwingend auf die Kommunikation über REST umzustellen.

Anbindung über SOAP (Simple Object Access Protocol)

Die Anbindung über SOAP erfordert keine weiteren Konfiguration und steht nach dem Anlegen des BundID Login-Dienstes sofort zur Verfügung, wenn die nachfolgend aufgeführten Bedingungen erfüllt sind:

Folgende URL muss vom formcycle Master-Server aus erreichbar sein:				Testsystem: https://int.id.bund.de/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
ODER
Livesystem:						bei Kommunikation über des Netz des Bundes (NdB):								
https://prod.id.bmi.in.bund.de/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
bei Kommunikation über das Verbindungsnetz des Bundes (NdB-VN):								
https://prod.bundid.doi-de.net/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm
Achtung: Der Livesystem Postkorb-Webservice ist nicht direkt aus dem Internet erreichbar!

Über den Button Postkorb Verbindung prüfen kann der Zugriff auf den Postkorb-Webservice getestet werden.

Anbindung über REST (Representational State Transfer)

Damit die Kommunikation mit dem REST-Webservice der BundID möglich ist, müssen folgende Bedingungen erfüllt sein:

Folgende URL muss vom formcycle Master-Server aus erreichbar sein:				Testsystem: https://int.zbp.bund.de
ODER
Livesystem:						bei Kommunikation über des Netz des Bundes (NdB):								
https://prod.zbp.bmi.in.bund.de
bei Kommunikation über das Verbindungsnetz des Bundes (NdB-VN):								
https://prod.zbp.bundid.doi-de.net
Achtung: Der Livesystem Postkorb-Webservice ist nicht direkt aus dem Internet erreichbar!

Schritt 1: Certificate-Signing-Request erstellen im BundID SSP hochladen

Um eine Anbindung über REST zu bewerkstelligen muss im Vorfeld ein CSR (Certificate-Signing-Request) über das BundID SSP gestellt werden. Die Erstellung des CSR kann über die Oberfläche des BundID Login-Dienstes erfolgen:

Schritt 1 der REST-Service Anbindung: Erstellung CSR zum Upload im BundID SSP

Nachdem der CSR über den Button CSR erzeugen erzeugt und heruntergeladen wurde, muss der Login-Dienst gespeichert werden.

Um den erzeugten CSR im BundID SSP hochzuladen muss dort zuvor eine Leistung "Antrag Komponente Postfach" erstellt werden. Nachdem diese bewilligt wurde, kann eine Leistung "BundID-Postfach-Zertifikat beantragen" ausgewählt und dort die zuvor erstellte CSR-Datei hochgeladen werden.

Schritt 2: PKI-Zertifikat am Login-Dienst hinterlegen

Im 2. Schritt der Anbindung muss das PKI-Zertifikat, welches aus dem CSR erzeugt wurde, am Login-Dienst hinterlegt werden. Dazu wird das Zertifikat über den Button Hochladen am Dienst hinterlegt. Beim Speichern der Konfiguration wird der private Schlüssel automatisch gegen den im PKI-Zertifikat hinterlegten öffentlichen Schlüssel geprüft. Wenn zwischen privaten und öffentlichen Schlüssel eine Zusammengehörigkeit besteht, so wird die Konfiguration gespeichert.

Schritt 1 der REST-Service Anbindung: Hinterlegen des PKI-Zertifikats

Über den Button Postkorb Verbindung prüfen kann der Zugriff auf den Postkorb-Webservice getestet werden. Die Kommunikation zum Postkorb der BundID findet ab diesem Zeitpunkt über den REST-Webservice statt.

Erweiterung der Sendemöglichkeiten über FIT-Connect

Durch die im obigen Abschnitt erwähnte Problematik einer Einbindung des formcycle Systems in das NdB bzw. NdB-VN zum Übertragen von Nachrichten an das BundID Live-System, ist die konfigurative Möglichkeit einer Anbindung von FIT-Connect zur Nachrichtenübermittlung vorhanden.

Achtung:

Aktuell ist nur eine Übermittlung an das BundID Testsystem möglich, da sich auf Seiten von FIT-Connect der entsprechende Zustellpunkt noch in Erstellung befindet. Sobald dieser bekannt ist, wird die entsprechende Konfiguration am Login-Dienst für das BundID Live-System verfügbar sein.

Für eine Anzeige der Konfigurationsmöglichkeit zur Anbindung von FIT-Connect als Übertragungsmedium der Postkorb-Nachrichten müssen folgende Voraussetzungen getroffen werden:

das FIT-Connect Plugin muss im System vorhanden sein
die Postkorb-Anbindung muss über den REST-Webservice erfolgen und diese Konfiguration muss vollständig sein

Konfiguration für die Übertragung von Postkorb-Nachrichten mittels FIT-Connect Anbindung

Nachrichtenversand über FIT-Connect

Aktiviert / Deaktiviert die Sendemöglichkeit über FIT-Connect. Wird nur angezeigt, wenn die im Vorfeld beschriebenen Voraussetzungen gegeben sind und die BundID Zielumgebung die entsprechende Funktionalität unterstützt.

FIT-Connect Client-ID

Client-ID aus dem FITKO Self Service Portal (SSP). Muss zum hinterlegten Client-Secret passen.

FIT-Connect Client-Secret

Client-Secret aus dem FITKO SSP. Muss zur hinterlegten Client-ID passen.

Proxy-Server definieren

Weiterhin können die Daten für einen Proxy-Server hinterlegt werden, wenn dieser für die Kommunikation zum BundID Postkorb notwendig sein sollte.

Konfigurationsmöglichkeiten für Proxy-Server Nutzung bei Postkorb-Kommunikation

Proxy Host

Host-Name oder IP-Adresse eines Proxy-Servers, welcher für die Kommunikation genutzt werden soll.

Proxy Port

Portangabe (Zahl) für die Kommunikation über einen Proxy-Server.

Proxy-Server Authentifizierung benutzen?

Aktiviert / Deaktiviert eine Basic-Auth Authentifizierung am Proxy-Server

Proxy Login

Basic-Auth Login zur Authentifizierung an einem Proxy-Server

Proxy Passwort

Basic-Auth Passwort zur Authentifizierung an einem Proxy-Server

Troubleshooting

Im folgenden Abschnitt werden mögliche Fehlerszenarien dokumentiert.

Wichtig ist dabei, dass ein erfolgreicher Aufruf nur über eine Domain erfolgen kann, welche in den Assertion-Consumer-Service URLs auf Seiten der BundID hinterlegt wurde. 

Diese URL(s) repräsentieren somit für den Identity Provider (IDP) vertrauenswürdige Quellen für eine Authentifizierungsanfrage. 

Erfolgt eine Authentifizierungsanfrage über eine, für den IDP unbekannte Quelle, so wird diese vom IDP abgelehnt und man erhält eine Fehlerseite.

Login-Dienst testen fehlgeschlagen: EndpointResolutionFailed

Beispielhafte Ausgangssituation:

auf Seiten der BundID wurde im Vorfeld eine Assertion-Consumer-Service-URL mit folgender Domain (welche über einen Frontend-Server bereitgestellt wird) hinterlegt:
https://bund.formcycle.eu/frontend-server/auth/callback...
das formcycle Backend zur Konfiguration des Login-Dienstes ist nur aus dem Intranet erreichbar und wurde über eine Domain https://formcycle.intern/formcylce/... aufgerufen

Nach dem Klick auf den Login-Dienst testen Button innerhalb der Login-Dienst Konfiguration und der Weiterleitung zur BundID ergibt sich folgendes Fehlerbild:

Beispiel für Fehlerseite aufgrund einer Anfrage mit einer nicht registrierten Domain

Die Aufruf wird je nach Umgebung zu folgender URL weitergeleitet (hier Testumgebung):

https://int.id.bund.de/de/idpError?idp.code=EndpointResolutionFailed&url=

Der Fehler ist darauf zurückzuführen, dass für eine Authentifizierungs-Anfrage immer die aktuell genutzte Domain, mit der das formcycle-System gerade aufgerufen wird, genutzt wird. In dem konstruierten Fallbeispiel ist dies formcycle.intern. Der angesprochene Identity-Provider (IDP) erwartet aber eine Anfrage über die (auf seiner Seite als vertrauenswürdig gekennzeichnete) Domain bund.formcycle.eu.

Da auf Seiten des IDP die übermittelte Assertion-Consumer-Service-URL nicht der erwarteten URL entspricht, lehnt der IDP die Anfrage ab und antwortet entsprechend mit der dargestellten Fehlerseite.

Wenn beispielsweise bei den Assertion-Consumer-Service-URL nur eine Domain zum Frontend-Server angegeben hat, muss das Test-Formular für diesen Frontend-Server freigegeben und auch über diesen aufgerufen werden. Nur so kann eine Nutzung und Übertragung der vertrauenswürdigen Domain erfolgen.