Accountregistrierung und Client-Verwaltung
Das Self-Service-Portal (SSP) von FIT-Connect erlaubt es Ländern, Kommunen und IT-Dienstleistern, Clients und Zustellpunkte anzulegen. Clients müssen für jedes angebundene System angelegt 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 (siehe folgendes Bild).
Für die Einwahl in der Testumgebung über "Elster - MeinUnternehmenskonto" muss ein Testzertifikat von "Elster - MeinUnternehmenskonto" genutzt werden. Testzertifikate für die E4K-Testumgebung erhalten Sie über ein registriertes Vorhaben im Self-Service-Portal von Elster - MeinUnternehmenskonto. Dort können Sie über die Support-Funktion ein ganzes Paket an Testzertifikaten beantragen. Weitere Informationen zum Self-Service-Portal von Elster - MeinUnternehmenskonto finden Sie auch in diesem Quick-Start-Guide. Bitte beachten Sie, dass ein Onlinedienst erstellt werden muss. Allerdings besteht auch die Möglichkeit, dass Testzertifikate von Vorhaben an Sub-Partner weitergegeben werden. Das heißt, wenn jemand einen Online-Dienst bei uns im Self-Service-Portal registriert hat und mit weiteren Partnern, die mit dem Vorhaben assoziiert sind zusammenarbeitet, kann der ursprüngliche Anbindungspartner die Zertifikate in eigener Verantwortung seinen Partnern bereitstellen.
Das Self-Service-Portal der Testumgebung steht allen Interessierten zur Registrierung von Clients für die Testumgebung zur Verfügung.
Zugang zum SSP in der Stage- und Produktiv-Umgebung (neu/ ab Anfang November verfügbar)
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.
Zugang zum SSP in der Stage- und Produktivumgebung (bislang/ ab 02.12.2024 nicht mehr verfügbar)
Username/Passwort und Zwei-Faktor-Authentifizierung erforderlich
Für den Zugang zum Self-Service-Portal in der Stage- und Produktivumgebung ist zusätzlich zur Anmeldung per Username und Passwort eine Zwei-Faktor-Authentifizierung erforderlich. Eine Beschreibung der Zwei-Faktor-Authentifizierung finden Sie hier. Anbei eine Schritt für Schritt Anleitung zum Umgang mit der 2-Faktor-Authentifizierung ab der Stageumgebung für die Erstnutzung:
- Mail von GitLab erhalten
- In dieser Mail auf den Link für die Berechtigungsgruppe klicken
- Mit der personalisierten Mailadresse und Passwort anmelden. a. Falls dies einen Fehler aufwirft, auf „Passwort zurücksetzen“ klicken und ein neues Passwort anfordern.
- Nach dem erfolgreichen Login die 2-Faktor-Authentifizierung einrichten.
- Nach erfolgreicher Einrichtung der 2-Faktor-Authentifizierung Login in der Stage- oder Produktivumgebung.
Client-Verwaltung
In der Ansicht "Client-Verwaltung" zeigt das SSP alle Clients für Onlinedienste und Verwaltungssysteme an: Sie können Clients ändern oder löschen. Zudem können Sie das Client-Secrets eines Clients erneuern (noch nicht im folgenden Video enthalten):
Das folgende Video erläutert die Clientübersicht (Client-Verwaltung):
Clients für Onlinedienste
Einen Sender-Client anlegen
Das folgende Video zeigt, wie Sie im SSP einen Sender-Client anlegen:
Um einen Client für einen Onlinedienst anzulegen, klicken Sie zunächst im Self-Service-Portal (SSP) auf den Menüpunkt "Clients". Das SSP zeigt die Client-Verwaltung an. Im folgenden Beispiel sind noch keine Clients 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 Client ein. Weitere Angaben sind für einen Client 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 und Client-Secret
Das Self-Service-Portal erstellt beim Anlegen eines Clients eine Client-ID und ein Client-Secret. 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 Client-ID und das Client-Secret, 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 Clients für Verwaltungssysteme zu senden.
In der Testphase gibt es somit keine Einschränkungen.
Details des Clients
Das folgende Bild zeigt die Details des Clients, der im Beispiel angelegt wurde:
Die Client-ID wird angezeigt, wie auch der Client-Scope, nicht aber das Client-Secret.
Client-Secret kopieren
Um das Client-Secret zu kopieren,
klicken Sie auf die Schaltfläche "Client-Secret kopieren".
Speichern Sie anschließend das Client-Secret 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 Clients das Client-Secret kopieren.
Geht das Secret verloren,
dann müssen Sie es erneuern (siehe nächsten Absatz).
Client-Secret erneuern
Ging das Client-Secret verloren oder ist es Unberechtigten bekannt geworden, dann muss es erneuert werden.
Das folgende Video zeigt, wie Sie das Secret eines Clients erneuern.
Um das Secret eines Clients zu erneuern, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt den Client an, der im Beispiel angelegt wurde. Um das Client-Secret eines Clients zu erneuern, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal (SSP) stellt daraufhin eine Sicherheitsfrage:
Tragen Sie den Namen des Clients ein, um zu bestätigen, dass das Secret dieses Clients 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 Clients an:
Die Client-ID wird angezeigt, wie auch der Client-Scope, nicht aber das erneuerte Client-Secret.
Nach dem Erneuern des Client-Secrets müssen Sie dieses Secret bei der sendenden Anwendung (Onlinedienst) verwenden.
Name des Clients ändern
Um den Namen (Bezeichnung) eines Clients zu ändern, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt den Client an, der im Beispiel oben angelegt wurde. Um den Namen des Clients zu ändern, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal zeigt nun die Ansicht "Client bearbeiten" an:
Tragen Sie die neue Bezeichnung des Clients ein und klicken Sie auf "Speichern".
Client löschen
Um einen Client zu löschen, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt den Client an, der im Beispiel oben angelegt wurde. Um den Client zu löschen, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal zeigt nun eine Sicherheitsfrage an:
Tragen Sie die Bezeichnung des Clients ein, der gelöscht werden soll, und klicken Sie auf die aktivierte Schaltfläche "Client löschen".
Im Beispiel soll der Client mit der Bezeichnung "MeinSenderClient" gelöscht werden. Im Eingabefeld muss also "MeinSenderClient" eingetragen werden, damit die Schaltfläche "Client löschen" aktiv wird und der Client gelöscht werden kann.
Clients für Verwaltungssysteme
Client anlegen
Das folgende Video zeigt, wie Sie einen Client für ein Verwaltungssystem anlegen:
Um einen Client für ein Verwaltungssystem anzulegen, klicken Sie zunächst im Self-Service-Portal (SSP) auf den Menüpunkt "Clients". Das SSP zeigt die Client-Verwaltung an. Im folgenden Beispiel sind noch keine Clients 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 Client ein. Das folgende Beispiel verwendet die Bezeichnung "MeinVerwaltungssystem".
Optionales Feature
Sie können diesem Client 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 diesem Client einen 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 dem neuen Client 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 Client zu erstellen.
Details des Clients
Das folgende Bild zeigt die Details des Clients, der im Beispiel angelegt wurde:
Die Client-ID wird angezeigt, nicht aber das Client-Secret.
Client-ID und Client-Secret
Das Self-Service-Portal erstellt beim Anlegen eines Clients eine Client-ID und ein Client-Secret. Die Client-ID ist ein eindeutiger Identifikator für eine Anwendung (ein Verwaltungssystem). Das Client-Secret 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 kopieren
Nachdem der neue Client angelegt wurde, müssen Sie das Client-Secret kopieren. Klicken Sie dazu auf die Schaltfläche "Client-Secret kopieren", um das Client-Secret in die Zwischenablage Ihres Rechners zu übernehmen. Speichern Sie das Client-Secret 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 Clients das Client-Secret kopieren. Geht das Secret verloren, dann müssen Sie es erneuern (siehe nächsten Absatz).
Client-Secret erneuern
Ging das Client-Secret verloren oder ist es Unberechtigten bekannt geworden, dann muss es erneuert werden.
Das folgende Video zeigt, wie Sie das Secret eines Clients erneuern.
Um das Secret eines Clients 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 Clients, die im Beispiel angelegt wurden. Um das Client-Secret eines Clients zu erneuern, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal (SSP) stellt daraufhin eine Sicherheitsfrage:
Tragen Sie den Namen des Clients 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 Clients:
Die Client-ID wird angezeigt, nicht aber das erneuerte Client-Secret.
Client-Secret kopieren
Um das erneuerte Client-Secret zu kopieren,
klicken Sie auf die Schaltfläche "Client-Secret kopieren".
Speichern Sie das neue Client-Secret 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 Client-Secret kopieren,
später nicht mehr.
Nach dem Erneuern des Client-Secrets müssen Sie dieses Secret bei der empfangenden Anwendung (Verwaltungssystem) verwenden.
Name des Clients ändern
Um den Namen (Bezeichnung) eines Clients 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 Clients ein und klicken Sie auf "Speichern".
Client löschen
Um einen Client zu löschen, klicken Sie im Self-Service-Portal (SSP) zunächst auf den Menüpunkt "Clients". Die Client-Verwaltung wird angezeigt:
Die Client-Verwaltung zeigt die Clients, die im Beispiel angelegt wurden. Um einen Client zu löschen, klicken Sie bei diesem Client auf das folgende Symbol:
Das Self-Service-Portal zeigt nun eine Sicherheitsfrage an:
Tragen Sie die Bezeichnung des Clients ein, der gelöscht werden soll, und klicken Sie auf die aktivierte Schaltfläche "Client löschen".
Im Beispiel soll der Client 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 Client gelöscht werden kann.