Permissions Service

The Permissions Service (wfa.measurement.access.v1alpha.Permissions) provides APIs for managing permissions and checking what permissions a principal has on protected resources.

Overview

Permissions are the foundation of the access control system:

Granular permissions - Each permission represents a specific operation
Resource-scoped - Permissions apply to specific resource types
Role composition - Permissions are grouped into roles
Runtime checks - Verify permissions before executing operations

Permission Resource

A Permission represents a single operation that can be performed on a resource type.

name

string

Resource name (identifier)Format: permissions/{permission}Examples:

permissions/measurement.create
permissions/report.read
permissions/eventGroup.list

resource_types

string[]

required

Set of resource types this permission can apply toExamples:

["halo.wfanet.org/Measurement"]
["reporting.halo-cmm.org/Report", "reporting.halo-cmm.org/Metric"]
["*"] - Applies to all resource types

Permission Naming Convention

Permission IDs follow the pattern {resource}.{operation}:

Permission	Description
`measurement.create`	Create measurements
`measurement.read`	Read measurement details
`measurement.list`	List measurements
`measurement.cancel`	Cancel measurements
`report.create`	Create reports
`report.read`	Read report results
`report.list`	List reports
`metric.create`	Create metrics
`metric.read`	Read metric results
`metric.invalidate`	Invalidate cached metrics
`eventGroup.list`	List event groups
`policy.manage`	Create and modify policies

Service Methods

GetPermission

Retrieve a permission by resource name.

name

string

required

Permission resource nameFormat: permissions/{permission}

Permission

message

The requested permission resource

Example:

from wfa.measurement.access.v1alpha import permissions_service_pb2

request = permissions_service_pb2.GetPermissionRequest(
    name="permissions/measurement.create"
)

permission = permissions_client.GetPermission(request)
print(f"Permission: {permission.name}")
print(f"Resource types: {permission.resource_types}")

Error Codes:

PERMISSION_NOT_FOUND - Permission does not exist

ListPermissions

List all available permissions in the system.

page_size

int32

Maximum number of permissions to returnDefault: 50 Maximum: 100

page_token

string

Token from previous ListPermissions call for pagination

permissions

Permission[]

List of permission resources

next_page_token

string

Token for retrieving the next page (empty if no more pages)

Example:

request = permissions_service_pb2.ListPermissionsRequest(
    page_size=100
)

response = permissions_client.ListPermissions(request)

for permission in response.permissions:
    print(f"Permission: {permission.name}")
    print(f"  Resource types: {permission.resource_types}")
    print()

CheckPermissions

Check what permissions a principal has on a specific resource.

protected_resource

string

Name of the resource to check permissions onFormat: Resource-specific (e.g., measurementConsumers/{id}/reports/{id})If not specified, checks permissions on the root of the API.

principal

string

required

Principal to check permissions forFormat: principals/{principal}

permissions

string[]

required

Set of permissions to checkExample: ["measurement.create", "measurement.read", "report.create"]

permissions

string[]

Subset of requested permissions that the principal hasEmpty array if principal has none of the requested permissions.

Example:

request = permissions_service_pb2.CheckPermissionsRequest(
    protected_resource="measurementConsumers/123/reports/456",
    principal="principals/user-alice",
    permissions=[
        "report.read",
        "report.delete",
        "metric.create"
    ]
)

response = permissions_client.CheckPermissions(request)

print(f"Alice has permissions: {response.permissions}")
# Output: Alice has permissions: ['report.read', 'metric.create']

# Check if has specific permission
if "report.read" in response.permissions:
    print("Alice can read this report")
else:
    print("Access denied")

Error Codes:

PRINCIPAL_NOT_FOUND - Principal does not exist
PERMISSION_NOT_FOUND - One or more requested permissions don’t exist

Permission Check Patterns

Pre-request Authorization

Check permissions before making API calls:

def create_report_with_auth_check(principal_name, report_data):
    """
    Create a report only if principal has permission.
    """
    # Check permissions first
    check_request = permissions_service_pb2.CheckPermissionsRequest(
        protected_resource="measurementConsumers/123",
        principal=principal_name,
        permissions=["report.create"]
    )
    
    check_response = permissions_client.CheckPermissions(check_request)
    
    if "report.create" not in check_response.permissions:
        raise PermissionError("User lacks report.create permission")
    
    # Proceed with report creation
    return reports_client.CreateReport(report_data)

Batch Permission Check

Check multiple permissions at once:

def check_user_capabilities(principal_name, resource_name):
    """
    Check all relevant permissions for a resource.
    """
    request = permissions_service_pb2.CheckPermissionsRequest(
        protected_resource=resource_name,
        principal=principal_name,
        permissions=[
            "measurement.create",
            "measurement.read",
            "measurement.list",
            "measurement.cancel",
            "report.create",
            "report.read"
        ]
    )
    
    response = permissions_client.CheckPermissions(request)
    
    # Build capability map
    capabilities = {
        "can_create_measurement": "measurement.create" in response.permissions,
        "can_read_measurement": "measurement.read" in response.permissions,
        "can_list_measurements": "measurement.list" in response.permissions,
        "can_cancel_measurement": "measurement.cancel" in response.permissions,
        "can_create_report": "report.create" in response.permissions,
        "can_read_report": "report.read" in response.permissions,
    }
    
    return capabilities

UI Authorization

