Setzt voraus, dass OIDC clients für dein Unternehmen aktiviert sind.
Ein OIDC client ist eine externe App oder ein Dienst, den du berechtigst, Flip als Identity Provider zu nutzen. Die Anmeldung an dieser App erfolgt mit den Flip-Zugangsdaten, ohne separaten Login. Du erstellst und verwaltest diese Clients selbst in der Admin Console und kannst so eine neue Verbindung aktivieren oder eine bestehende anpassen, ohne den Support zu kontaktieren.
Häufige Anwendungsfälle:
- Single Sign-on aus Flip in eine Drittanbieter- oder eigene Webanwendung anbieten.
- Den Login für eine App ermöglichen, die du mit dem Mini App Builder erstellt hast.
Bevor du beginnst
- Du brauchst die Rolle System Admin. Nur System Admins können OIDC clients sehen oder verwalten.
- Lege eine Client ID für den Client fest (Namensregeln siehe Erstellungsschritt).
- Halte die Redirect URI deiner Anwendung bereit (die URL, zu der Flip nach der Anmeldung zurückleitet). Du kannst mehrere angeben.
- Entscheide, ob du einen Public- oder Confidential-Client brauchst (siehe nächster Abschnitt).
Public- vs. Confidential-Clients
Wähle den Typ danach, ob deine Anwendung ein Secret sicher speichern kann.
| Typ | Authentifizierung | Wofür |
|---|---|---|
| Public | PKCE, kein Secret | Single-Page-Apps, mobile Apps und die meisten browserbasierten Apps, die kein Secret sicher speichern können. Der empfohlene Standard. |
| Confidential | Ein Client Secret | Serverseitige Anwendungen, die ein Secret sicher speichern können. |
Wenn du unsicher bist, beginne mit einem Public-Client.
Einen OIDC client erstellen
- Gehe zu Access & security → OIDC clients und wähle + Create OIDC client.
- Gib eine Client ID ein. Verwende Kleinbuchstaben, Ziffern und einzelne Bindestriche zwischen Segmenten, 3 bis 32 Zeichen (z. B.
my-oidc-client). Sie identifiziert den Client gegenüber Flip und deiner Anwendung. - Aktiviere Confidential, wenn deine App serverseitig läuft und ein Secret speichern kann. Ein Secret wird automatisch erzeugt und du kannst es nach dem Erstellen kopieren. Lass die Option aus für einen Public-Client, der stattdessen PKCE nutzt.
- Lass PKCE aktiviert (empfohlen). Es erfordert PKCE (S256) im Authorization-Code-Flow für höhere Sicherheit. Deaktiviere es nur, wenn die verbundene Anwendung PKCE nicht unterstützt.
- Lass Flip API access deaktiviert, außer die App muss im Namen des angemeldeten Nutzers in Flip handeln (lies den Abschnitt unten, bevor du das aktivierst).
- Optional: Client name, Description und SSO domain. Setze die SSO domain nur, wenn dein Unternehmen Flip auf mehr als einer Domain nutzt, um zu steuern, an welche Domain diese Integration ihren Login leitet.
- Wähle die Access token lifespan. Nutze einen der vorgegebenen Werte oder wähle Custom für einen eigenen Wert zwischen 5 Minuten und 24 Stunden. Eine kürzere Lifespan verkleinert das Zeitfenster, in dem ein abgeflossenes Token nutzbar ist.
- Wähle unter Redirect URIs die Option + Add URI und füge jede URL hinzu, zu der Flip nach der Anmeldung zurückleiten darf (Regeln siehe unten).
- Optional: Logout URIs (wohin Nutzer nach dem Abmelden geleitet werden). Bleibt das Feld leer, werden die Redirect URIs verwendet.
- Wähle Create OIDC client.
Es hat funktioniert, wenn der neue Client in der Liste der OIDC clients erscheint. Öffne ihn, um die Verbindungsdaten (OIDC Discovery URL und bei Confidential-Clients das Secret) in die Konfiguration deiner Anwendung zu übernehmen.
Regeln für Redirect URIs
- Bevorzuge exakte
https://-URLs und halte sie so eng wie möglich. - Abschließende
*-Wildcards werden unterstützt. - Jede URI muss über alle deine OIDC- und SAML-Clients hinweg eindeutig sein.
- Wird der Client in Flip-Menüpunkten verwendet, muss die Menüpunkt-URL zu einer der Redirect URIs passen, damit die automatische Login-Weitergabe zuverlässig funktioniert.
Einem Client Zugriff auf Flip APIs geben
Standardmäßig kann ein OIDC client nur die Anmeldung durchführen. Wenn du Flip API access aktivierst, erhält der Client die vollen Berechtigungen des angemeldeten Nutzers und kann in seinem Namen in der Flip App handeln.
Aktiviere das nur, wenn die Anwendung wirklich Flip APIs im Namen des Nutzers aufrufen muss. Bleibt es deaktiviert, ist der Client auf die Anmeldung beschränkt, was die sicherere Einstellung ist. Die Liste der OIDC clients zeigt pro Client an, ob API access Active oder Inactive ist.
Verbindungsdaten des Clients finden
Öffne einen Client, um die Daten zu sehen, die deine Anwendung braucht:
- Die OIDC Discovery URL (z. B.
https://deine-flip-domain/auth/realms/flip/.well-known/openid-configuration). Nutze Copy, um sie zu kopieren. Über diese eine URL findet deine App alle nötigen OIDC-Endpunkte (Authorization, Token und User Info). - Die Client ID, die du beim Erstellen festgelegt hast.
- Bei Confidential-Clients das OIDC secret.
Entwickler, die den Flip-Login in eine eigene App integrieren, finden den vollständigen Entwicklungs-Guide unter getflip.dev.
Das Secret eines Confidential-Clients verwalten
Confidential-Clients haben zusätzlich zur Client ID ein OIDC secret. In der Detailansicht des Clients unter OIDC secret:
- Secret kopieren (Copy) und in die Konfiguration deiner Anwendung übernehmen. Behandle es wie ein Passwort.
- Rotate secret value, wenn du es ersetzen musst, z. B. wenn es möglicherweise offengelegt wurde.
Das Rotieren unterbricht bestehende Integrationen. Alle Integrationen, die noch das aktuelle Secret nutzen, können keine neuen Access Tokens mehr beziehen. Aktualisiere deine Anwendung sofort nach dem Rotieren mit dem neuen Secret.
Client bearbeiten oder löschen
- Bearbeiten (Edit): Öffne den Client (oder wähle Edit in der Liste), ändere Name, Description, Redirect URIs oder Einstellungen und speichere.
- Löschen: Das Entfernen eines Clients verhindert sofort, dass er Nutzer anmelden kann. Stelle sicher, dass keine aktive Anwendung mehr davon abhängt, bevor du löschst.
Fehlerbehebung
-
Anmeldung schlägt mit Redirect-URI-Fehler fehl: Die von deiner App gesendete URL passt zu keiner Redirect URI des Clients. Füge die exakte URL hinzu oder nutze eine abschließende
*-Wildcard und achte darauf, dass sie über deine OIDC- und SAML-Clients hinweg eindeutig ist. - Anmeldung schlägt fehl und die App unterstützt kein PKCE: Prüfe, ob die App PKCE unterstützt. Wenn nicht, deaktiviere PKCE am Client.
- API-Aufrufe werden abgelehnt: Prüfe, ob Flip API access am Client auf Active steht.
- Anmeldung funktioniert nach dem Rotieren des Secrets nicht mehr: Die App nutzt noch das alte Secret. Aktualisiere sie mit dem aktuellen Secret aus der Detailansicht.
- Anmeldung wird auf die falsche Domain geleitet: Wenn dein Unternehmen Flip auf mehr als einer Domain nutzt, setze die SSO domain des Clients.