The Keycloak extension for the password link

What this is about

An account that CIAS creates has no password. CIAS never accepts one. The person is meant to set it themselves at Keycloak, on Keycloak’s page.

But how do they get there? The required action “set password” (UPDATE_PASSWORD) alone does not help. Keycloak only asks for required actions after login, and without a password nobody can log in. Only “forgot password” would be left.

Keycloak can issue a one-time link that solves exactly this problem. It is valid once, expires, and belongs to one account, one list of actions, one client and one return address. Keycloak signs it with the realm’s key, so nobody outside Keycloak can build it, not even CIAS. But Keycloak’s own admin API only delivers this link in an email that Keycloak sends itself, with Keycloak’s text and Keycloak’s sender.

The extension is not an adapter. The adapter (cias-iam-keycloak) runs in CIAS and calls the extension over HTTP. The extension is the other end of that call, in Keycloak’s server.

The flow

sequenceDiagram
    participant C as CIAS
    participant K as Keycloak
    participant X as Extension in Keycloak
    participant M as Email
    participant B as User
    C->>K: enable account, require UPDATE_PASSWORD
    C->>X: POST /admin/realms/{realm}/cias-action-links
    X->>X: checks caller, account, actions, client, return address
    X-->>C: link and expiry time
    C->>M: email with the link, in CIAS' own template
    M-->>B: email
    B->>K: opens the link
    K-->>B: page "New password"
    B->>K: set password
    K-->>B: on to the return address, that is, the application's login

CIAS never sees a password in this. It only carries the link to the person, just as it carries the confirmation link of a registration.

Request and response

POST /admin/realms/codamai/cias-action-links
Authorization: Bearer <token of the service account cias-admin>
{
  "userId": "5c9e…",
  "actions": ["UPDATE_PASSWORD"],
  "clientId": "hub-frontend",
  "redirectUri": "https://app.example.com/login",
  "lifespan": 86400
}

HTTP 200
{
  "link": "https://sso.example.com/realms/codamai/login-actions/action-token?key=…",
  "expiresAt": "2026-09-23T09:14:03Z"
}

What the extension checks

The extension sits under /admin/realms/{realm}. So Keycloak checks the caller’s token before its code runs at all. After that, it checks by itself:

Every check has a reason. Unlike Keycloak’s own email, the link goes to the caller, not to the person’s mailbox. Without the list of callers, anybody allowed to manage accounts (manage-users) could therefore pick up links for any account. Without the fixed list of actions, one could build a link that, for example, deletes an account (delete_account). The limit of 72 hours makes sure a link does not lie valid in a mailbox for weeks. Without checking the return address, an email from the platform address could lead to a foreign site. Without checking the actions, there would be links that get stuck in the middle of the login. An account that is not enabled could not log in after the password anyway. So the extension refuses loudly here instead of handing out a useless link.

What CIAS does with the link

Two places ask for a link:

• The welcome email of the registration, only for new accounts. See Set the password.
• “Resend the link” by an administrator. See Resend the password setup link.

The variants

Installing the extension

Keycloak loads extensions at startup from the directory /opt/keycloak/providers. The jar is called cias-iam-keycloak-provider.jar and registers itself under the service name cias-action-links.

The jar alone is not enough. Keycloak also has to know which clients may pick up links. Without this setting the extension refuses every request.

KC_SPI_ADMIN_REALM_RESTAPI_EXTENSION__CIAS_ACTION_LINKS__ALLOWED_CLIENTS=cias-admin

Several entries are separated by a comma. An entry without a realm never matches a client of the same name in another realm, because client names are unique only within a realm. In cias-runtime/docker-compose.yml, cias-admin is already set; in the cluster, deploy/keycloak-sidecar.yaml sets the variable on the Keycloak container.

Whether the extension is really loaded cannot be seen from a call without login. The admin API checks the login before the path and answers 401 in both cases. Two ways are reliable: Keycloak’s startup log mentions ActionLinkResourceProviderFactory, or a logged-in call without a body answers 400 or 403 (extension present) instead of 404 (extension missing). The script deploy/smoke-test.sh requests a real link and then checks that a foreign return address, an unknown action, an action that is not permitted and a validity above 72 hours are refused. The client the script logs in with has to be named in allowed-clients for this.

Pitfalls

Next

• Set the password
• Resend the password setup link
• The Keycloak adapter
• Which emails exist