# 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. | Term | What it is | Example | | ---------- | -------------------------------------------- | -------------------------------------- | | Permission | An action on a kind of thing | `manage:agents`, `read:audit` | | Role | A named set of permissions | Administrator, Auditor, Developer | | Group | A set of people, agents and other groups | `engineering` | | Grant | One subject's access to one particular thing | `group:engineering` may open `grafana` | 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:ada@acme.com` or `group:engineering`. | Subject | Is | | -------- | -------------------------------- | | `user:` | A person | | `group:` | A group | | `agent:` | An AI agent | | `app:` | An application calling as itself | ## What a grant can be on A grant names the kind of thing it gives access to. | Kind | Grants access to | | -------------- | ----------------------------------------- | | `app` | Sign-in to an application | | `saml_sp` | Sign-in to a SAML application | | `cloud_role` | Assuming a role in a cloud account | | `server` | Connecting to a server | | `network_rule` | Reaching a service protected by Zero-Code | | `mcp` | Calling a tool through the MCP gateway | 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](/access/servers#what-the-certificate-contains) 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. | To | Open | Select | | --------------------------------- | ------------------------------------------------------- | ------------------ | | Create a group | **Identity > Groups**, **Groups** tab | **New group** | | Add a person, a group or an agent | The group's page | **Add member** | | Grant a group access to something | The group's page, **Roles & access** tab | **Grant access** | | Create a role | **Identity > Roles & permissions**, **Roles** tab | **New role** | | Bind a role | The role's page | **Give this role** | | Create a permission | **Identity > Roles & permissions**, **Permissions** tab | **New permission** | | Assign an application to a group | The application's page | **Assign a group** | 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 See who may use an application, and which groups appear in its tokens. Grant an agent capabilities, and write rules that deny an action or ask a person. Grant a tool to an agent or to a group the agent is in. Grant a server to a group, and its members can connect.