What this is about
Revoking a role means: a grant ends before its time has run out. You always revoke one specific grant, identified by its ID, not “the role tenant-user of Anna”. You find the ID in the list of grants of a person or a tenant, see Grant a role.
The call
POST /cias/admin/role-assignments/a41f…/revoke
Authorization: Bearer <token of Anna, tenant-admin in nordbau>
{ "reason": "moved to another department" }HTTP 200
{ "id": "a41f…", "roleKey": "tenant-user", "tenantKey": "nordbau",
"state": "REVOKED", … }The reason is required. If it is missing, CIAS responds with 400. It ends up in the event Revoked and therefore in the audit.
Who may revoke
Revoking follows the same rules as granting:
- A platform administrator may revoke any grant.
- Everyone else only a grant of a tenant role that is delegated to one of their roles, in their own tenant, and only if they hold the role there themselves.
If you may not grant a role, you may not revoke it either: 403 cias.authorization.denied. A retired role, on the other hand, can still be revoked, it just can no longer be granted.
The flow
sequenceDiagram
participant A as Anna
participant C as CIAS
participant K as Keycloak
participant DB as CIAS database
A->>C: POST …/a41f…/revoke {reason}
C->>C: load grant, check permissions
C->>K: person leaves group cias-backend:tenant-user in nordbau
C->>DB: grant := REVOKED
C-->>A: 200, event Revoked
The order is the reverse of granting. The rule behind it is the same: what takes access away comes first, what gives access comes last. No matter which half fails, in the end the person is more likely to be without the role than with one nobody wanted.
Variants
When: The grant is ACTIVE.
CIAS removes the role in Keycloak and sets the grant to REVOKED.
Result: Event Revoked with the reason and the caller's tenant.
When: The grant is SCHEDULED, its start is in the future.
Nothing is entered in Keycloak, so CIAS does not call Keycloak. The grant becomes REVOKED and never starts.
Result: After that, the timer no longer touches it.
When: The grant is already REVOKED, for example because the first response got lost.
CIAS changes nothing and responds like the first time.
Result: Repeating is safe.
When: The grant is EXPIRED.
An expired grant is not revoked afterwards. "Expired" and "revoked" are different answers to the question of why someone lost a permission.
Result: 409 cias.authorization.invalid-state
When: There is no grant for the ID.
CIAS changes nothing.
Result: 404 cias.authorization.assignment-not-found
What happens in Keycloak
| Grant | In Keycloak |
|---|---|
realm or client role, scope PLATFORM | the role is removed directly from the account |
| tenant role | the person leaves the group <client>:<role> in the organization |
For a tenant role, the group with its role stays. If CIAS removed the role from the group, all other members of the tenant would lose it at once.
When it takes effect
-
CIASCIASrole removed in Keycloak, grant
REVOKED -
KeycloakTokenThe token the person has right now still carries the role until it expires or is renewed
-
CDMSApplicationchecks the roles from the request's token↳ no 403 only with the new token
- The person can no longer use the role
So a revocation does not take effect in the same second. How long it takes depends on the token’s lifetime. More in Why revoking permissions takes effect with a delay. If a person should immediately be unable to do anything, suspend their account, see Suspend, reactivate, close.