Roles, groups and grants

Understand the four things that decide what a person or agent may do, how a group passes access on, and the order in which a decision is made.

Every access decision in AuthFI is made from the same four things: permissions, roles, groups and grants. Learn them once and they apply to applications, cloud roles, servers and AI agents alike.

Permissions, roles, groups and grants

A permission is an action on a kind of thing, such as read:audit. A role is a named set of permissions. A group is a set of people, agents and other groups. A grant gives one subject access to one particular thing.

Roles and grants answer different questions. A role answers "what may this person do in the project?". A grant answers "may this person reach this one application, cloud role or server?".

Who can hold access

Whoever holds a role or a grant is called a subject. A subject is written as its kind and its ID, for example user:[email protected] or group:engineering.

What a grant can be on

A grant names the kind of thing it gives access to.

A grant can carry an end date. After that date the grant no longer counts, and nobody has to remember to remove it.

Groups pass access on

Grant something to a group and every member has it. Groups can contain groups, and membership is followed all the way down.

Put a person in a group and they gain everything granted to it. Take them out and they lose it. A change is seen everywhere within 30 seconds, and at the latest when their current token expires. An SSH session that is already open stays open, as Set up server access describes.

This is why access in AuthFI is given to groups, and people are moved between groups. Applications, cloud roles, servers and tools are all assigned to groups in the same way.

A token carries the caller's groups in the groups claim and their roles in the roles claim.

Built-in roles

Every project starts with a set of roles, among them Owner, Administrator, Auditor, Help Desk, Developer and Member. They cannot be renamed, deleted or given different permissions, so their meaning is the same in every project. Create your own roles for anything else.

A role takes effect when it is bound to a person, a group or an AI agent. Like a grant, a binding can carry an end date.

How a decision is made

Every check runs in the same order:

1. If a rule denies it, the answer is no. Nothing overrides a deny.
2. Otherwise, if a role's permission or a grant allows it, the answer is yes.
3. If a rule says this action needs approval, a yes becomes "wait for a person".
4. If nothing allowed it, the answer is no.

Two consequences follow. Access is denied by default, because step 4 answers no when nothing allows the action. And a deny always wins, because step 1 runs before any role or grant is considered.

Applications are open until first assigned

Applications follow one more rule. An application nobody has been assigned to is open to everyone who can sign in to the project. The first assignment closes it to everyone else.

This lets you connect an application and try it before you decide who gets it.

Where each one is managed in the console

Groups, roles and permissions each have a page under Identity in the AuthFI console. A grant to a group is made from that group's page.

Every project is installed with three groups: Super Admins, Approvers and Everyone. They cannot be deleted.

A new permission is an Action and a Resource. Its key is the two joined by a colon, as in read:audit, and the key cannot be changed later.

Next steps