Worum es geht
CIAS schickt Mails an Personen, wenn im Leben eines Kontos etwas passiert: eine Registrierung beginnt, wartet auf eine Freigabe, ist fertig, oder ein Administrator schickt einen Link zum Passwort-Setzen. Jede Mail hat einen festen Schlüssel, etwa VERIFY_EMAIL. Über diesen Schlüssel findet CIAS die Vorlage, also den Text mit Platzhaltern.
Mails, die Keycloak selbst verschickt, etwa „Passwort vergessen“, gehören nicht dazu. Die gestaltet, wer den Realm betreibt, im Keycloak-Theme.
Alle Mails auf einen Blick
| Schlüssel | Anlass | Link in der Mail | Betreff (deutsche Vorlage) |
|---|---|---|---|
VERIFY_EMAIL | eine Registrierung für eine neue Adresse beginnt | verificationUrl, bestätigt die Adresse | Bitte bestätigen Sie Ihre E-Mail-Adresse |
MEMBERSHIP_INVITATION | ein bestehendes Konto soll einem Mandanten beitreten | verificationUrl, bestätigt den Beitritt | Sie wurden zu einem Bereich eingeladen |
INVITATION | Vorlage für eine Einladung, bei der die Person ihre Angaben selbst vervollständigt | verificationUrl | Einladung: Bitte vervollständigen Sie Ihre Angaben |
ALREADY_REGISTERED | jemand registriert eine Adresse, die schon ein Konto hat, und es gibt keinen Mandanten zum Beitreten | loginUrl, zur Anmeldung | Zu dieser Adresse besteht bereits ein Konto |
APPROVAL_PENDING | die Adresse ist bestätigt, jetzt muss ein Administrator freigeben | keiner | Ihre Registrierung wird geprüft |
REJECTED | ein Administrator hat die Registrierung abgelehnt | keiner, auf Wunsch mit Begründung reason | Ihre Registrierung wurde abgelehnt |
WELCOME | die Registrierung ist fertig, das Konto ist eingerichtet | passwordUrl bei neuem Konto, sonst loginUrl | Willkommen |
PASSWORD_SETUP | ein Administrator schickt einen Link zum Passwort-Setzen | passwordUrl | Passwort für Ihr Konto festlegen |
SWITCH_CONSENT_REQUESTED | jemand bittet darum, in deinem Namen arbeiten zu dürfen | consentUrl, falls eingestellt | {Name} bittet um Zugriff auf Ihr Konto |
SWITCH_CONSENT_USED | eine Freigabe für einen Benutzerwechsel wird zum ersten Mal genutzt | consentUrl, falls eingestellt | {Name} nutzt jetzt Ihre Freigabe |
Die Mails einer Registrierung
-
1CIAS→E-MailAnfrage angenommen:
VERIFY_EMAIL(neue Adresse),MEMBERSHIP_INVITATION(bestehendes Konto, Mandant zum Beitreten) oderALREADY_REGISTERED(bestehendes Konto, kein Mandant) -
2Benutzer→CIASklickt den Link
-
3CIASMuss ein Administrator freigeben?
-
4CIAS→E-Mailja:
APPROVAL_PENDING. Später bei AblehnungREJECTED -
5CIAS→E-Mailnach der Bereitstellung:
WELCOMEErgebnis: Konto fertig, die Person bekommt den Link zum Passwort-Setzen oder zur Anmeldung
Warum bekommt ein bestehendes Konto ohne Mandant ALREADY_REGISTERED statt einer Fehlermeldung? Die Antwort an die registrierende Seite ist in beiden Fällen gleich. So lässt sich von außen nicht herausfinden, welche Adressen schon ein Konto haben. Nur die Mail an die Adresse selbst sagt es. Siehe Die E-Mail ist das Konto.
Die Ausprägungen
Wann: Selbstregistrierung, Anlage durch einen Administrator oder Einladung einer neuen Adresse.
Der Link bestätigt die Adresse. Erst danach wird das Konto freigeschaltet. Wie lange der Link gilt, legt der Ablauf fest, siehe E-Mail bestätigen.
Ergebnis: Link verificationUrl
Wann: Die Adresse hat schon ein Konto, und die Registrierung nennt einen Mandanten.
Die Person bestätigt, dass sie beitreten will. Ein neues Konto entsteht nicht.
Ergebnis: Link verificationUrl
Wann: Eine Installation will eine Einladung anders formulieren.
CIAS liefert die Vorlage mit, und Mandanten-Administratoren dürfen sie im eigenständigen CIAS bearbeiten. Eine Einladung an eine neue Adresse verschickt der Registrierungsablauf als VERIFY_EMAIL, mit dem Ablauf als Variante, siehe Wie die passende Vorlage gefunden wird.
Ergebnis: Link verificationUrl
Wann: Die Adresse hat schon ein Konto, und es gibt keinen Mandanten zum Beitreten.
Die Mail sagt, dass es das Konto schon gibt, und bietet die Anmeldung an.
Ergebnis: Link loginUrl
Wann: Der Ablauf verlangt eine Freigabe, die Adresse ist bestätigt.
Die Person weiß damit, dass sie nichts mehr tun muss. Siehe Freigabe durch einen Administrator.
Ergebnis: kein Link
Wann: Ein Administrator lehnt die Registrierung ab.
Gibt der Administrator einen Grund an, steht er in der Mail. Ohne Grund entfällt der Absatz.
Ergebnis: kein Link, optional reason
Wann: Die Bereitstellung ist fertig.
Bei einem neuen Konto enthält sie, wenn die Installation das eingerichtet hat, einen Link zum Passwort-Setzen. Sonst verweist sie auf die Anmeldung und auf „Passwort vergessen“. Scheitert nur diese Mail, ist die Registrierung trotzdem fertig.
Ergebnis: passwordUrl oder loginUrl
Wann: Ein Administrator schickt einer Person einen neuen Link zum Passwort-Setzen.
Nur wenn die Installation Passwort-Links eingerichtet hat. Siehe Passwort-Setz-Link erneut schicken.
Ergebnis: Link passwordUrl
Wann: Jemand mit der Rolle allowed-user-context-switch bittet eine Person um Freigabe.
Die Mail nennt, wer fragt, mit wessen Rechten, bis wann und warum. Ein zweiter gleicher Antrag schickt keine zweite Mail. Scheitert der Versand, bleibt der Antrag trotzdem bestehen.
Ergebnis: consentUrl, wenn die Installation eine Adresse eingestellt hat
Wann: Eine Freigabe wird zum ersten Mal für einen Wechsel genutzt.
Geht einmal je Freigabe an die Person, die sie erteilt hat. Scheitert der Versand, geht der Wechsel trotzdem durch.
Ergebnis: consentUrl, wenn eingestellt
Was in jeder Mail zur Verfügung steht
Eine Vorlage füllt Platzhalter aus einem Kontext, einer Liste von Namen und Werten. Bei Mails der Registrierung steht dort immer:
| Platzhalter | Inhalt |
|---|---|
email | die Adresse der Person |
registrationId | die ID der Registrierung |
verificationUrl | der Bestätigungslink, leer wo es keinen gibt |
loginUrl | die Anmeldeseite der Anwendung, aus der die Person kam |
passwordUrl | der Link zum Passwort-Setzen, leer wo es keinen gibt |
reason | nur bei REJECTED: der Grund, kann leer sein |
Links, die es nicht gibt, sind leer, aber immer vorhanden. Eine Vorlage muss also nicht prüfen, ob ein Platzhalter existiert. Ein Registrierungs-Hook kann weitere Werte hinzufügen, etwa einen Markennamen, siehe Versand und Branding. PASSWORD_SETUP kennt nur passwordUrl und displayName.
Die beiden Mails zur Freigabe kennen requesterName und requesterEmail bzw. granteeName und granteeEmail, dazu targetRoles (true oder false), validUntil (leer heißt ohne Ende), reason, tenantKey und consentUrl.
In jeder Mail stehen außerdem application und flow: aus welchem Produkt die Person kam und über welchen Ablauf. Beide sind leer, wo der Absender nichts dazu weiß. Eine Vorlage verzweigt darauf, statt dafür eigene Vorlagen zu brauchen, siehe Wie die passende Vorlage gefunden wird.