SSO und SCIM
Einrichtung der Anmeldung mit dem Firmenkonto (IdP) und der automatischen Benutzersynchronisierung in der richtigen Reihenfolge.
Verbinden Sie den IdP Ihres Unternehmens (Okta, Microsoft Entra ID, Google Workspace usw.) mit Keural. Mitarbeitende melden sich danach mit ihrem Firmenkonto an und treten bei der ersten Anmeldung automatisch der Organisation bei.
Die Spezifikation für IdP-Verantwortliche und Entwickler finden Sie unter SSO- und SCIM-Spezifikation.
Voraussetzungen
| Punkt | Grund |
|---|---|
| Das Inhaber-Konto der Organisation bei Keural | Nur Inhaber dürfen die SSO-Einstellungen ändern. |
| IdP-Administratorrechte | Sie müssen eine Keural-Anwendung im IdP anlegen. |
| DNS-Verwaltungsrechte für die Firmendomain | Die Inhaberschaft der Domain weisen Sie mit einem TXT-Eintrag nach. |
Unterstützte Verfahren
| Verfahren | Verwendung |
|---|---|
| OpenID Connect (OIDC) | Anmeldung mit dem Firmenkonto |
| SAML 2.0 | Anmeldung mit dem Firmenkonto. Authentifizierungsanfragen laufen über Redirect, Antworten werden per HTTP-POST empfangen. |
| SCIM 2.0 | Hinzufügungen und Deaktivierungen von Benutzern im IdP werden automatisch in den Keural-Konten übernommen |
Wählen Sie OIDC oder SAML. Unterstützt Ihr IdP beides, empfehlen wir OIDC, weil die Einrichtung einfacher ist.
Ablauf der Einrichtung
- Firmendomain verifizieren
- Anwendung im IdP anlegen
- Werte in Keural eintragen und speichern
- SSO aktivieren und Anmeldung testen
- SCIM verbinden (optional)
Alle Einstellungen befinden sich unter Organisationsverwaltung → SSO-Einstellungen.
1. Firmendomain verifizieren
Zuerst müssen Sie nachweisen, dass Ihnen die E-Mail-Domain gehört, die Sie für SSO verwenden möchten. Eine nicht verifizierte Domain kann in Schritt 3 nicht gespeichert werden.
Geben Sie unter Organisationsdomains die Domain Ihres Unternehmens (z. B. acme.com) ein und klicken Sie auf Domain hinzufügen.
Klicken Sie in der Zeile dieser Domain in der Liste auf Verifizieren. Das Fenster Domain verifizieren zeigt den Wert des TXT-Eintrags (keural-verify=…). Kopieren Sie diesen Wert.
Fügen Sie in der DNS-Verwaltung einen TXT-Eintrag für diese Domain hinzu und fügen Sie den kopierten Wert ein. Der Host (Name) ist die Domain selbst (meist @).
Kehren Sie zu Keural zurück und klicken Sie auf Verifizierung bestätigen. Erscheint in der Zeile Verifiziert, ist der Schritt abgeschlossen. Die DNS-Änderung kann einige Zeit brauchen. Schlägt die Prüfung fehl, warten Sie kurz und klicken erneut.
Haben Sie mehrere Firmendomains, fügen Sie jede hinzu und verifizieren sie. Öffentliche E-Mail-Domains wie gmail.com können nicht verwendet werden.
2. Anwendung im IdP anlegen
Wählen Sie oben in den SSO-Einstellungen unter Protokoll entweder OpenID Connect (OIDC) oder SAML 2.0. Der Bildschirm zeigt dann die Keural-Werte, die Sie im IdP eintragen müssen. Kopieren Sie sie in die Anwendung im IdP und notieren Sie die Werte, die der IdP Ihnen liefert.
| Richtung | Element | Details |
|---|---|---|
| Keural → IdP | Callback-URI | In die Redirect-URI Ihrer IdP-Anwendung eintragen. |
| IdP → Keural | Issuer-URL | Die Aussteller-Adresse Ihres IdP. |
| IdP → Keural | Client ID · Client Secret | Werte, die beim Anlegen der IdP-Anwendung ausgegeben werden. |
Die Anmeldung gelingt nur, wenn der IdP so eingestellt ist, dass er die E-Mail-Adresse des Benutzers übermittelt.
| IdP | Wo anlegen | Feld für die Callback-URI | Issuer-URL |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<Okta-Domain> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI (Web) | https://login.microsoftonline.com/<Mandanten-ID>/v2.0 |
| Google Workspace | Google-Cloud-Konsole → APIs & Dienste → Anmeldedaten → OAuth-Client-ID (Webanwendung) | Autorisierte Redirect-URIs | https://accounts.google.com |
- Microsoft Entra ID: Das Client Secret ist der Value eines unter Certificates & secrets neu erstellten Geheimnisses. Fügen Sie unter Token configuration den optionalen Claim
emailzum ID-Token hinzu. - Okta: Legen Sie unter Assignments der Anwendung fest, welche Benutzer oder Gruppen Keural verwenden dürfen.
3. Werte in Keural eintragen und speichern
- Tragen Sie die IdP-Werte aus Schritt 2 ein.
- Tragen Sie unter E-Mail-Domains die in Schritt 1 verifizierten Domains durch Kommas getrennt ein. Meldet sich jemand mit einer E-Mail-Adresse dieser Domains an, wird er zur Anmeldeseite des Unternehmens weitergeleitet.
- Legen Sie fest, ob Sie Benutzer beim ersten Login automatisch anlegen (JIT) aktivieren. Ist die Option aktiv, erhalten Mitarbeitende ohne Keural-Konto beim ersten SSO-Login automatisch ein Konto. Ist sie deaktiviert, können sich nur Personen mit bestehendem Konto anmelden.
- Klicken Sie auf Speichern.
Stellt der IdP bei OIDC die Standardadressen (Discovery) nicht bereit, tragen Sie die Endpoints unter Erweiterte Einstellungen anzeigen manuell ein. Bei den meisten IdPs lassen Sie die Felder leer.
4. SSO aktivieren und Anmeldung testen
- Aktivieren Sie SSO aktivieren und klicken Sie auf Speichern.
- Klicken Sie auf Anmeldung testen. Die Anmeldeseite des Unternehmens öffnet sich in einem neuen Fenster.
- Melden Sie sich mit Ihrem Firmenkonto an und kehren Sie zu Keural zurück. Kommen Sie bei Keural an, ist die Verbindung hergestellt.
Der Anmeldetest funktioniert nur, wenn SSO aktiviert ist. Bei Problemen deaktivieren Sie SSO aktivieren und speichern. Bis dahin melden sich Mitarbeitende dieser Domain per E-Mail-Link an.
Anmeldung für Mitarbeitende
- Geben Sie auf der Keural-Anmeldeseite Ihre Firmen-E-Mail-Adresse ein; Sie werden zur Anmeldeseite des Unternehmens weitergeleitet. Nach der Anmeldung kehren Sie zu Keural zurück.
- In der Desktop-App melden Sie sich per E-Mail-Link statt über die Unternehmensseite an.
- Mitarbeitende, die sich zum ersten Mal per SSO anmelden, treten der Organisation als Mitglieder bei. Administratorrollen weisen Sie separat unter Organisationsverwaltung zu.
In den folgenden Fällen funktioniert die Anmeldung, die Person wird aber nicht automatisch der Organisation hinzugefügt:
- Alle von der Organisation gekauften Plätze sind belegt
- Das Konto gehört bereits einer anderen Organisation an
5. SCIM verbinden (optional)
Mit SCIM werden Benutzer, die Sie im IdP hinzufügen oder deaktivieren, sofort in den Keural-Konten übernommen. Richten Sie SCIM ein, nachdem die SSO-Verbindung abgeschlossen ist.
Aktivieren Sie unter SCIM-Provisioning die Option SCIM-Provisioning aktivieren.
Klicken Sie auf Token ausstellen und kopieren Sie das Token. Es wird nur einmal angezeigt.
Tragen Sie die SCIM-Basis-URL (Tenant-URL) und das Token in den Provisioning-Einstellungen Ihres IdP ein. Die Authentifizierung erfolgt per Bearer-Token.
| IdP | Wo eintragen |
|---|---|
| Okta | Application → Provisioning → SCIM connector base URL; Authentication Mode auf HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
Was Sie im IdP tun, wird in Keural so übernommen:
| Im IdP | In Keural |
|---|---|
| Benutzer zuweisen | Legt ein Konto an und fügt es der Organisation hinzu. Der Benutzername ist die E-Mail-Adresse. |
| Benutzer deaktivieren oder Zuweisung entfernen | Sperrt das Konto und blockiert die Anmeldung. Die Daten werden nicht gelöscht. |
| Wieder aktivieren | Hebt die Sperre auf. |
| Zur Gruppe Keural Admins hinzufügen oder daraus entfernen | Befördert den Benutzer zum Administrator oder stuft ihn zum Mitglied herab. Der Inhaber ändert sich nicht. |
Haben Sie das Token verloren, klicken Sie auf Token neu ausstellen. Das bisherige Token wird sofort ungültig, tragen Sie daher das neue Token im IdP ein.
Fehlerbehebung
| Symptom | Maßnahme |
|---|---|
| Die E-Mail-Domains werden nicht gespeichert | Ob die Domainverifizierung aus Schritt 1 abgeschlossen ist und die Domain keine öffentliche E-Mail-Domain ist. |
| Die Domainverifizierung schlägt fehl | Ob der TXT-Wert vollständig ab keural-verify= eingetragen ist. Warten Sie, bis sich der DNS-Eintrag verbreitet hat, und klicken Sie erneut. |
| Nach Klick auf Anmeldung testen öffnet sich die Unternehmensseite nicht | Ob SSO aktivieren eingeschaltet und gespeichert ist. |
| Nach der Anmeldung im Unternehmen landen Sie wieder auf der Keural-Anmeldeseite | Bei OIDC: Callback-URI, Issuer-URL, Client Secret und E-Mail-Claim. Bei SAML: SP-EntityID, ACS-URL, Zertifikat und E-Mail-Attribut. |
| Die Anmeldung wird abgelehnt, weil kein Konto existiert | Benutzer beim ersten Login automatisch anlegen (JIT) ist deaktiviert. Aktivieren Sie es oder laden Sie den Mitarbeitenden vorher ein. |
| Die Anmeldung klappt, aber der Arbeitsbereich der Organisation erscheint nicht | Ob noch Plätze frei sind und ob das Konto nicht zu einer anderen Organisation gehört. |
| Beim Öffnen der App über das IdP-Portal schlägt die Anmeldung fehl (SAML) | Starten Sie auf der Keural-Anmeldeseite mit Ihrer Firmen-E-Mail-Adresse. |
| Der SCIM-Verbindungstest schlägt fehl | Tragen Sie Base URL und Token erneut ein. Haben Sie das Token neu ausgestellt, ersetzen Sie es durch das neue. |