The authorization engine in your tenant

The model

The model lists resource types, the relations each type has and the actions each type allows. Every tenant starts with the photo library model the labs use: libraries hold albums, albums hold photos, and owner, editor, contributor and viewer each include the next. A relation can include another relation of the same object ("editor"), or a relation reached through one of its subjects ("parent->viewer", whoever views the object's parent). Each action names the relation that allows it, such as "photo.delete": "editor". Types user and group always stay. A model change that would leave stored relationships, rules or roles without a definition is refused.

Relationships

A relationship says that a subject holds a relation on an object: album:4410 owner user:<ID>. A subject can also be everyone holding a relation on another object, such as group:editors#member. Users can be named by email when you write a relationship and are stored by ID. Members of a directory group count as group:<group ID>#member without writing anything. A decision that a relationship grants shows the path it followed, for example photo, album, library, group, user.

Application roles

A role grants actions, such as album.view, on every resource whose type defines them. Members are users, named by email or ID, and directory groups, named by display name or ID. Application roles are separate from the tenant's management roles and give no access to tenant management.

Attribute rules

A rule allows or denies actions on a resource type when its condition holds. Conditions compare an attribute with a value, or with another attribute, and combine with all, any and not. Subject attributes come from the directory: email, department, title, organization, division, cost center, employee number, groups, directory roles and application roles. Resource attributes come from the request; for the sample API's albums and photos the engine adds the owner, visibility, status and embargo itself, and the request cannot replace them. Context attributes come from the request, plus the server's time as context.time.hour and context.time.weekday in UTC. A missing attribute never matches. Rules use a bounded JSON condition language rather than arbitrary code. Decisions depend on the current attributes, roles and server time; different inputs can produce different outcomes.

Combining

Grants are roles and relationships. With deny overrides, the default, any matching deny rule refuses, otherwise a grant or allow rule permits. With permit overrides, any grant or allow rule permits, otherwise a deny rule refuses. With first applicable, the first matching rule in position order decides, then grants. With nothing that permits, the answer is deny.

Decision endpoints

The engine follows OpenID AuthZEN 1.0. Its metadata is at /.well-known/authzen-configuration on the tenant host. A confidential client calls it with a client credentials token that carries the built-in authz:evaluate scope, which must be assigned to the client:

POST /access/v1/evaluation
Authorization: Bearer <token>
Content-Type: application/json

{"subject": {"type": "user", "id": "[email protected]"}, "action": {"name": "photo.view"}, "resource": {"type": "photo", "id": "9001"}}

The answer is {"decision": true, "context": {...}}, where the context names the reason, the rule, roles or relationship path, the policy and relationship versions, and the decision ID. /access/v1/evaluations answers up to 20 questions at once, and /access/v1/search/resource, /search/subject and /search/action list what a subject may reach, who may act on a resource, and which actions are allowed, checking at most 500 candidates. /access/v1/relationships reads (GET) and writes (POST {"writes": [...], "deletes": [...]}) relationships with the authz:relationships scope. A token issued for a user cannot call these endpoints.

Decisions and history

Every decision from an endpoint, the sample API or the Test tab is explained in the Decisions log, kept for 30 days; the oldest explanations are removed first when 20,000 are stored. Each endpoint decision is also recorded in the tenant's protocol Audit with its reason, and every change to the model, roles, rules or relationships is recorded in Audit with who made it. The Test tab runs the same evaluation without an application. Each test is recorded in Audit as tenant.authz.test with the answer's reason, such as permitted_by_role or denied_by_rule, the person asked about as its subject when they are a user of the tenant, and the action, resource, deciding rule and Decisions entry. The context you enter is not kept in Audit.

Versions and rollback

Every change to the model, the combining approach, a rule or a role's actions keeps a version on the Versions tab, up to the latest 100. The first change also keeps the policy as it was before. View shows what changed from the version before: the model, the combining approach, rules added, removed or changed with the fields that changed, and role actions added or removed. Roll back to this version restores the model, the combining approach, the rules and the actions of the roles that existed at that version, as a new version; a role created since keeps its actions. Role members, relationships and the directory are not policy and are never rolled back, so a rollback cannot give access back to someone it was taken from; a role deleted since is not recreated.

Policy tests

A test on the Policy tests tab is a decision request, with any context, and the answer it must get. Tests run each time the tab opens, against the current directory and relationships as well as the policy, so a failure can come from either. Changes made on the Authorization page are checked, including a role's members. A relationship written through the API and access given through Governance are not refused, even if they make a test fail. The refusal of a change is recorded in Audit with the IDs of the failing tests. With Require every test to pass before a policy change is saved, any change to the model, a rule or a role, a rollback or a promoted shadow policy that makes a test fail is refused whole and recorded with the number of failing tests. Requiring tests needs at least one test, all passing. A tenant can keep 50 tests.

Shadow policy

On the Shadow tab, a candidate set of rules and a combining approach run beside the active policy. Real decisions from the decision endpoints and the sample photo API are evaluated by both; the answer always comes from the active policy, and every request the two would answer differently is listed with both answers and the rule that decided the shadow one. Test decisions are not compared. The tab keeps the latest 1,000 disagreements for 30 days and totals for the whole run. Each disagreement names the person and resource, so listing them also needs permission to read the decision log; without it, the totals still show. Make active replaces the active rules and combining approach with the candidate as a new version, after the required tests pass; Stop ends the run.

Permissions and limits

Reading the engine, changing it, reading and writing relationships, reading decisions, testing, reading versions, rolling back and managing policy tests each need their own tenant permission, which Tenant Admin holds. Starting, stopping and promoting a shadow policy need the permission to change the engine. A tenant can keep 50 application roles, 100 rules and 10,000 relationships, shown in its usage view. Decision endpoints share a per-minute budget, also shown there.