c77_rbac/TUTORIAL-P1.md

# c77_rbac Complete Hands-On Tutorial - Part 1: Getting Started

Welcome to the comprehensive tutorial for the c77_rbac PostgreSQL extension! This multi-part tutorial will walk you through every aspect of setting up and using database-level authorization, from installation to advanced real-world scenarios.

**Tutorial Structure:**
- **Part 1: Getting Started** (this document) - Prerequisites, installation, and basic setup
- **Part 2: Building the TechCorp Database** - Creating realistic company data and schema
- **Part 3: Implementing RBAC** - Setting up roles, features, and permissions
- **Part 4: Row-Level Security** - Applying sophisticated access controls
- **Part 5: Testing and Validation** - Comprehensive security testing
- **Part 6: Advanced Features** - Bulk operations, web integration, and monitoring

By the end of this complete tutorial, you'll have:
- ✅ Installed and configured c77_rbac
- ✅ Created a complete multi-department company system
- ✅ Implemented role-based access control with row-level security
- ✅ Tested various permission scenarios
- ✅ Integrated with a web application framework
- ✅ Set up monitoring and troubleshooting

## Prerequisites

- PostgreSQL 14+ installed and running
- Basic SQL knowledge
- Command line access
- Superuser access to PostgreSQL

## Tutorial Overview

We'll build a complete **TechCorp Employee Management System** with these features:
- Multiple departments (Engineering, Sales, HR, Finance)
- Different user roles (Admin, Manager, Employee, Contractor)
- Secure document sharing
- Project management with team access
- Expense tracking with approval workflows

---

## Chapter 1: Installation and Basic Setup

### Step 1: Verify PostgreSQL Installation

```bash
# Check PostgreSQL version
psql --version
# Should show PostgreSQL 14 or later

# Test connection
sudo -u postgres psql -c "SELECT version();"
```

### Step 2: Create Tutorial Database

```bash
# Connect as postgres superuser
sudo -u postgres psql

# Create our tutorial database
CREATE DATABASE techcorp_tutorial;

# Create application user
CREATE USER techcorp_app WITH PASSWORD 'secure_tutorial_password';

# Connect to our tutorial database
\c techcorp_tutorial
```

### Step 3: Install c77_rbac Extension

First, copy the extension files (assuming you have them):

```bash
# Copy extension files to PostgreSQL directory
# (Adjust paths based on your PostgreSQL version)
sudo cp c77_rbac.control /usr/share/postgresql/14/extension/
sudo cp c77_rbac--1.1.sql /usr/share/postgresql/14/extension/
```

Now install the extension:

```sql
-- Install the extension
CREATE EXTENSION c77_rbac;

-- Verify installation
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';
-- Should show: c77_rbac | 1.1

-- Grant necessary privileges to application user
GRANT CONNECT ON DATABASE techcorp_tutorial TO techcorp_app;
GRANT CREATE ON DATABASE techcorp_tutorial TO techcorp_app;
GRANT USAGE ON SCHEMA public TO techcorp_app;
GRANT CREATE ON SCHEMA public TO techcorp_app;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO techcorp_app;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO techcorp_app;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO techcorp_app;

-- Set default privileges
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON TABLES TO techcorp_app;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT EXECUTE ON FUNCTIONS TO techcorp_app;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT USAGE, SELECT ON SEQUENCES TO techcorp_app;
```

### Step 4: Verify RBAC Installation

```sql
-- Check RBAC tables were created
\dt public.c77_rbac_*

-- Check RBAC functions are available
\df public.c77_rbac_*

-- Test basic functionality
SELECT public.c77_rbac_grant_feature('test_role', 'test_feature');
SELECT public.c77_rbac_assign_subject('test_user', 'test_role', 'global', 'all');
SELECT public.c77_rbac_can_access('test_feature', 'test_user', 'global', 'all');
-- Should return: true

-- Clean up test data
SELECT public.c77_rbac_revoke_subject_role('test_user', 'test_role', 'global', 'all');
SELECT public.c77_rbac_revoke_feature('test_role', 'test_feature');
```

**✅ Checkpoint 1:** You should now have c77_rbac installed and working!

### Important: Switch to Application User

From this point forward in the tutorial, you should work as the `techcorp_app` user, not as the postgres superuser. This simulates real-world usage where your application connects with limited privileges.

```bash
# Exit current session if needed
\q

# Connect as the application user
psql -d techcorp_tutorial -U techcorp_app -W
# Enter the password: secure_tutorial_password

---

## What's Next?

In **Part 2**, we'll create the complete TechCorp database schema with:
- Multiple departments and users
- Projects and team structures
- Document management with security levels
- Expense tracking system
- Realistic sample data

**Continue to [Part 2: Building the TechCorp Database](TUTORIAL-Part2.md)**

---

## Quick Reference

### Key Extension Files
- `c77_rbac.control` - Extension metadata
- `c77_rbac--1.1.sql` - Main installation script
- `c77_rbac--1.0--1.1.sql` - Upgrade script (if upgrading from v1.0)

### Basic Commands
```sql
-- Create extension
CREATE EXTENSION c77_rbac;

-- Check installation
SELECT extname, extversion FROM pg_extension WHERE extname = 'c77_rbac';

-- Basic test
SELECT public.c77_rbac_can_access('feature', 'user', 'scope_type', 'scope_id');
```

### Troubleshooting Installation

If you encounter issues:

1. **Permission denied copying files**: Use `sudo` for file operations
2. **Extension directory not found**: Check your PostgreSQL version and paths
3. **Extension creation fails**: Verify files are in correct location with proper permissions

For detailed troubleshooting, see the [INSTALL.md](INSTALL.md) guide.