Configure principal attributes

Principal attributes are the input to Principal Set conditions and to $principal.* references in Resource Set rules. Configure them before enabling a restrictive ABAC policy.

Principal context

Vertesia evaluates dynamic rules against this logical context:

How user and group attributes combine

For a user, Vertesia merges the user's attributes with attributes from groups that apply to the selected project:

• Clearance uses the highest configured value.
• Compartments are combined as a union.
• Tags are combined as a union.
• Custom properties are merged into the properties object.

Project-restricted groups contribute attributes only in projects they are allowed to cover. This prevents a group's clearance or department properties from leaking into unrelated projects.

Configure group attributes

Group attributes are the preferred way to manage shared organizational policy.

1. Open Organization Settings → Groups.
2. Create or edit a group.
3. Configure:
   • Clearance — a level from 0 (Public) through 4 (Secret).
   • Compartments — stable identifiers such as legal, finance, or customer-a.
   • Tags — labels that can select groups dynamically, such as employee or finance.
   • Properties — a JSON object containing fields such as department, region, or employment_type.
   • Allowed Projects — projects in which the group and its attributes apply.
4. Add the relevant users as members.
5. Save the group and issue a new user token before testing access.

Example custom properties:

{
    "department": "legal",
    "region": "eu",
    "employment_type": "employee"
}

Conditions reference these values using paths such as properties.department.

Configure user attributes

Organization administrators can edit a user's clearance, compartments, and custom properties from the organization user-management view. Use direct user attributes for exceptions that should not be modeled as group membership.

Prefer group attributes for normal team policy. A large number of direct user exceptions is difficult to audit and can produce surprising merged values.

Configure API-key attributes

1. Open Project Settings → API Keys.
2. Locate the key and select Edit properties.
3. Set its clearance, compartments, and custom properties.
4. Save and issue a new token for the key before testing.

API keys do not inherit user or group attributes. Their principal context comes only from the key itself. Use a Principal Set condition such as kind = apikey when a policy should apply only to service access.

Delegate API-key attributes from automation

A project admin API key can manage security attributes on other API keys in the same project.

The admin key can create or update keys subject to these bounds:

• Clearance — when the admin key has a clearance, a target key's resulting clearance cannot exceed it. An admin key without a clearance may set any clearance.
• Compartments — when the admin key has compartments, the target key's resulting compartments must be the same unordered set. An admin key without compartments may set any compartments.
• Properties — custom properties are unrestricted.

Assign the admin role only to automation that must provision other project credentials.

Naming guidance

• Keep compartment identifiers stable, lowercase, and machine-friendly.
• Use the same vocabulary on principals and resources.
• Store numerical policy fields such as security level in the dedicated clearance/sensitivity fields.
• Put organization-specific strings and booleans under properties.
• Avoid placing confidential values in authorization attributes; tokens may carry resolved policy information.

Safe rollout checklist

Before enabling restrict mode:

1. Confirm every affected principal has the expected merged context.
2. Classify a small set of test documents or collections.
3. Create a narrow rule for a test group.
4. Refresh that user's token and verify both allowed and denied resources.
5. Add the global restrict-mode switch only after the granting rules are ready.

Continue with Dynamic access rules.