🌐 Web | 👤 Entwickler
Du kannst eine SFTP-Verbindung (auch „Jail“ genannt) verwenden, um dateibasierte Daten sicher zwischen Yokoy und Deinen Drittanbietersystemen zu übertragen. Du kannst den Yokoy SFTP-Server verwenden, um Stammdaten (d. h. Benutzer, Kostenstellen, Tags, Transaktionen usw.) in Yokoy zu importieren und Finanzdaten in ein externes System zu exportieren.
Um eine SFTP-Verbindung für den Dateiaustausch einzurichten, musst Du Folgendes festlegen:
Wo findet der Dateiaustausch statt (auf dem FTP-Server von Yokoy), und
wie wird die in das sichere Verzeichnis hochgeladene Datei von den Diensten von Yokoy verarbeitet und in das System importiert („Verdrahtung“).
Um den Dateiaustausch mit Yokoy zu ermöglichen, verwendet Yokoy einen Azure-SFTP-Server. Der Server ist partitioniert, um sichere Verzeichnisse („Jails“) für jeden Kunden bereitzustellen.
✏️ Hinweis
Stelle sicher, dass Du die SFTP-IP-Adressen von Yokoy zur Genehmigungsliste Deiner Firma hinzufügst:
Testumgebung: exchange.test.yokoy.ai (20.203.214.32)
Produktionsumgebung: exchange.yokoy.ai (20.203.148.139)
🚧 Vorsicht
Wenn Deine SFTP-Verbindung von Yokoy eingerichtet wurde, kann es sein, dass der Hostname fe.yokoy.ai statt exchange.yokoy.ai lautet, da hierbei der frühere SFTP-Server von Yokoy verwendet wird. Dieser Server wird weiterhin für bestimmte Kunden betrieben.
Falls das bei Dir der Fall sein sollte, muss die IP-Adresse fe.yokoy.ai (34.65.67.218) auf die Freigabeliste Deines Unternehmens gesetzt werden.
Unter Admin > Entwickler > SFTP-Verbindungen kannst Du die Konfiguration einsehen, allerdings keine Details ändern. Wenn eine Anpassung der Konfiguration erforderlich ist, musst Du dich ggf. an Yokoy wenden.
Eine SFTP-Verbindung einrichten
Bevor Du mit der Übertragung von Dateien beginnen kannst, musst Du zunächst die Anmeldeinformationen für die Verbindung einrichten. Yokoy verwendet einen Azure-Server, um einen sicheren Dateiaustausch zu ermöglichen. Zur Authentifizierung gegenüber dem Server kannst Du entweder einen SSH-Schlüssel oder ein Passwort verwenden.
🚧 Vorsicht
Yokoy empfiehlt Dir, für einen sicheren Zugang die SSH-Verschlüsselung zu verwenden.
✏️ Hinweis
Um die Registerkarte SFTP-Verbindungen unter Admin > Entwickler anzuzeigen, muss SFTP für Deine Organisation aktiviert sein. Wenn Du sie nicht siehst, wende Dich an Yokoy Support.
Authentifizierung über SSH-Schlüssel
Du kannst die Authentifizierung mit öffentlichem Schlüssel verwenden, wenn Du Dich mit dem Yokoy-Server verbindest.
Der SFTP-Benutzername muss individuell sein und ausschließlich Kleinbuchstaben (d. h. keine Großbuchstaben), keine Unterstriche, keine Bindestriche und keine Leerzeichen enthalten. Der öffentliche Schlüssel muss das Format OpenSSHG haben.
💡 Tipp
Du kannst den aktuellen Schlüssel über die folgende Befehlszeile in das benötigte Format konvertieren:
ssh-keygen -i -f oldkey > newkey
Du solltest eine moderne Chiffre verwenden, um Deinen öffentlichen SSH-Schlüssel zu generieren. Yokoy unterstützt insbesondere diese Chiffren:
| Chiffre |
Host-Schlüssel-Algorithmen |
|
SSH-Schlüssel-Validierung
Wenn Du den öffentlichen SSH-Schlüssel in das SSH-Schlüsselfeld einfügst, überprüft Yokoy:
Ob der Schlüssel eine gültige Anzahl von Elementen enthält: Ein korrekt generierter öffentlicher SSH-Schlüssel besteht aus folgenden Teilen:
Schlüsseltyp: Gibt den Algorithmus an, der zur Generierung des Schlüsselpaars verwendet wurde, z. B. ssh-rsa für RSA-Schlüssel, ssh-dss für DSA-Schlüssel oder ecdsa-sha2-nistp256 für ECDSA-Schlüssel.
Schlüsseldaten: Dies sind die tatsächlichen Daten des öffentlichen Schlüssels. Es handelt sich in der Regel um eine lange Zeichenfolge, die zur Verschlüsselung oder Signaturprüfung verwendet wird.
Schlüsselkommentar (optional): Ein optionales Feld, in dem Du den Schlüssel mit zusätzlichen Informationen wie einer E-Mail-Adresse oder einer Beschreibung, wo der Schlüssel verwendet wird, versehen kannst.
Beispiel für einen öffentlichen Schlüssel
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC34FvmaZ5Rf4dY1BvQh0nWzG8n... user@example.com
ssh-rsasteht für den Schlüsseltyp.AAAAB3NzaC1yc2EAAAADAQABAAACAQC34FvmaZ5Rf4dY1BvQh0nWzG8n...sind die Schlüsseldaten.user@hostist der Schlüsselkommentar.
Ob der SSH-Schlüssel mit der richtigen Struktur beginnt: Ein SSH-Schlüssel muss mit der Verschlüsselungsmethode beginnen. Gängige Beispiele sind:
'ssh-ed25519', 'ssh-rsa', 'ssh-dss', 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384', 'ecdsa-sha2-nistp521'
Ob der SSH-Schlüssel eine Zeichenkette ist oder nicht: Ein SSH-Schlüssel muss eine Zeichenkette sein, andernfalls wird er nicht akzeptiert.
So richtest Du eine Authentifizierung mit einem SSH-Schlüssel ein:
Gehe zu Admin > Entwickler und wähle die Registerkarte STFP-Verbindungen.
Klicke auf + SFTP-Verbindung hinzufügen
Gib den SFTP-Benutzernamen ein. Der SFTP-Benutzername ist eine individuelle Referenz für das Kundenverzeichnis auf dem SFTP-Server. Du solltest einen Namen verwenden, der die Organisation identifiziert (z. B.
firma).Füge Deinen SSH-Schlüssel ein und stelle sicher, dass das Schlüsselformat und die Schlüsselstruktur bei keiner der durchgeführten Prüfungen durchfallen.
Klicke auf Einrichtung abschließen.
Die Erstellung des sicheren Verzeichnisses auf dem SFTP-Server dauert etwa 24 Stunden. Versuche in dieser Zeit nicht, auf den Yokoy-SFTP-Server zuzugreifen, um End-to-End-Tests durchzuführen, da die Verbindung abgelehnt wird.
Nach 24 Stunden verschwindet die Warnmeldung über den SFTP-Verbindungsdetails automatisch und zeigt Dir damit an, dass Du auf den Server zugreifen kannst.
Authentifizierung über Passwort
Obwohl empfohlen wird, SSH-Schlüssel zur Authentifizierung beim Yokoy-Server zu verwenden, kannst Du bei Bedarf auch eine Passwort-Authentifizierung einrichten.
✏️ Hinweis
Falls Du eine Passwort-Authentifizierung konfigurierst und sie später zur Authentifizierung per SSH-Schlüssel ändern willst, musst Du ein Support-Ticket eröffnen.
Um den Zugriff zu sichern, musst Du die IP-Adressen angeben, von denen aus ein Client auf den Server zugreifen kann.
Der SFTP-Benutzername muss ausschließlich aus Kleinbuchstaben bestehen und darf keine Großbuchstaben, Bindestriche oder Leerzeichen enthalten. Er muss individuell sein.
So richtest Du eine Authentifizierung über ein Passwort ein:
Gehe zu Admin > Entwickler und wähle die Registerkarte STFP-Verbindungen.
Klicke auf + SFTP-Verbindung hinzufügen und wähle + Anmeldung mit Passwort einrichten aus, um einen alternativen Autorisierungsmechanismus auszuwählen.
Gib den SFTP-Benutzernamen ein. Der SFTP-Benutzername ist eine individuelle Referenz für das Kundenverzeichnis auf dem SFTP-Server. Du solltest einen Namen verwenden, der die Organisation identifiziert (z. B.
firma).Füge eine oder mehrere IP-Adressen hinzu. Die IP-Adressen bestimmen, von welchen IPs aus auf den Yokoy SFTP-Server zugegriffen werden kann. Alle Verbindungen von IPs, die nicht auf der Zulassungsliste stehen, werden abgelehnt.
Klicke auf Passwort generieren, um das sichere Verzeichnis mithilfe des Passwort-Authentifizierungsmechanismus zu erstellen.
Yokoy generiert automatisch ein Passwort aus zufälligen Zeichen, das zur Authentifizierung auf dem Server verwendet werden kann. Du kannst das Passwort anzeigen und über die entsprechenden Symbole kopieren.
✏️ Hinweis
Kopiere das Passwort und bewahre es an einem sicheren Ort auf.
Die Erstellung des sicheren Verzeichnisses auf dem SFTP-Server dauert etwa 24 Stunden. Versuche nicht, auf den Yokoy SFTP-Server zuzugreifen, um End-to-End-Tests durchzuführen, da die Verbindung abgelehnt wird. Nach 24 Stunden verschwindet die Warnmeldung über den SFTP-Verbindungsdetails automatisch und zeigt an, dass Du auf den Server zugreifen kannst.
SFTP-Verbindungsdetails anzeigen
Du kannst die Details der SFTP-Verbindung einsehen, sobald sie erstellt wurde. Wenn Yokoy die SFTP-Verbindung für Deine Firma eingerichtet hat, kannst Du die Details hier einsehen.
Yokoy Rolle: Rolle von Yokoy in der Verbindung, entweder Server oder Host.
Bei SFTP-Verbindungen auf dem Server von Yokoy ist es Server. Ansonsten ist es Client.
Benutzername: Benutzername, den Anwendungen für den Zugriff auf das sichere Verzeichnis auf dem Yokoy-SFTP-Server verwenden.
Host-Name: Serveradresse (oder URL) des Servers. Yokoys SFTP-Einrichtung (exchange.yokoy.ai).
Port: Port, an dem der Server auf Client-Anfragen wartet. Standardmäßig wird Port 22 verwendet, da SFTP über das SSH-Protokoll läuft.
Art der Bescheinigung: Authentifizierungsmethode für den Zugriff auf die SFTP-Verbindung. Dies kann entweder ein Public-Key (SSH-Schlüsselauthentifizierung) oder ein Passwort (Passwortauthentifizierung) sein.
Public-Key: Für die SSH-Schlüsselauthentifizierung: öffentlicher SSH-Schlüssel, der dem Client auf dem SFTP-Server zugeordnet ist.
Erlaubte IP-Addressen: Für die Passwortauthentifizierung die IPs, die eine Verbindung zum sicheren Verzeichnis herstellen können. Wenn Du mehr als eine hast, wird Mehrere angezeigt. Klicke auf Mehrere, um eine vollständige Liste der IPs anzuzeigen.
✏️ Hinweis
Wenn Deine SFTP-Verbindung von Yokoy eingerichtet wurde, lautet der Hostname möglicherweise fe.yokoy.ai. In diesem Fall musst Du die IP-Adresse zur Zulassungsliste Deiner Firma hinzufügen: fe.yokoy.ai (34.65.67.218)
SFTP-SSH-Schlüssel bearbeiten
Du kannst den SSH-Schlüssel einer SFTP-Verbindung ändern, indem Du oben in den SFTP-Details auf Bearbeiten klickst.
Du kannst den neuen SSH-Schlüssel in das Feld SSH-Schlüssel eingeben. Klicke anschließend auf Speichern.
Es dauert 24 Stunden, bis die neuen Details aktualisiert werden. Daher musst Du möglicherweise warten, bevor Du erneut versuchst, Dich mit den neuen Details zu verbinden.
Erlaubte IP-Adressen bearbeiten und neues Passwort anfordern
Du kannst die Liste der genehmigten IPs hinzufügen oder ändern, indem Du oben in den SFTP-Details auf Bearbeiten klickst.
Es gibt zwei Möglichkeiten:
Hinzufügen/Ändern der zulässigen IP-Adressen: Damit kannst Du alle IPs hinzufügen oder entfernen, die für die Verbindung mit der SFTP-Einrichtung verwendet werden.
Neues Passwort für die Verbindung anfordern: Wenn Du das Passwort für den Zugriff auf Dein sicheres SFTP-Verzeichnis vergessen hast, kannst Du jederzeit ein neues anfordern, indem Du auf Neues Passwort anfordern klickst. Kopiere das neue Passwort und speichere es an einem sicheren Ort. Klicke auf Speichern, um Dein neues Passwort zu bestätigen.
Sichere Verzeichnisstruktur einrichten
Wenn die SFTP-Verbindung hergestellt wurde, kannst Du Dich mit Deinen Zugangsdaten mit dem Yokoy SFTP-Server verbinden und die Konfiguration für den Dateiaustausch einrichten.
✏️ Hinweis
Der SFTP-Server wird täglich um ca. 20:00:00 UTC (koordinierte Weltzeit)
neu aufgebaut. Dieser Vorgang dauert etwa 5 Minuten. In dieser Zeit ist es möglicherweise nicht möglich, eine Verbindung herzustellen.
Im Allgemeinen ist es immer ratsam, eine einheitliche Benennung und Struktur der Ordner beizubehalten:
to_yokoy: Ordner für Dateien, die importiert werden müssen oder an Yokoy gesendet werden.from_yokoy: Für den Fall, dass Du Finanzdaten als Teil einer dateibasierten Integration abrufst.Ein Unterordner pro Firma oder verwende eine Kennung der Firma im Dateinamen.
Bitte änder keine Verzeichnis- oder Dateisystemberechtigungen.
Während des täglichen Builds des SFTP-Servers wird ein Skript ausgeführt, das alle Berechtigungen zurücksetzt. Wenn Du Berechtigungen änderst, kann das dazu führen, dass Du für 20 Minuten keinen Zugriff auf den Server hast, während das Skript ausgeführt wird.