Single Sign-on (SSO) mit SAML 2.0 ermöglicht es deinen Nutzer:innen, sich mit ihrem bestehenden Identity Provider (IdP) bei deskbird anzumelden. Unten findest du Schnellstart-Optionen für Okta und Keycloak sowie eine vollständige Anleitung zur Föderationseinrichtung (SP-initiiertes SSO).
- SAML mit Okta
- SAML mit Keycloak
- Einrichtung der SAML 2.0 Föderation
- SAML-Zertifikat erneuern
- Wann SAML statt OAuth / OIDC nutzen?
1. SAML mit Okta
Nutze unsere spezielle Okta-Anleitung, um eine Okta SAML-App zu konfigurieren, die benötigten Attribute zuzuordnen und das SP-initiierte SSO zu deskbird zu testen. Die Anleitung enthält Screenshots, Attribut-Statements und Tipps zur Fehlerbehebung.
👉 Schritt für Schritt: SAML SSO mit Okta einrichten
2. SAML mit Keycloak
Du nutzt lieber Keycloak? Folge der Keycloak-Anleitung, um SSO zu deskbird zu starten.
👉 Schritt für Schritt: SAML SSO mit Keycloak einrichten
3. Einrichtung der SAML 2.0 Föderation
SAML 2.0 (Security Assertion Markup Language) ist ein XML-basiertes Protokoll, um Authentifizierungs- und Autorisierungsdaten sicher zwischen einem Identity Provider (IdP) und einem Service Provider (SP) auszutauschen. deskbird unterstützt SP-initiiertes SSO (die Authentifizierung muss von deskbird aus gestartet werden).
Wenn du eine Kachel im IAM-Launcher (z. B. OneLogin, JumpCloud) möchtest, auf die Nutzer:innen klicken können, füge eine Bookmark-Anwendung hinzu, die den SP-initiierten Flow in deskbird startet:https://app.deskbird.com/saml?providerName={saml-provider-ID}
Die SAML-Provider-ID folgt dem Muster saml.{firmenname}. Beispiel für "Polaroid": https://app.deskbird.com/saml?providerName=saml.polaroid.
Lege eine separate, versteckte Föderationsanwendung in deinem IdP für die eigentliche SAML-Verbindung an (nicht für Nutzer:innen sichtbar).
3.1 Allgemeine Einrichtung
Konfiguriere deinen IdP mit folgenden deskbird Service Provider-Details:
| Service Provider ID (Entity ID) | https://api.deskbird.app/saml/metadata |
| ACS URL (Callback) | https://app.deskbird.com/__/auth/handler |
💡 Für eine erfolgreiche SAML 2.0-Authentifizierung setze NameID auf die E-Mail-Adresse des Nutzers mit dem Format urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
Beispiel für ein Assertion-Snippet
<saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="<IdP Entity ID>" SPNameQualifier="https://api.deskbird.app/saml/metadata" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> email </saml2:NameID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> </saml2:Subject> Diese Infos an deskbird zur Konfiguration senden
| IdP Entity ID | |
| IdP SSO URL | |
| IdP-Zertifikat | Muss mit -----BEGIN CERTIFICATE----- beginnen und mit -----END CERTIFICATE----- enden (ohne zusätzliche Zeichen/Zeilenumbrüche einfügen). |
Wenn du eine Metadata-Datei deines IdP hast, kannst du diese stattdessen einfach schicken.
3.2 Nutzerattribute
Benötigtes Attribut (genau so benennen):
| Attribut | Beschreibung |
| UPN-E-Mail-Adresse für Login, Benachrichtigungen und Buchungsinfos |
Empfohlene Attribute:
| Attribut | Beschreibung |
| first_name | Vorname des Nutzers (wird in der Plattform angezeigt). Microsoft Entra IDs Standard-Claim givenname funktioniert auch. |
| last_name | Nachname des Nutzers (wird in der Plattform angezeigt). Microsoft Entra IDs Standard-Claim surname funktioniert auch. |
| avatar_url | URL zum Profilbild; Initialen werden genutzt, falls nicht angegeben |
| external_id | IdP-Benutzer-ID zum Abgleich |
| manager_id | IdP-ID des Vorgesetzten (für Freigaben) |
| locale | Bevorzugte Sprache des Nutzers (Standard ist die Unternehmenssprache, falls nicht angegeben) |
| job_title | Berufsbezeichnung des Nutzers |
| company_entity | Juristische Einheit des Nutzers (Standard ist die Unternehmenseinheit, falls nicht angegeben) |
3.3 Namensabgleich mit deinem IdP
Wenn Nutzer:innen beim ersten SAML-Login erstellt werden (kein SCIM- oder HRIS-Abgleich), übernimmt deskbird Vor- und Nachname aus deinem IdP und hält diese synchron:
- Erster Login: Der Nutzer wird mit Vor- und Nachname aus der SAML-Assertion angelegt.
- Weitere Logins: Sendet dein IdP einen anderen Namen, aktualisiert deskbird diesen. Auch manuell in deskbird geänderte Namen werden überschrieben.
- Bearbeitung: Solange der Name vom IdP kommt, können Nutzer:innen und Admins ihn in deskbird (Web, iOS und Android) nicht bearbeiten. Namensänderungen müssen im IdP erfolgen und erscheinen nach dem nächsten Login.
- SCIM- oder HRIS-Abgleich: Wird einer davon genutzt, steuert dieser die Namen und SAML überschreibt sie nie.
- Kein Name gesendet: Enthält die Assertion keinen Vor- und Nachnamen, geben Nutzer:innen ihren Namen beim Setup ein und können ihn weiterhin bearbeiten.
💡 Es werden nur Vor- und Nachname synchronisiert. Andere Attribute wie Büro oder Abteilung werden nicht aus SAML übernommen.
3.4 Metadata-Datei
Nachdem du die SAML-Anwendung in deinem IdP erstellt hast, sende uns bitte die Metadata-Datei, die Folgendes enthält:
- Zertifikat
- Entity ID
- SSO-URL
4. SAML-Zertifikat erneuern
SAML-Zertifikate haben ein Ablaufdatum (meist 1–3 Jahre nach Erstellung). Wenn ein Zertifikat bald abläuft, informiert dich dein Identity Provider. Es ist wichtig, das Zertifikat rechtzeitig zu erneuern, um Login-Ausfälle zu vermeiden.
Starte den Erneuerungsprozess mindestens 2–3 Wochen vor Ablauf, damit genug Zeit für die Abstimmung bleibt.
Schritt-für-Schritt-Anleitung zur Erneuerung (Microsoft Entra ID):
- Gehe im Microsoft Entra ID-Portal zu deiner deskbird Enterprise-Anwendung.
- Navigiere zu Single sign-on > SAML Certificates.
- Klicke auf das Bearbeiten (Stift)-Symbol.
- Klicke auf Neues Zertifikat.
- Lege das Ablaufdatum fest (Standard: 3 Jahre).
- Klicke auf Speichern. Das neue Zertifikat erscheint mit dem Status Inaktiv.
- Lade das neue Zertifikat herunter (Base64-Format).
- Sende das Zertifikat an den deskbird Support per Support-Ticket. Gib deinen Firmennamen an und erwähne, dass es sich um eine SAML-Zertifikatserneuerung handelt.
- Der deskbird Support ersetzt das Zertifikat auf unserer Seite und bestätigt, wenn alles bereit ist.
- Sobald deskbird bestätigt, gehe zurück zu Entra ID und aktiviere das neue Zertifikat (Status auf Aktiv setzen).
Downtime
In der Regel gibt es während des Zertifikatswechsels keine Ausfallzeit, solange du die Aktivierung mit dem deskbird Support abstimmst. Das alte Zertifikat funktioniert weiter, bis du auf das neue umstellst.
5. Wann SAML statt OAuth / OIDC nutzen?
Wenn du dich zwischen SAML und OAuth (Microsoft SSO) entscheiden möchtest, beachte Folgendes:
| Funktion | SAML 2.0 | OAuth / Microsoft SSO / Google SSO |
|---|---|---|
| Zertifikatsverwaltung | Erfordert regelmäßige Erneuerung | Keine Zertifikatsverwaltung nötig |
| Nutzererlebnis | Nutzer:innen klicken auf "Mit Unternehmenskonto (SSO) anmelden" im Login-Bildschirm | Nutzer:innen klicken auf "Mit Microsoft anmelden" im Login-Bildschirm |
| IdP-Flexibilität | Funktioniert mit jedem SAML 2.0 IdP (Okta, Keycloak, ADFS, etc.) | Nur Microsoft und Google |
| Plan-Anforderung | User and Data Management Plus | In allen Plänen verfügbar |