Grant a role

What this is about

Granting a role means: a person gets a permission, usually in a specific tenant. For this, CIAS stores a grant and enters the role in Keycloak. With the next token, the person has the role.

Before that happens, CIAS checks whether the caller is allowed to do this at all.

The call

POST /cias/admin/role-assignments
Authorization: Bearer <token of Anna, tenant-admin in nordbau>
{
  "userId": "5c9e…",
  "roleClient": "cias-backend",
  "roleKey": "tenant-user",
  "tenantKey": "nordbau",
  "validFrom": null,
  "validUntil": null,
  "reason": "new colleague in purchasing"
}

HTTP 200
{
  "id": "a41f…",
  "userId": "5c9e…",
  "roleClient": "cias-backend",
  "roleKey": "tenant-user",
  "scope": "TENANT",
  "tenantKey": "nordbau",
  "validFrom": null,
  "validUntil": null,
  "state": "ACTIVE",
  "grantedBy": "nordbau",
  "reason": "new colleague in purchasing"
}

The checks in order

After that, CIAS also checks the receiving person and the tenant:

• A client role with scope PLATFORM for a person whose home tenant has an organization: 403. The role would be in the token, but no request would read it, see Realm role, client role, organization role.
• A tenant role in a tenant without an organization, that is, a static tenant: 403. In Keycloak, a tenant role is attached to the organization. CIAS never falls back to a global grant, because that would turn a tenant role into a platform role by accident.

All refusals of the permission check look the same: 403 cias.authorization.denied with the text not permitted. CIAS writes the exact reason to the log.

The decision table

The own tenant comes from the caller’s token, never from the request. Otherwise every tenant administrator could grant a delegated role in any other tenant. How the ceiling is counted is described in The ceiling: nobody grants more than they have.

The flow when everything is right

sequenceDiagram
    participant A as Anna (tenant-admin)
    participant C as CIAS
    participant DB as CIAS database
    participant K as Keycloak
    A->>C: POST /cias/admin/role-assignments
    C->>C: check role, delegation, tenant, ceiling
    C->>DB: is there already a running grant? otherwise store (ACTIVE)
    C->>K: person into group cias-backend:tenant-user of organization nordbau
    C-->>A: 200 with the grant, event Granted

First store the grant, then Keycloak. If Keycloak fails, CIAS records more than the token carries. That tends to refuse rather than allow too much, and a second call catches up.

The call can be repeated safely: if there is already a running grant for this person, this role and this tenant, CIAS does not create a second one. Two running grants of one role would have two end dates, and nobody would know which one applies. With the same window and reason CIAS returns the existing one; with a different one the existing grant takes it over, see Time-limited roles.

How the role is entered in Keycloak depends on level and scope, see Realm role, client role, organization role.

Variants

Viewing grants

Pitfalls

Next

• Revoke a role
• Time-limited roles
• The ceiling: nobody grants more than they have