upstream-seaweedfs/weed/s3api/policy_engine/GOVERNANCE_PERMISSIONS.md

Governance Permission Implementation

This document explains the implementation of s3:BypassGovernanceRetention permission in SeaweedFS, providing AWS S3-compatible governance retention bypass functionality.

Overview

The governance permission system enables proper AWS S3-compatible object retention with governance mode bypass capabilities. This implementation ensures that only users with the appropriate permissions can bypass governance retention, while maintaining security and compliance requirements.

Features

1. Permission-Based Bypass Control

• s3:BypassGovernanceRetention: New permission that allows users to bypass governance retention
• Admin Override: Admin users can always bypass governance retention
• Header Detection: Automatic detection of x-amz-bypass-governance-retention header
• Permission Validation: Validates user permissions before allowing bypass

2. Retention Mode Support

• GOVERNANCE Mode: Can be bypassed with proper permission and header
• COMPLIANCE Mode: Cannot be bypassed (highest security level)
• Legal Hold: Always blocks operations regardless of permissions

3. Integration Points

• DELETE Operations: Checks governance permissions before object deletion
• PUT Operations: Validates permissions before object overwrite
• Retention Modification: Ensures proper permissions for retention changes

Implementation Details

Core Components

1. Permission Checker

   func (s3a *S3ApiServer) checkGovernanceBypassPermission(r *http.Request, bucket, object string) bool
   

   • Checks if user has s3:BypassGovernanceRetention permission
   • Validates admin status
   • Integrates with existing IAM system

2. Object Lock Permission Validation

   func (s3a *S3ApiServer) checkObjectLockPermissions(r *http.Request, bucket, object, versionId string, bypassGovernance bool) error
   

   • Validates governance bypass permissions
   • Checks retention mode (GOVERNANCE vs COMPLIANCE)
   • Enforces legal hold restrictions

3. IAM Integration

   • Added ACTION_BYPASS_GOVERNANCE_RETENTION constant
   • Updated policy engine with s3:BypassGovernanceRetention action
   • Integrated with existing identity-based access control

Permission Flow

Request with x-amz-bypass-governance-retention: true
        ↓
Check if object is under retention
        ↓
If GOVERNANCE mode:
    ↓
Check if user has s3:BypassGovernanceRetention permission
    ↓
If permission granted: Allow operation
If permission denied: Deny operation
        ↓
If COMPLIANCE mode: Always deny

Configuration

1. Identity-Based Configuration

Add governance bypass permission to user actions in identities.json:

{
  "identities": [
    {
      "name": "governance-admin",
      "credentials": [{"accessKey": "admin123", "secretKey": "secret123"}],
      "actions": [
        "Read:my-bucket/*",
        "Write:my-bucket/*",
        "BypassGovernanceRetention:my-bucket/*"
      ]
    }
  ]
}

2. Bucket Policy Configuration

Grant governance bypass permission via bucket policies:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:BypassGovernanceRetention",
      "Resource": "arn:aws:s3:::bucket/*"
    }
  ]
}

Note: The policy version should use the standard AWS policy version PolicyVersion2012_10_17 constant (which equals "2012-10-17").

Usage Examples

1. Delete Object with Governance Bypass

# User with bypass permission
aws s3api delete-object \
    --bucket my-bucket \
    --key my-object \
    --bypass-governance-retention

# Admin user (always allowed)
aws s3api delete-object \
    --bucket my-bucket \
    --key my-object \
    --bypass-governance-retention

2. Update Object Retention

# Extend retention period (requires bypass permission for governance mode)
aws s3api put-object-retention \
    --bucket my-bucket \
    --key my-object \
    --retention Mode=GOVERNANCE,RetainUntilDate=2025-01-01T00:00:00Z \
    --bypass-governance-retention

3. Bulk Object Deletion

# Delete multiple objects with governance bypass
aws s3api delete-objects \
    --bucket my-bucket \
    --delete file://delete-objects.json \
    --bypass-governance-retention

Error Handling

Permission Errors

• ErrAccessDenied: User lacks s3:BypassGovernanceRetention permission
• ErrGovernanceModeActive: Governance mode protection without bypass
• ErrComplianceModeActive: Compliance mode cannot be bypassed

Example Error Response

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>AccessDenied</Code>
    <Message>User does not have permission to bypass governance retention</Message>
    <RequestId>abc123</RequestId>
    <Resource>/my-bucket/my-object</Resource>
</Error>

Security Considerations

1. Least Privilege Principle

• Grant bypass permission only to users who absolutely need it
• Use bucket-specific permissions rather than global permissions
• Regularly audit users with bypass permissions

2. Compliance Mode Protection

• COMPLIANCE mode objects cannot be bypassed by any user
• Use COMPLIANCE mode for regulatory requirements
• GOVERNANCE mode provides flexibility while maintaining audit trails

3. Admin Privileges

• Admin users can always bypass governance retention
• Ensure admin access is properly secured
• Use admin privileges responsibly

Testing

Unit Tests

# Run governance permission tests
go test -v ./weed/s3api/ -run TestGovernance

# Run all object retention tests
go test -v ./weed/s3api/ -run TestObjectRetention

Integration Tests

# Test with real S3 clients
cd test/s3/retention
go test -v ./... -run TestGovernanceBypass

AWS Compatibility

This implementation provides full AWS S3 compatibility for:

• ✅ x-amz-bypass-governance-retention header support
• ✅ s3:BypassGovernanceRetention permission
• ✅ GOVERNANCE vs COMPLIANCE mode behavior
• ✅ Legal hold enforcement
• ✅ Error responses and codes
• ✅ Bucket policy integration
• ✅ IAM policy integration

Troubleshooting

Common Issues

1. User cannot bypass governance retention

   • Check if user has s3:BypassGovernanceRetention permission
   • Verify the header x-amz-bypass-governance-retention: true is set
   • Ensure object is in GOVERNANCE mode (not COMPLIANCE)

2. Admin bypass not working

   • Verify user has admin privileges in the IAM system
   • Check that object is not under legal hold
   • Ensure versioning is enabled on the bucket

3. Policy not taking effect

   • Verify bucket policy JSON syntax
   • Check resource ARN format
   • Ensure principal has proper format

Future Enhancements

• AWS STS integration for temporary credentials
• CloudTrail-compatible audit logging
• Advanced condition evaluation (IP, time, etc.)
• Integration with external identity providers
• Fine-grained permissions for different retention operations