AUTHORIZATION AND POLICY · LAB

Design task-based custom roles for your tenant

Derive roles from real tasks in your tenant, prove the built-in role cannot be changed, see how far a shared role edit reaches, and watch temporary access turn into role creep.

Partly readyUses your lab tenant

The lesson

Designing a role modelPractices Starting from tasks, Built-in and custom roles, Inheriting permissions, When roles multiply, Keeping access small

Builds on: Roles, assignments, and scope.

New to the labs? Start with the lab toolkit and the shared cast and names every lab uses.

Partly ready. Most of this lab runs today. Steps that wait on platform features are marked, and Missing infrastructure says what they need.

G23 Access requests and approvals, access reviews, JIT or temporary access

Your progress

Press Start before you begin. Only events your tenant records after that count, in the order below. Checking reads your tenant's Audit, so you need Audit read access in it.

Create a custom role from a cluster of tasks
Recorded as tenant.roles.create succeeded.
Try to change the built-in Tenant Admin role
Recorded as tenant.roles.update rejected.
Add a permission to a shared role, then take it out
Recorded as tenant.roles.update succeeded.
Give Ben the temporary role with no end date
Recorded as tenant.users.management_roles.assign succeeded about [email protected].

Setup

Complete Build roles, assign them, and work out effective permissions first. Help desk and Auditor exist.
Write down five tasks someone other than you might do in this tenant: unlock people who are locked out, review failed sign-ins, onboard a new OAuth client, run the HR simulator, and manage roles.

Walkthrough

Group the tasks that the same people always do together, and name one role per cluster with a sentence about the work. Two exist: Help desk unlocks people, and Auditor reviews what happened. Create the third in Roles: lab-tmp-app-onboarding with tenant.overview.read, tenant.oauth.clients.read, tenant.oauth.clients.create, tenant.oauth.clients.update and tenant.oauth.scopes.read.

Why it matters: roles start from tasks, not titles. Each one can be described in a sentence about work, like "a Contributor supplies pictures".

Apply the lesson's test to each role. Would two groups of holders ask for different permissions? Then it is two roles. Do they need the same permissions in different places? Then it is one role assigned in different scopes. Here every place is the whole tenant, so a second copy of Help desk for another shift would add nothing but drift.

Why it matters: this is how the Gazette avoided a sports and a news copy of Picture editor.

Open Tenant Admin in Roles. The editor opens read-only. Test the server anyway: open DevTools on the Roles page, save a harmless change to lab-tmp-app-onboarding, and copy the roles/update request as fetch. In the console, change its role ID to tenant_admin and its command_id to a fresh crypto.randomUUID(), then send it. It is refused: "The built-in Tenant Admin role cannot be changed."

Why it matters: built-in roles keep a fixed meaning that the service maintains. Organizations compose custom roles from the same catalog instead, and the server, not the read-only form, enforces the difference.

The reach of a shared role. Roles here are flat, with no inheritance, but an edit still reaches every holder. Before saving, check who holds Help desk. Add tenant.logs.read to it and save. Ben gains it at once; confirm with the console call from the previous lab in his window. Then remove it again.

Why it matters: editing a role changes everyone who holds it, which is the lesson's Viewer surprise in a flat model. Seeing the holders before saving is the review that hierarchy needs.

Role creep. Ben needs to onboard one client "for two weeks". Assign him lab-tmp-app-onboarding under Users > Ben > Management roles. Look for an expiry or a reason field. There is none, so write the date in your lab notes.

Why it matters: without an assignment that ends by itself, temporary access depends on someone remembering to remove it, and each forgotten grant adds to role creep.

Break it

Compare the two tenant.roles.update events for Help desk in Audit from step 4: same role, same actor, opposite changes, and nothing in either record says the change was meant to be temporary.

Why it matters: the record shows what changed and who changed it. Why, and for how long, live only in your notes, which is the gap an expiring assignment closes.

Check your work

Press Check my progress. The checks follow the new role, the refused change to Tenant Admin, the shared role edit and Ben's temporary assignment.

Also confirm by hand:

Each of your three roles has a one-sentence description of the work in your notes.

Cleanup

Remove lab-tmp-app-onboarding from Ben by hand. That manual step is the lesson.
Delete lab-tmp-app-onboarding. A role that someone still holds cannot be deleted, so the removal comes first.
Help desk is back to its permissions from the previous lab.

Missing infrastructure

G23, temporary and just-in-time access. With assignment expiry and a recorded reason, the full lab would assign lab-tmp-app-onboarding to Ben with an expires_at and a reason, move past the expiry, and see his next management request refused without anyone removing the assignment, exactly like Lena's festival assignment.

Back to all labs

Create a tenant