🌐 Web | 👤 Organisations-Admin
Um Yokoy mit Microsoft Entra ID (ehemals Azure Active Directory) unter Verwendung von SAML 2.0 zu konfigurieren, musst Du sowohl Yokoy als auch die Microsoft Entra ID-App einrichten.
Einige Schritte erfordern Maßnahmen in beiden Systemen. Yokoy ist eine zertifizierte Entra ID-App, was den Konfigurationsprozess erleichtert. Weitere Details und Informationen findest Du unter Microsoft Entra SSO-Integration mit Yokoy – Microsoft Entra ID.
Um SSO einzurichten und Usern die Anmeldung bei Yokoy über ihre Entra ID zu ermöglichen:
Passwortauthentifizierung deaktivieren (optional)
Domain(s) und Authentifizierungsprotokoll einrichten
Du musst von Microsoft genutzte SAML 2.0-Protokoll in Yokoy einrichten.
Gehe dafür zu Admin > Organisation, Tab Authentifizierung.
🚧 Vorsicht
Stelle sicher, dass die Funktion Authentifizierung für Deine Organisation aktiviert wurde. Andernfalls ist dieser Tab nicht sichtbar.
Um eine spezifische Domain für Dein Unternehmen hinzuzufügen, musst Du das Format yourcompany.com verwenden. Klicke auf Speichern, um die Domain zu speichern. Du kannst Deiner Organisation mehrere Domains hinzufügen.
Du kannst mehrere Domains hinzufügen – z. B. für verschiedene Länder oder Niederlassungen Deines Unternehmens (z. B. company.it, company.ch, company.de).
Sobald Du alle Domains hinzugefügt hast, kannst Du die gewünschte Authentifizierungsmethode festlegen. Klicke auf Anbieter hinzufügen und wähle das SAML-Protokoll aus.
SP Entity ID und ACS-URL kopieren
Nach der Auswahl von SAML werden folgende Informationen angezeigt:
SP entity ID
ACS URL
Klicke auf das Kopiersymbol neben dem Feld, um die URLs zu kopieren. So kannst Du MS Entra ID konfigurieren, um mit Yokoy zu kommunizieren, falls Du keinen Zugriff auf Microsoft Entra ID hast.
✏️ Hinweis
Wenn Du einen Identity-Provider-initiierten Flow einrichten möchtest,
musst Du Dich direkt an den Yokoy Support wenden, um es zu konfigurieren.
Yokoy als neue SAML-Applikation hinzufügen
Öffne in Microsoft Entra Enterprise Applications und klicke auf + New application (Neue Anwendung). Gebe Yokoy in die Suchleiste ein und wähle Yokoy aus.
Klicke auf Create (Erstellen), um die Applikation zu Deiner Microsoft Entra Gallery hinzuzufügen.
SAML SSO konfigurieren
Wähle Set up single sign on (Single sign-on konfigurieren) in der Applikations-Übersicht von Single sign-on aus wähle SAML als die einzige sign-on-Methode aus.
Hinzufügen von SP entity ID und ACS URL
Füge die durch Yokoy bereitgestellte SP entity ID in dem Identifier-Feld (Entity ID) und die ACS URL in das Reply URL-Feld (Assertion Consumer Service URL) ein.
Gebe nun die URL für die jeweilige Umgebung für die sign-on-URL ein:
Umgebung | URL |
Production | |
Sandbox |
Klicke auf Save (Speichern), um die Konfiguration zu speichern.
Die voreingestellten Werte bei den User Attributes Claims (Benutzerattribute und -ansprüche) können übernommen oder bei Bedarf angepasst werden.
IdP-Metadata herunterladen
Lade das SAML-Signaturzertifikat als Metadata-XML herunter (Federation Metadata XML). Du benötigst diese Datei, um das OX509-Zertifikat und die SSO-URL mit OPOST-Binding zu ermitteln.
Diese Informationen findest Du innerhalb der Metadata-XML-Datei. Suche nach dem Tag <IDPSSODescriptor>, um so die benötigten Details zu finden.
💡 Tipp
Du kannst jeden Browser verwenden, um die XML-Metadaten-Datei zu öffnen und die jeweiligen Teile der Datei auszuwählen, die Du benötigst.
🚧 Vorsicht
Beim Implementieren von Microsoft Entra ID mit SAML ist es wichtig, Folgendes zu überprüfen:
○X509-Zertifikat: Die für Test- und Produktionsumgebungen generierten Zertifikate sollten unterschiedlich sein.
○POST-Binding SSO-URL: Sie sollte mit
saml2enden und nicht mitwsfed.
Wenn sie mitwsfedendet, wurde SAML nicht korrekt eingerichtet.
○X509-Zertifikat und die ○POST binding SSO URL hinzufügen
Füge das ○X509-Zertifikat in das Feld Zertifikat und die ○POST-Binding SSO-URL in das Feld IdP-Login-URL ein.
Stelle beim Einfügen des Zertifikats sicher, dass:
Nur der Text ab der tatsächlichen Zeichenkette eingefügt wird.
Keine XML-Tags (z. B. </ds:X509Certificate>) enthalten sind.
Keine line breaks (Zeilenumbrüche) vorhanden sind.
✏️ Hinweis
Die SSO-URLs erfordern keine Authentifizierung und Du wirst sofort sehen, ob sie gültig sind, indem Du sie in einem Browser öffnest. Das kann dabei helfen, Probleme durch eine fehlerhafte Konfiguration zu vermeiden.
Button-Label für den SSO-Anmeldebutton hinzufügen
Du kannst einen Text hinzufügen, der im Button angezeigt wird, den der End user sieht. Dieser Text wird mit der Schaltflächen-Beschriftung Login mit kombiniert. Wenn Du bspw. in diesem Feld Microsoft Entra eingibst, wird der Button mit Login mit Microsoft Entra angezeigt.
SSO-Konfiguration testen
Sobald die Konfiguration abgeschlossen ist, fahre mit dem Testen fort.
Gebe auf der Haupt-Login-Seite von Yokoy eine Test-E-Mail-Adresse ein und klicke auf Weiter. Sobald Yokoy eine E-Mail-Adresse mit der Domain Deines Unternehmens erkennt, wird die SSO-Option angezeigt. Beispiel: Ein zusätzlicher Button erscheint über dem Passwortfeld, z. B. Login mit Microsoft Entra (SAML).
Richte einen Testbenutzer ein, mit dem Du den vollständigen Ablauf testen kannst, um sicherzustellen, dass SSO korrekt konfiguriert ist. Der Test kann das Klicken auf den SSO-Button beinhalten. So lässt sich prüfen, ob die Anwendung korrekt eingerichtet wurde. Bei einer fehlerhaften Konfiguration kann ggf. ein Microsoft Entra ID-Fehler angezeigt werden.
💡 Tipp
Falls der Button nicht angezeigt wird, überprüfe die folgenden Dinge:
Umgebung: Stelle sicher, dass Du die richtige Umgebung (Sandbox/Production) konfiguriert hast.
Domain: Überprüfe, dass die E-Mail-Domain korrekt geschrieben ist und mit der konfigurierten Domain übereinstimmt.
Passwortauthentifizierung deaktivieren
Sobald Du überprüft hast, dass SSO korrekt eingerichtet ist und sich Benutzer über SSO anmelden können, kann die Passwortauthentifizierung für die Organisation deaktiviert werden, um Anmeldeprobleme zu vermeiden. Obwohl dieser Schritt empfohlen wird, kannst Du wahlweise beide Authentifizierungsmethoden zulassen.
Gehe dazu zu Admin > Organisation, Tab Authentifizierung, und deaktiviere den Schalter Passwort einschalten.
