Accountregistrierung und Zugangsdaten-Verwaltung
Das Self-Service-Portal (SSP) von FIT-Connect erlaubt es Ländern, Kommunen und IT-Dienstleistern, Zugangsdaten einzurichten und Zustellpunkte anzulegen. Zugangsdaten müssen für jedes angebundene System eingerichtet werden (für Onlinedienste und Verwaltungssysteme), Zustellpunkte dagegen nur für Verwaltungssysteme. Die Seite Anlegen eines Zustellpunktes zeigt, wie Sie für Verwaltungssysteme Zustellpunkte anlegen.
Anmeldung am Self-Service-Portal (SSP)
Der Zugang zum Self-Service-Portals (SSP) ist nur über einen Identity-Provider möglich (zum Beispiel über GitLab, siehe folgendes Bild).
Zugang zum SSP in der Testumgebung
In der Testumgebung legt FIT-Connect keinen Account für Sie an. Daher ist der Zugang über Ihren eigenen Account bei GitHub,
GitLab, OpenCoDE oder über "Elster - MeinUnternehmenskonto" möglich.
Für die Einwahl in der Testumgebung über "Elster - MeinUnternehmenskonto" muss ein Zertifikat von "Elster - MeinUnternehmenskonto" genutzt werden. Ab dem 03.02.2025 ist anstatt eines Testzertifikates ein Produktivzertifikat für den Login "Elster-MeinUnternehmenskonto" notwendig. Die Anleitung zur Beantragung des Zertifikats finden Sie auf unserer Dokumentationsseite Elster Login.
Das Self-Service-Portal der Testumgebung steht allen Interessierten zur Registrierung von Zugangsdaten für die Testumgebung zur Verfügung.
Zugang zum SSP in der Stage- und Produktiv-Umgebung
Für die Stage- und Produktiv-Umgebung ist Elster erforderlich
Für den Zugang zum Self-Service-Portal in der Stage- und Produktivumgebung ist ein Unternehmenskonto bei Elster erforderlich. Der bisherige Zugang über Username/Passwort und der Zwei-Faktor-Authentifizierung ist bis zum 02.12.2024 möglich. Die Seite Login über Elster beschreibt, wie Sie Zugang zur Stage- und Produktiv-Umgebung von FIT-Connect erhalten.
Nach erfolgreicher Anmeldung zeigt das Self-Service-Portal die Startseite an: Die Client-Verwaltung.
Zugangsdaten-Verwaltung
In der Ansicht "Client-Verwaltung" zeigt das SSP alle Zugangsdaten für Onlinedienste und Verwaltungssysteme an: Sie können Zugangsdaten ändern oder löschen. Zudem können Sie das Client-Secret (Zugangs-Geheimnis) eines Zugangs erneuern (noch nicht im folgenden Video enthalten):
Das folgende Video erläutert die Clientübersicht (Client-Verwaltung):
Zugangsdaten für Onlinedienste
Einen Sender-Zugang anlegen
Das folgende Video zeigt, wie Sie im SSP einen Sender-Zugang anlegen:
Um einen Zugang für einen Onlinedienst anzulegen, klicken Sie zunächst im Self-Service-Portal (SSP) auf den Menüpunkt "Clients". Das SSP zeigt die Zugangs-Verwaltung an. Im folgenden Beispiel sind noch keine Zugänge vorhanden:
Klicken Sie nun auf die Schaltfläche "+ Client anlegen" und dann auf die Schaltfläche "Onlinedienst anlegen". Geben Sie eine Bezeichnung für den Zugang ein. Weitere Angaben sind für einen Zugang des Typs "Sender" nicht erforderlich. Im folgenden Beispiel wurde die Bezeichnung "MeinSenderClient" gewählt:
Klicken Sie anschließend auf die Schaltfläche "Speichern".
Client-ID (Zugangs-Kennung) und Client-Secret (Zugangs-Geheimnis)
Das Self-Service-Portal erstellt beim Anlegen eines Zugangs eine Client-ID (Zugangs-Kennung) und ein Client-Secret (Zugangs-Geheimnis). Die Client-ID ist ein eindeutiger Identifikator für eine Anwendung (für ein sendendes System). Das Client-Secret ist ein Geheimnis, das nur dieser Anwendung und dem Authentifizierungs-Server (OAuth-Server) bekannt ist. Die Anwendung benötigt die Zugangs-Kennung und das Zugangs-Geheimnis, damit sie sich gegenüber dem Authentifizierungs-Server ausweisen kann.
Vom Authentifizierungs-Server erhält die Anwendung ein Access-Token (Zugriffs-Berechtigung), die die Anwendung (den Onlinedienst) berechtigt, Anträge über FIT-Connect einzureichen.
Beim Abruf von Access-Tokens ist es ist technisch möglich, die gewünschten OAuth-Scopes explizit anzugeben. Jedoch können Namen und Anzahl von OAuth-Scopes im Rahmen von API Updates durch FIT-Connect geändert werden. Und dies auch ohne Veröffentlichung einer Major-Version und der Beachtung der zugehörigen Migrationsfrist. Die explizite Angabe von OAuth-Scopes kann beim Abholen eines Access-Tokens unter diesen Umständen zu einem Bruch der Verbindung führen. Daher raten wir ausdrücklich von der expliziten Angabe von OAuth-Scopes ab!
Für den Zugriff auf FIT-Connect werden Berechtigungen in Form von OAuth-Scopes verwaltet.
Für Sender legen sie fest,
ob ein sendendes System eine Einreichung (Antrag) an einen bestimmten Zustellpunkt senden darf.
Die Seite OAuth-Scopes für sendende Systeme enthält weitere Informationen zu den Berechtigungen sendender Systeme.
In der Testphase ist der Scope mit send:region:DE
festgelegt.
Diese Berechtigung erlaubt es Sendern,
Anträge an alle Zugänge für Verwaltungssysteme zu senden.
In der Testphase gibt es somit keine Einschränkungen.
Details des Zugangs
Das folgende Bild zeigt die Details des Zugangs, der im Beispiel angelegt wurde:
Die Client-ID (Zugangs-Kennung) wird angezeigt, wie auch der Client-Scope, nicht aber das Client-Secret (Zugangs-Geheimnis).
Client-Secret (Zugangs-Geheimnis) kopieren
Um das Zugangs-Geheimnis zu kopieren,
klicken Sie auf die Schaltfläche "Client-Secret kopieren".
Speichern Sie anschließend das Zugangs-Geheimnis in einer Datei ab.
Die Schaltfläche "Client-Secret kopieren" wird später nicht mehr dargestellt, d. h.
Sie können nur unmittelbar nach dem Anlegen eines Zugangs das Zugangs-Geheimnis kopieren.
Geht das Zugangs-Geheimnis verloren,
dann müssen Sie es erneuern (siehe nächsten Absatz).
Client-Secret (Zugangs-Geheimnis) erneuern
Geht das Zugangs-Geheimnis verloren oder ist es Unberechtigten bekannt, dann muss es erneuert werden.
Das folgende Video zeigt, wie Sie das Secret eines Zugangs erneuern.
Um das Zugangs-Geheimnis eines Zugangs zu erneuern, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Zugangs-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt den Zugang an, der im Beispiel angelegt wurde. Um das Client-Secret (Zugangs-Geheimnis) eines Zugangs zu erneuern, klicken Sie bei diesem Zugang auf das folgende Symbol:
Das Self-Service-Portal (SSP) stellt daraufhin eine Sicherheitsfrage:
Tragen Sie den Namen des Zugangs ein, um zu bestätigen, dass das Zugangs-Geheimnis dieses Zugangs erneuert werden soll. Im Beispiel lautet der Name "MeinSenderClient". Klicken Sie dann auf die aktivierte Schaltfläche "Ja, Client-Secret erneuern".
Das SSP zeigt nun die Detail-Ansicht dieses Zugangs an:
Die Zugangs-Kennung wird angezeigt, wie auch der Client-Scope, nicht aber das erneuerte Zugangs-Geheimnis.
Nach dem Erneuern des Client-Secrets müssen Sie dieses Zugangs-Geheimnis bei der sendenden Anwendung (Onlinedienst) verwenden.
Name des Zugangs ändern
Um den Namen (Bezeichnung) eines Zugangs zu ändern, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Zugangs-Verwaltung wird angezeigt:
Die Zugangs-Verwaltung zeigt den Client an, der im Beispiel oben angelegt wurde. Um den Namen des Zugangs zu ändern, klicken Sie bei diesem Zugang auf das folgende Symbol:
Das Self-Service-Portal zeigt nun die Ansicht "Client bearbeiten" an:
Tragen Sie die neue Bezeichnung des Zugangs ein und klicken Sie auf "Speichern".
Zugang löschen
Um einen Zugang zu löschen, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Zugangs-Verwaltung wird angezeigt:
Die Zugangs-Verwaltung zeigt den Client an, der im Beispiel oben angelegt wurde. Um den Zugang zu löschen, klicken Sie bei diesem Zugang auf das folgende Symbol:
Das Self-Service-Portal zeigt nun eine Sicherheitsfrage an:
Tragen Sie die Bezeichnung des Zugangs ein, der gelöscht werden soll, und klicken Sie auf die aktivierte Schaltfläche "Client löschen".
Im Beispiel soll der Zugang mit der Bezeichnung "MeinSenderClient" gelöscht werden. Im Eingabefeld muss also "MeinSenderClient" eingetragen werden, damit die Schaltfläche "Client löschen" aktiv wird und die Zugangsdaten gelöscht werden.
Zugangsdaten für Verwaltungssysteme
Zugangsdaten anlegen
Das folgende Video zeigt, wie Sie Zugangsdaten für ein Verwaltungssystem anlegen:
Um Zugangsdaten für ein Verwaltungssystem anzulegen, klicken Sie zunächst im Self-Service-Portal (SSP) auf den Menüpunkt "Clients". Das SSP zeigt die Zugangsdaten-Verwaltung an. Im folgenden Beispiel sind noch keine Zugangsdaten vorhanden:
Klicken Sie nun auf die Schaltfläche "+ Client anlegen" und dann auf die Schaltfläche "Verwaltungssystem anlegen". Tragen Sie eine Bezeichnung für den neuen Zugang ein. Das folgende Beispiel verwendet die Bezeichnung "MeinVerwaltungssystem".
Optionales Feature
Sie können diesem Zugang erlauben, über die Destination Management API einen Zustellpunkt zu erstellen. Das Beispiel verwendet diese Möglichkeit nicht. Die Seite Verwalten per API Aufrufe beschreibt das Erstellen von Zustellpunkten per API.
Erlaubte Zustellpunkte
Wenn Sie Zugangsdaten einem Zustellpunkt zuordnen, dann erlauben Sie dem Client, auf den zugeordneten Zustellpunkt zuzugreifen und Anträge entgegenzunehmen.
Im Beispiel gibt es bereits den Zustellpunkt "MeinZustellpunkt":
Um diesen Zustellpunkt den neuen Zugangsdaten zuzuordnen, klicken Sie auf diesen Zustellpunkt. Die Seite Zustellpunkte beschreibt, wie Sie im Self-Service-Portal einen Zustellpunkt erstellen.
Klicken Sie auf die Schaltfläche "Speichern", um den neuen Zugang zu erstellen.
Details des Zugangs
Das folgende Bild zeigt die Details des Zugangs, der im Beispiel angelegt wurde:
Die Client-ID (Zugangs-Kennung) wird angezeigt, nicht aber das Client-Secret (Zugangs-Geheimnis).
Client-ID (Zugangs-Kennung) und Client-Secret (Zugangs-Geheimnis)
Das Self-Service-Portal erstellt beim Anlegen eines Clients eine Client-ID und ein Client-Secret. Die Zugangs-Kennung ist ein eindeutiger Identifikator für eine Anwendung (ein Verwaltungssystem). Das Zugangs-Geheimnis ist ein Geheimnis, das nur dieser Anwendung und dem Authentifizierungs-Server (OAuth-Server) bekannt ist. Die Anwendung benötigt die Client-ID und das Client-Secret, damit sie sich gegenüber dem Authentifizierungs-Server ausweisen kann.
Vom Authentifizierungs-Server erhält die Anwendung Zugriffs-Berechtigungen (Access-Token), die die Anwendung (ein empfangendes System) berechtigen, Anträge über FIT-Connect zu erhalten.
Scopes
Für den Zugriff auf FIT-Connect werden Berechtigungen in Form von OAuth-Scopes verwaltet. Für Empfänger legen sie fest, ob ein empfangendes System Einreichungen (Anträge) für einen bestimmten Zustellpunkt erhalten darf.
Beim Abruf von Access-Tokens ist es ist technisch möglich, die gewünschten OAuth-Scopes explizit anzugeben. Jedoch können Namen und Anzahl von OAuth-Scopes im Rahmen von API Updates durch FIT-Connect geändert werden. Und dies auch ohne Veröffentlichung einer Major-Version und der Beachtung der zugehörigen Migrationsfrist. Die explizite Angabe von OAuth-Scopes kann beim Abholen eines Access-Tokens unter diesen Umständen zu einem Bruch der Verbindung führen. Daher raten wir ausdrücklich von der expliziten Angabe von OAuth-Scopes ab!
Die Seite OAuth-Scopes für empfangende Systeme enthält weitere Informationen zu den Berechtigungen empfangender Systeme.
Client-Secret (Zugangs-Geheimnis) kopieren
Nachdem der neue Zugang angelegt wurde, müssen Sie das Client-Secret (Zugangs-Geheimnis) kopieren. Klicken Sie dazu auf die Schaltfläche "Client-Secret kopieren", um das Zugangs-Geheimnis in die Zwischenablage Ihres Rechners zu übernehmen. Speichern Sie das Zugangs-Geheimnis in einer Datei.
Die Schaltfläche "Client-Secret kopieren" wird später nicht mehr dargestellt, d. h. Sie können nur unmittelbar nach dem Anlegen eines Zugangs das Client-Secret kopieren. Geht das Geheimnis verloren, dann müssen Sie es erneuern (siehe nächsten Absatz).
Client-Secret (Zugangs-Geheimnis) erneuern
Ging das Zugangs-Geheimnis verloren oder ist es Unberechtigten bekannt geworden, dann muss es erneuert werden.
Das folgende Video zeigt, wie Sie das Zugangs-Geheimnis eines Clients erneuern.
Um das Secret eines Zugangs zu erneuern, klicken im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt die Zugänge, die im Beispiel angelegt wurden. Um das Client-Secret (Zugangs-Geheimnis) eines Clients zu erneuern, klicken Sie bei diesem Zugang auf das folgende Symbol:
Das Self-Service-Portal (SSP) stellt daraufhin eine Sicherheitsfrage:
Tragen Sie den Namen des Zugangs ein, um zu bestätigen, dass das Secret dieses Clients erneuert werden soll. Im Beispiel lautet der Name "MeinVerwaltungssystem". Klicken Sie dann auf die aktivierte Schaltfläche "Ja, Client-Secret erneuern".
Das SSP zeigt nun die Detail-Ansicht dieses Zugangs:
Die Client-ID (Zugangs-Kennung) wird angezeigt, nicht aber das erneuerte Client-Secret (Zugangs-Geheimnis).
Client-Secret (Zugangs-Geheimnis) kopieren
Um das erneuerte Zugangs-Geheimnis zu kopieren,
klicken Sie auf die Schaltfläche "Client-Secret kopieren".
Speichern Sie das neue Zugangs-Geheimnis in einer Datei.
Die Schaltfläche "Client-Secret kopieren" wird später nicht mehr dargestellt, d. h.
Sie können nur unmittelbar nach dem Erneuern das Zugangs-Geheimnis kopieren,
später nicht mehr.
Nach dem Erneuern des Client-Secrets müssen Sie dieses Geheimnis bei der empfangenden Anwendung (Verwaltungssystem) verwenden.
Name des Zugangs ändern
Um den Namen (Bezeichnung) eines Zugang zu ändern, klicken im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt die Clients an, die im Beispiel angelegt wurden. Um den Namen eines Clients zu ändern, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal zeigt die Ansicht "Client bearbeiten" an:
Tragen Sie die neue Bezeichnung des Zugangs ein und klicken Sie auf "Speichern".
Zugangsdaten löschen
Um einen Zugang zu löschen, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Zugangsdaten-Verwaltung wird angezeigt:
Die Zugangsdaten-Verwaltung zeigt die Zugänge, die im Beispiel angelegt wurden. Um Zugangsdaten zu löschen, klicken Sie auf das folgende Symbol des entsprechenden Zugangs:
Das Self-Service-Portal zeigt nun eine Sicherheitsfrage an:
Tragen Sie die Bezeichnung des Zugangs ein, der gelöscht werden soll, und klicken Sie auf die aktivierte Schaltfläche "Client löschen".
Im Beispiel soll der Zugang mit der Bezeichnung "MeinVerwaltungssystem" gelöscht werden. Im Eingabefeld muss also "MeinVerwaltungssystem" eingetragen werden, damit die Schaltfläche "Client löschen" aktiv wird und der Zugang gelöscht werden kann.