What this is about
After registration, a person gets a link in the welcome email to set their password in Keycloak. Sometimes this email gets lost, or the link has expired. Then a platform administrator can send a new link.
The flow
-
1Admin→CIASrequests the link, without a body
-
2CIASPlatform administrator? Person known?otherwise 403 or 404
-
3CIASDelivery configured? Account active?otherwise 501 or 409
-
4CIAS→Keycloakfetches a one-time link through the Keycloak extensionThe link carries the action "set password" itself. Keycloak only demands it once the person opens the link.
-
5CIAS→EmailEmail
PASSWORD_SETUPwith the link to the person's addressin the language Keycloak holds for the person (attributelocale), otherwise German -
6CIASEvent
PasswordSetupLinkSentResult: 200{ "recipient": "anna@nordbau.example", "expiresAt": "…" }
The variants
When: The installation has configured the delivery, and the account is active.
The person gets the email, clicks the link, sets a password in Keycloak, and then lands on the configured return address. The email may have its own template per tenant.
Result: New password set. Until then the old one stays valid.
When: The account is not yet enabled (PENDING), suspended (SUSPENDED) or closed (CLOSED).
CIAS refuses before Keycloak does anything. An account that is not yet enabled cannot sign in at Keycloak, a suspended or closed one is meant to stay out.
Result: 409 cias.user.invalid-state, no email.
When: The installation has not set a client for this link.
CIAS refuses, the account stays unchanged. The person can request a new password themselves through "Forgot password" on the login page.
Result: 501 cias.user.password-setup-unavailable, no email.
When: The add-on module cias-iam-keycloak-provider is not installed in Keycloak.
Keycloak does not know the endpoint for the link. CIAS refuses, the account stays unchanged.
Result: 501 cias.user.password-setup-unavailable, no email. See The Keycloak extension for the password link.
Settings
| Setting | Meaning |
|---|---|
codamai.cias.user.password-setup.client-id | the browser client of the user interface Keycloak issues the link for. Empty means: feature off, response 501 |
codamai.cias.user.password-setup.return-url | where the person lands after setting the password. Must be a permitted redirect address of that client. If a client is set and the address is missing, the application does not start |
codamai.cias.user.password-setup.valid-for | how long the link is valid, default 24 hours, at most 72 hours |
The settings are separate from those of registration. A registration knows which application it ran for, an administrator’s link does not. That is why it needs its own return address.