diff options
Diffstat (limited to 'docs/gitlab_cedar_design.md')
| -rw-r--r-- | docs/gitlab_cedar_design.md | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/docs/gitlab_cedar_design.md b/docs/gitlab_cedar_design.md new file mode 100644 index 00000000..353b7e53 --- /dev/null +++ b/docs/gitlab_cedar_design.md @@ -0,0 +1,321 @@ +# GitLab Cedar Authorization Design (Simplified) + +This document describes the simplified design for implementing GitLab-style authorization using Cedar policies in the `authzd` service, without feature or license checks. + +## Overview + +The `authzd` service implements a Policy Decision Point (PDP) that authorizes GitLab REST API operations using Cedar policies based purely on user access levels and project visibility. + +## Architecture + +### Entity Model + +The Cedar entity model mirrors GitLab's core entities: + +- **User**: GitLab users with access levels, admin status, and group memberships +- **Project**: GitLab projects with visibility settings, feature flags, and member lists +- **Namespace/Group**: GitLab groups/namespaces with hierarchical relationships +- **ProjectMembership**: Explicit user-project relationships with access levels +- **GroupMembership**: User-group relationships with inheritance +- **Issue/MergeRequest**: Project resources with ownership and state + +### Access Levels + +GitLab's hierarchical access system is implemented using numeric levels: + +- **Guest** (10): Read-only access to allowed resources +- **Reporter** (20): Can create issues, view CI/CD results +- **Developer** (30): Can push code, create merge requests +- **Maintainer** (40): Can manage project settings and members +- **Owner** (50): Full project control including deletion + +### Policy Structure + +Cedar policies are organized into separate files by concern: + +#### 1. Access Level Policies (`gitlab_simple.cedar`) +- Implements role-based authorization using GitLab's access levels +- Grants permissions based on user access level to projects/groups +- Includes admin override capabilities +- Blocks access for blocked users +- No feature or license checks + +#### 2. Visibility Policies (`gitlab_visibility.cedar`) +- Implements GitLab's public/internal/private visibility model +- Allows public access to public projects +- Restricts internal projects to non-external users +- Limits private projects to members only +- Handles archived project restrictions + +## REST API Integration + +### Request Mapping + +REST API requests are mapped to Cedar authorization checks: + +``` +HTTP Request Cedar Authorization +GET /projects/1 -> can?(User, "read_project", Project::1) +POST /projects/1/issues -> can?(User, "create_issue", Project::1) +PUT /projects/1/settings -> can?(User, "admin_project", Project::1) +DELETE /projects/1 -> can?(User, "destroy_project", Project::1) +``` + +### Context Variables + +HTTP request context is passed to Cedar policies: + +- `method`: HTTP method (GET, POST, PUT, DELETE) +- `path`: Request path +- `host`: Request hostname +- `user_agent`: Client user agent +- `ip_address`: Client IP address + +### Authorization Flow + +1. **Extract Principal**: Identify user from JWT token or API key +2. **Determine Resource**: Extract project/group ID from URL path +3. **Map Action**: Convert HTTP method + path to Cedar action +4. **Build Request**: Create Cedar authorization request +5. **Evaluate**: Execute policies against request +6. **Decision**: Return allow/deny based on policy evaluation + +## Entity Generation + +### GitLab API Integration + +The CLI tool generates Cedar entities by fetching data from GitLab's REST API: + +```rust +// Generate entities for a project +let entities = EntitiesRepository::new(api) + .all("gitlab-org/gitlab") + .await?; +``` + +### Entity Structure + +Entities are generated with simplified attributes for policy evaluation: + +```json +{ + "uid": {"type": "Project", "id": "123"}, + "attrs": { + "name": "GitLab", + "path": "gitlab", + "full_path": "gitlab-org/gitlab", + "visibility": "public", + "archived": false, + "members": ["User::\"1\"", "User::\"2\"", "User::\"3\""] + }, + "parents": [{"type": "Group", "id": "456"}] +} +``` + +User entities include access level and status flags: + +```json +{ + "uid": {"type": "User", "id": "1"}, + "attrs": { + "username": "alice", + "access_level": 40, + "admin": false, + "blocked": false, + "external": false + }, + "parents": [] +} +``` + +## Implementation Components + +### 1. Enhanced GitLab Types + +Updated GitLab API types include all fields needed for authorization: + +- **Project**: visibility, features, access levels, archived status +- **User**: admin, blocked, external, bot flags +- **Group**: visibility, hierarchy, member access levels + +### 2. Cedar Entity Builders + +The `GitLabEntityBuilder` converts GitLab API responses to Cedar entities: + +```rust +impl GitLabEntityBuilder { + pub fn build_project(project: &Project) -> CedarEntity { ... } + pub fn build_user(user: &User) -> CedarEntity { ... } + pub fn build_membership(user_id: u64, project_id: u64, member: &Member) -> CedarEntity { ... } +} +``` + +### 3. Authorization Service + +The `CedarAuthorizer` evaluates requests against policies: + +```rust +pub fn authorize(&self, principal: &str, action: &str, resource: &str, context: &Context) -> Result<Decision> { + let request = Request::new(principal, action, resource, context); + self.authorizer.is_authorized(&request, &self.policies, &self.entities) +} +``` + +## gRPC Service Design + +### Authorization Service + +Implement gRPC endpoints that mirror GitLab's `Ability.allowed?` method: + +```protobuf +service GitLabAuthorization { + rpc IsAllowed(IsAllowedRequest) returns (IsAllowedResponse); + rpc BatchIsAllowed(BatchIsAllowedRequest) returns (BatchIsAllowedResponse); +} + +message IsAllowedRequest { + string user_id = 1; + string action = 2; + string resource_type = 3; + string resource_id = 4; + map<string, string> context = 5; +} + +message IsAllowedResponse { + bool allowed = 1; + string reason = 2; +} +``` + +### Performance Optimizations + +- **Entity Caching**: Cache entities in memory with TTL +- **Policy Compilation**: Pre-compile policies for faster evaluation +- **Batch Operations**: Support bulk authorization checks +- **Connection Pooling**: Pool GitLab API connections + +## Deployment Patterns + +### Standalone PDP + +Deploy `authzd` as a standalone authorization service: + +- Applications make gRPC calls for authorization decisions +- Entities are refreshed periodically from GitLab API +- Policies are updated via configuration management + +### Envoy Integration + +Use as Envoy external authorization service: + +- Intercept HTTP requests at API gateway +- Make real-time authorization decisions +- Block unauthorized requests before reaching application + +### Library Integration + +Embed authorization logic in applications: + +- Link `authzd` as a Rust library +- Perform in-process authorization checks +- Reduce network latency for high-frequency operations + +## Configuration + +### Environment Variables + +```bash +GITLAB_TOKEN=glpat-xxx # GitLab API token +GITLAB_HOST=gitlab.example.com # GitLab instance URL +AUTHZD_PORT=50051 # gRPC service port +ENTITY_REFRESH_INTERVAL=300 # Seconds between entity updates +POLICY_PATH=/etc/authzd # Path to Cedar policy files +``` + +### Policy Management + +- Store policies in version control +- Use GitOps for policy deployment +- Implement policy validation in CI/CD +- Support hot-reloading of policy changes + +## Testing Strategy + +### Unit Tests + +- Test individual policy rules +- Verify entity generation accuracy +- Validate API type parsing + +### Integration Tests + +- Test complete authorization flows +- Verify GitLab API integration +- Test gRPC service endpoints + +### Policy Tests + +- Use Cedar's policy testing framework +- Create test scenarios for common GitLab operations +- Validate policy correctness with real GitLab data + +## Security Considerations + +### Token Management + +- Rotate GitLab API tokens regularly +- Use least-privilege tokens for entity generation +- Secure token storage in production + +### Entity Data + +- Sanitize sensitive data in entities +- Implement data retention policies +- Audit entity access and modifications + +### Policy Security + +- Validate policies before deployment +- Implement policy signing/verification +- Monitor for policy conflicts or errors + +## Migration Strategy + +### Phase 1: Read-Only Operations + +- Implement authorization for GET requests +- Test with non-critical projects +- Validate performance and accuracy + +### Phase 2: Write Operations + +- Add support for POST/PUT/DELETE operations +- Implement fine-grained permissions +- Roll out to production gradually + +### Phase 3: Advanced Features + +- Add support for custom roles +- Implement audit logging +- Add policy analytics and monitoring + +## Monitoring and Observability + +### Metrics + +- Authorization request rate and latency +- Policy evaluation time +- Entity refresh success/failure rates +- Cache hit/miss ratios + +### Logging + +- Log all authorization decisions +- Include request context and policy evaluation details +- Implement structured logging for analysis + +### Alerting + +- Alert on authorization failures +- Monitor entity refresh errors +- Track policy evaluation performance
\ No newline at end of file |