Determine which UI elements to show:

def get_ui_permissions(user_principal, measurement_consumer_id):
    """
    Get permissions for UI rendering.
    """
    request = permissions_service_pb2.CheckPermissionsRequest(
        protected_resource=f"measurementConsumers/{measurement_consumer_id}",
        principal=user_principal,
        permissions=[
            "measurement.create",
            "report.create",
            "report.read",
            "eventGroup.list",
            "metric.create",
            "policy.manage"
        ]
    )
    
    response = permissions_client.CheckPermissions(request)
    
    return {
        "show_create_measurement_button": "measurement.create" in response.permissions,
        "show_create_report_button": "report.create" in response.permissions,
        "show_reports_tab": "report.read" in response.permissions,
        "show_event_groups_tab": "eventGroup.list" in response.permissions,
        "show_metrics_tab": "metric.create" in response.permissions,
        "show_admin_panel": "policy.manage" in response.permissions,
    }

Permission Hierarchy

Permissions can be organized hierarchically:

resource.*         # All operations on resource
├── resource.create
├── resource.read
├── resource.update
├── resource.delete
└── resource.list

The system does not automatically grant wildcard permissions. Each permission must be explicitly assigned through roles and policies.

Integration with Roles and Policies

Permissions are granted to principals through the role-policy system: Example Policy:

# Create a role with permissions
role = roles_service_pb2.Role(
    name="roles/report-viewer",
    permissions=[
        "permissions/report.read",
        "permissions/report.list",
        "permissions/metric.read"
    ]
)

# Create a policy binding principal to role
policy = policies_service_pb2.Policy(
    protected_resource="measurementConsumers/123",
    bindings=[
        policies_service_pb2.Policy.Binding(
            role="roles/report-viewer",
            members=["principals/user-alice"]
        )
    ]
)

# Now CheckPermissions for alice will return the role's permissions

Common Permission Sets

Read-Only Access

READ_ONLY_PERMISSIONS = [
    "measurement.read",
    "measurement.list",
    "report.read",
    "report.list",
    "metric.read",
    "metric.list",
    "eventGroup.list",
]

Report Creator

REPORT_CREATOR_PERMISSIONS = [
    "report.create",
    "report.read",
    "report.list",
    "metric.create",
    "metric.read",
    "eventGroup.list",
]

Measurement Administrator

MEASUREMENT_ADMIN_PERMISSIONS = [
    "measurement.create",
    "measurement.read",
    "measurement.list",
    "measurement.cancel",
    "report.create",
    "report.read",
    "report.list",
    "metric.create",
    "metric.read",
    "metric.list",
    "metric.invalidate",
    "eventGroup.list",
]

System Administrator

SYSTEM_ADMIN_PERMISSIONS = [
    "*"  # All permissions (must be defined as separate permission)
]

Best Practices

Check permissions early

Verify permissions at the start of request handlers before expensive operations. Fail fast if unauthorized.

Use least privilege principle

Grant only the minimum permissions required for each role. Don’t grant admin permissions by default.

Batch permission checks

When checking multiple permissions, use a single CheckPermissions call rather than multiple calls.

Cache permission check results

Cache CheckPermissions responses for short durations (e.g., 60 seconds) to reduce API calls, but balance with security needs.

Document permission requirements

Clearly document which permissions are required for each API operation in your API documentation.

Audit permission checks

Log failed permission checks for security monitoring and debugging authorization issues.

Error Handling

PERMISSION_NOT_FOUND

error

One or more requested permissions don’t existResolution: Verify permission names match defined permissions in the system

PRINCIPAL_NOT_FOUND

error

Principal does not existResolution: Verify principal resource name and ensure principal was created

INVALID_ARGUMENT

error

Invalid resource name format or empty permissions listResolution: Verify request parameters follow correct format

Policies Service

Manage access policies

Principals Service

Manage principals (users and services)

API Overview

Access control architecture

Public APIs

System APIs

Access Control

Overview

Permission Resource

Permission Naming Convention

Service Methods

GetPermission

ListPermissions

CheckPermissions

Permission Check Patterns

Pre-request Authorization

Batch Permission Check

UI Authorization

Permission Hierarchy

Integration with Roles and Policies

Common Permission Sets

Read-Only Access

Report Creator

Measurement Administrator

System Administrator

Best Practices

Error Handling

Policies Service

Principals Service

API Overview

Build docs developers (and LLMs) love

Public APIs

System APIs

Access Control

​Overview

​Permission Resource

​Permission Naming Convention

​Service Methods

​GetPermission

​ListPermissions

​CheckPermissions

​Permission Check Patterns

​Pre-request Authorization

​Batch Permission Check

​UI Authorization

​Permission Hierarchy

​Integration with Roles and Policies

​Common Permission Sets

​Read-Only Access

​Report Creator

​Measurement Administrator

​System Administrator

​Best Practices

​Error Handling

​Related APIs

Policies Service

Principals Service

API Overview

Build docs developers (and LLMs) love

Overview

Permission Resource

Permission Naming Convention

Service Methods

GetPermission

ListPermissions

CheckPermissions

Permission Check Patterns

Pre-request Authorization

Batch Permission Check

UI Authorization

Permission Hierarchy

Integration with Roles and Policies

Common Permission Sets

Read-Only Access

Report Creator

Measurement Administrator

System Administrator

Best Practices

Error Handling

Related APIs