Skip to content

Authorization

Sign-in establishes who a caller is. A policy decides what they may do. The policy maps verified claims to roles, and roles to permissions, and every Principal.Can is answered by evaluating it. The language lives in pkg/authz; pkg/auth supplies the permissions and applies it.

Grammar

policy    = { statement } ;
statement = role | grant ;
role      = "role" IDENT [ "extends" IDENT { "," IDENT } ] "{" { rule } "}" ;
rule      = ( "allow" | "deny" ) actions "on" resources ;
actions   = "*" | IDENT { "," IDENT } ;          (* read, write *)
resources = "*" | IDENT { "," IDENT } ;          (* agents, runs, schedules, ... *)
grant     = "grant" IDENT { "," IDENT } "to" subject ;
subject   = "group" STRING
          | "subject" STRING
          | "email" "domain" STRING
          | "claim" ( IDENT | STRING ) "=" STRING
          | "anyone" ;

IDENT     = letter_or_underscore { letter | digit | "_" | "-" } ;
STRING    = '"' { any character but '"', "\" or a newline | '\"' | "\\" } '"' ;

# starts a comment to the end of the line. The words of the language are reserved and cannot name a role, action or resource. A claim's name can be any word, or a string for a name such as "https://example.com/roles".

Semantics

  • Default deny. A permission is held only if a rule allows it.
  • Deny wins. A deny beats every allow, wherever either comes from: the same role, a role it extends, a role that extends it, or another role held.
  • Inheritance. A role holds its own rules and every rule of the roles it extends, transitively.
  • Grants. A person holds every role of every grant whose subject matches their verified claims. group matches one entry of the groups claim. subject matches sub. email domain matches the part after @, ignoring case, and only when email_verified is true. claim matches a claim whose value is exactly that string; a missing claim, a list, a number or a boolean never matches. anyone matches any person with a subject and a tenant, never the zero Principal.
  • Machines are not decided by the policy. A machine gets exactly the scopes on its token. It holds no roles, so no grant, anyone included, widens it.
  • Errors at load time. A syntax error, an unknown role in extends or a grant, a cycle, a role declared twice, an unknown action or resource, or a policy with no roles stops the server from starting. Actions and resources are those of auth.Permissions(). A policy is limited to 256 roles, 4096 rules, 4096 grants and 32 levels of inheritance.

Example

role viewer   { allow read on * }
role operator extends viewer {
  allow write on runs, schedules, alerts, evals, artifacts, projects
}
role admin    { allow * on * }
role auditor  extends viewer { deny read on billing }
role steward  extends viewer { allow govern on projects }

grant viewer   to anyone
grant operator to group "eng-oncall"
grant admin    to group "platform-admins"
grant auditor  to claim department = "finance"

Someone in platform-admins whose department is finance holds viewer, admin and auditor, and cannot read billing: the auditor's deny wins.

Projects have three permissions: projects:read, projects:write, and projects:govern, the action govern, which changes the workspace itself and company projects and reuses a deleted project's name. allow * on * holds it, and so does a rule that names it, as steward does above. It adds to projects:write and never replaces it: a steward who cannot write projects changes none. A policy file written before projects had their own permissions adds projects to the rule that lets operators write runs, as above, or only admins make projects.

Upgrading from before projects had their own permissions

Project routes moved from runs:* to projects:*. A policy file written before then takes this one-line change, or only admins make projects:

 role operator extends viewer {
-  allow write on runs, schedules, alerts, evals, artifacts
+  allow write on runs, schedules, alerts, evals, artifacts, projects
 }

People are unaffected under the built-in policy, whose viewer reads *. A machine gets exactly the scopes on its token, so one with explicit scopes (the Slack app, CI) needs humagen:projects:read to list projects. humagen config check warns of a Slack app whose humagen_client holds humagen:runs:read but not humagen:projects:read, the one machine a spec configures; a CI token's scopes are the identity provider's to check.

Project roles

A project role narrows what a permission allows; it never grants one. Every project route checks one tenant permission, then the caller's role on the project it names: the action is allowed when the caller holds the permission and their role is at least the one it needs. A project the caller has no role in answers 404, as a missing one does, and a visible one with too low a role answers 403, saying which role it needs ("you need to own Globex").

Roles are viewer < member < owner, granted by a project's members: * (everyone who can see the parent; at the workspace, everyone holding projects:read), role:<name> (the holders of a policy role, so IdP groups reach a project through a grant), or a subject. Resolve reads a role along the chain, the workspace first: at each level the best entry that matches, an owner above owns every level below, and no role at one level means none below it. projects:govern is owner everywhere. A machine matches only * and its own subject, never a role: entry.

role field-eng {}
grant operator, field-eng to group "field-engineering"

and then {who: "role:field-eng", role: member} on the project.

Action Permission Role
See a project, its inbox, history, members and notes projects:read viewer
Create a project under it projects:write member (company kind: projects:govern)
Propose a note, which its owners keep or discard projects:write member (an owner of the workspace or a company project without projects:govern proposes too)
Start a conversation in it, add a turn to one there, call an agent from a run there, retry a failed turn there from the inbox, or file, change, pause, run or delete a schedule there runs:write, schedules:write member (a surface's act_as is checked as the person it names, who must hold runs:write themselves; a retry is checked as whoever retries, not who first asked)
Stop a run there runs:write member, unless the caller asked for the run or is the machine of the client that raised it
Write or run an eval suite that tries an agent living in it evals:write member: its cases are filed where the agent lives
Change it: title, description, instructions, account, kind, archiving, members, the agents it turns on, who may announce; add, keep or remove notes; delete it projects:write owner (the workspace and company projects: projects:govern too)
Name the knowledge sources every run in it and below is grounded in projects:write owner (the workspace and company projects: projects:govern too), holding knowledge:read as well, which reads the sources anyway. A caller without knowledge:read is shown no source's name
Declare the skills a message posted in it and below can name projects:write owner (the workspace and company projects: projects:govern too)
Make an agent live in it, or move one out agents:write owner of the project it comes to and of the one it leaves
Edit an agent that lives in it: its spec, call policy and notes, keeping or discarding its proposals in the inbox too agents:write owner (the agent's routes take its canonical name, in lower case, and answer 404 for another spelling)
Move it projects:write owner, and member of the new parent; leaving a project that holds a limit needs billing:write, and so does moving one that holds, or has below it, an owner's limit set from a parent the caller does not own; leaving an ancestor whose allow list keeps agents out needs owning it, unless the new chain allows no more; and it is refused (409) while it would leave a project's, a channel's or a thread's default below it, an agent that lives there, or a schedule filed there without its agent
Set a tighten-only limit on it projects:write owner of a project above it
Post an announcement projects:write the project's announce role, owner by default
Withdraw an announcement projects:write its author, or owner
Hide an announcement for oneself projects:read
Read the announcement a Slack reply's thread was started from, its first turn and its runs' input runs:read whoever reads the thread, which is filed in the announcement's project

Until reads are confined to members, every project keeps an entry for * of at least viewer, so a role decides what a person may change, not what they may read. A project record from before roles reads as everyone owning it, which is what any operator could do to it; the workspace reads as everyone a member, owned by projects:govern.

Voice notes have one permission, speech:write: sending a recording from the console to be transcribed. The built-in operator role holds it (allow write on ... speech), and so do manager and admin; a policy file that lists writes by resource adds speech.

The directory has one permission, people:read: seeing who is in the workspace, by name, handle, picture and roles. allow read on * holds it, so every built-in role does, and a policy file that lists reads by resource adds people. A grant to a subject (grant operator to subject "okta|00u1ana") also puts that person in the directory before they first sign in. With tenants from a claim (-tenant-claim, tenant.claim) it does not: the one policy is every tenant's and a grant names no tenant, so a person enters a workspace's directory by signing in to it, or by a client of it mapping them.

Setting the workspace default agent, the root's default, is a change to the workspace itself, so it needs projects:govern as well as projects:write. Managers held it through agents:write while it was a setting called the baseline; role steward above, or allow govern on projects on manager, gives it back to them.

Configure

export HUMAGEN_AUTHZ_POLICY=/etc/warp/policy.authz
humagen serve ...

Without it, the built-in policy (pkg/auth/default.authz) declares viewer, operator, manager and admin with exactly the permissions in security, and grants nothing itself. The -admin-group, -manager-group, -operator-group and -viewer-group flags become grants of those roles. With a policy file, the file decides, and a group flag is added as a grant only if it is set on the command line.

Debug with Explain

authz.Policy.Explain(identity, permission) returns the outcome (allowed, denied or no match), the rule that decided, the role it reached the caller through, the grant that gave that role, and every role held. auth.Policy.Explain(principal, permission) does the same for a signed-in Principal. A sign-in keeps the person's roles and, for each, the grant of the policy that gave it, so the explanation names the grant. It does not keep the claims or the token. A Principal made any other way names the rule and not the grant.

A signed-in person asks about themselves with GET /api/access/explain?permission=agents:write. It takes a permission and no subject, so nobody can ask about someone else, and any signed-in caller may call it. The console shows the answer under Access, reached from "Why can I do this?" on the home page.

From the command line, with the same environment and flags as serve:

humagen authz check policy.authz
HUMAGEN_AUTHZ_POLICY=policy.authz \
  humagen authz explain -claims id-token-claims.json billing:read
billing:read: denied
  rule:  deny read on billing (policy.authz:6:32)
  role:  auditor
  grant: grant auditor to claim department = "finance" (policy.authz:11:1)
  a deny overrides every allow
  holds: viewer (anyone), admin (group "platform-admins"), auditor (claim department = "finance")

-claims is a JSON file of a token's claims, such as a decoded ID token's payload.

Sign in locally

make dev-signin runs the server with -auth=mock: a development identity provider on 127.0.0.1:8081 with a page of personas and no passwords. Sign-in goes through the same flow, verifier and policy as a real provider. The built-in personas are a viewer, an operator, a manager, an admin and someone in no mapped group, and a machine mock-ci (secret mock-ci-secret) with humagen:runs:read and humagen:runs:write:

curl -s -u mock-ci:mock-ci-secret -d grant_type=client_credentials http://127.0.0.1:8081/token

-mock-personas reads others from a JSON file of {"people": [...], "machines": [...]}, with the fields of mockidp.Person and mockidp.Machine. The provider refuses to start unless selected with -auth=mock, refuses any address but 127.0.0.1 or localhost, refuses a redirect that is not loopback, and the server itself must listen on loopback.