What this is about
Many changes to a person must be written in two places: in the CIAS record and in the account in Keycloak. The two writes cannot be put into one shared transaction. If something fails between the two, one place has the new state and the other has the old one.
You cannot prevent this, but you can decide which half-finished state remains. CIAS always picks the safe one.
The two directions
sequenceDiagram
participant A as Admin
participant C as CIAS
participant K as Keycloak
Note over A,K: Revoke access (suspend, close)
A->>C: suspend
C->>K: 1. disable account
C->>C: 2. save status SUSPENDED
C-->>A: 200
Note over A,K: Grant access (reactivate)
A->>C: reactivate
C->>C: 1. save status ACTIVE
C->>K: 2. enable account
C-->>A: 200
What remains after a failure
When: Suspend or close
-
1CIAS→Keycloakdisables the account
-
2CIASsaves the new statusfails: record still shows the old status
Result: The person can no longer sign in, even though the record still shows the old status. Safe. Repeat the call, then the record is correct too.
When: Reactivate
-
1CIASsaves
ACTIVE -
2CIAS→Keycloakenables the accountfails: account stays disabled
Result: The record says ACTIVE, but the person cannot sign in yet. Safe. Repeat the call.
When: Keycloak does not respond, or responds with a server error.
CIAS aborts and responds with 503 cias.iam.unavailable. When revoking, nothing has been written yet. When granting, the new status is already in the record.
Result: Try again later.
When: Rename, change home tenant, replace CIAS attributes
These changes only affect the record in CIAS and write nothing to Keycloak. There is no second place, so there is no half-finished state.
The table
| Operation | Order | Remains after a failure in between |
|---|---|---|
| suspend, close | Keycloak, then CIAS | account disabled, record still old |
| reactivate, activate | CIAS, then Keycloak | record ACTIVE, account still disabled |
| rename, move, CIAS attributes | only CIAS | – |
Repeating is always safe
You can simply repeat each of these calls. Disabling an account that is already disabled changes nothing. Activating an active person does not either. This is why the repair after a failure is always the same: the same call once more.
There is no background job for users that reconciles record and account on its own. A difference shows up at the next operation on this person.