quay/agent_docs/global_readonly_superuser.md

Global Read Only Superuser

Overview

Global Read Only Superusers have read access to all repositories and resources across the registry, but cannot perform any write operations. This is useful for auditing and monitoring.

Configuration

# conf/stack/config.yaml
SUPER_USERS:
  - admin
GLOBAL_READONLY_SUPER_USERS:
  - quayadmin
  - readonly

Key Implementation Files

File	Purpose
util/config/superusermanager.py	is_global_readonly_superuser() check
auth/permissions.py	Permission classes with global readonly support
endpoints/api/__init__.py	allow_if_global_readonly_superuser() helper
endpoints/v2/__init__.py	V2 permission decorators

API v1 Support

Add support to endpoints via decorator parameter:

@require_repo_read(allow_for_global_readonly_superuser=True)
def get_repository(namespace, repository):
    # Global readonly superusers can access this

API v2 Support

V2 endpoints require explicit support:

@require_repo_read(allow_for_superuser=True, allow_for_global_readonly_superuser=True)
def list_tags(namespace_name, repo_name):
    # V2 endpoint accessible to global readonly superusers

Write Operation Blocking

Global readonly superusers are blocked from writes at multiple levels:

1. Permission Classes (auth/permissions.py): Each write permission class checks and blocks global readonly superusers

2. Superuser Function (endpoints/api/__init__.py): allow_if_superuser() excludes global readonly superusers from write privileges

3. Endpoint Level: Individual endpoints may have additional checks

App Token Access

Special handling for app tokens:

Endpoint	Superuser	Global Readonly	Regular User
List tokens	All tokens	All tokens	Own tokens only
Get token	Any token	Any token	Own tokens only
Create/Delete	Yes	No	Own tokens only

Testing

# Test read access (should work)
curl -s -b cookies.txt "http://localhost:8080/api/v1/repository/private/repo"

# Test v2 access
TOKEN=$(curl -s -u quayadmin:password "http://localhost:8080/v2/auth?service=localhost:8080" | jq -r '.token')
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:8080/v2/_catalog"

# Test write blocking (should return 403/insufficient_scope)
curl -s -b cookies.txt -X POST \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{"repository": "test", "visibility": "private"}' \
  "http://localhost:8080/api/v1/repository"

Adding Global Readonly Support to New Endpoints

1. For read endpoints, add allow_for_global_readonly_superuser=True to decorator
2. For write endpoints, no changes needed (blocked by default)
3. Add tests in endpoints/api/test/test_global_readonly_superuser.py