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.
groupmatches one entry of the groups claim.subjectmatchessub.email domainmatches the part after@, ignoring case, and only whenemail_verifiedistrue.claimmatches a claim whose value is exactly that string; a missing claim, a list, a number or a boolean never matches.anyonematches any person with a subject and a tenant, never the zeroPrincipal. - Machines are not decided by the policy. A machine gets exactly the scopes
on its token. It holds no roles, so no grant,
anyoneincluded, widens it. - Errors at load time. A syntax error, an unknown role in
extendsor 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 ofauth.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.
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¶
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:
-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.