path: root/share/man/README.md

# Sparkle & Authzd: Authorization at the Edge

## Slide 1: Overview

### What We Built

Two services that work together to provide authorization at the edge:

1. **Sparkled** - Demo application (Go web service)
2. **Authzd** - Authorization daemon (gRPC service implementing Envoy's `ext_authz` API)

### Key Innovation

Authorization decisions happen in Envoy *before* requests reach the application.

This is different from Rails where authorization typically happens inside the app.

---

## Slide 2: The Problem We're Solving

### Traditional Rails Approach

```
+-------------+
|   Browser   |
+------+------+
       |
       | HTTP Request
       v
+-------------+
|    Rails    | <-- Authentication + Authorization happens here
+-------------+
```

### Challenges
- Every app reimplements auth logic
- Hard to enforce consistent policies
- Difficult to audit authorization decisions
- Sensitive tokens handled by application code

---

## Slide 3: Our Solution - Authorization at the Edge

```
            +--------------+
            |  User-Agent  |
            +------+-------+
                   | HTTP Request
                   v
+=========================================+
|        DOCKER IMAGE: Sparkle            |
|                                         |
| +-------------------------------------+ |
| |         ENVOY PROXY (Sparkle)       | |
| |                                     | |
| | 1. OAuth2 Filter (login flow)       | |
| | 2. JWT Filter (validates tokens)    | |
| | 3. Ext_Authz Filter (Go authzd) --+ | |
| | 4. Router (forwards to app)       | | |
| +---------------+-------------------+-+ |
|                 |                   |   |
|                 v                   v   |
|         +-------------+    +----------+ |
|         |  Sparkled   |    | Go Authzd| |
|         |    (App)    |    | (sidecar)| |
|         +-------------+    +----+-----+ |
+==============================|=========+
                               |
                               | gRPC call
                               | (network)
                               v
+==============================+=========+
|        DOCKER IMAGE: Authzd            |
|                                        |
| +------------------------------------+ |
| |        ENVOY PROXY (Remote)        | |
| +------------------+-----------------+ |
|                    |                   |
|                    v                   |
|            +---------------+           |
|            | Rust Authzd   |           |
|            |   (remote)    |           |
|            +---------------+           |
+========================================+
```

---

## Slide 4: Request Flow - First Time User

```
User-Agent     Envoy(Sparkle)     Sparkled       GitLab
   |                |                 |              |
   | GET /dashboard |                 |              |
   |--------------->|                 |              |
   |                |                 |              |
   |                | No auth cookie  |              |
   | 302 Redirect   | detected        |              |
   |<---------------|                 |              |
   |                |                 |              |
   | GET gitlab.com/oauth/authorize   |              |
   |----------------------------------|------------->|
   |                                  |              |
   | (User logs in)                   |              |
   |                                  |              |
   | 302 /callback?code=xyz           |              |
   |<---------------------------------|------------->|
   |                |                 |              |
   | GET /callback  |                 |              |
   |--------------->|                 |              |
   |                | Exchange code   |              |
   |                |-----------------|------------->|
   |                |                 |              |
   |                | ID token +      |              |
   |                | Access token    |              |
   |                |<----------------|--------------|
   |                |                 |              |
   | Set cookies    |                 |              |
   | 302 /dashboard |                 |              |
   |<---------------|                 |              |
```

---

## Slide 5: Request Flow - Authenticated User

```
User-Agent  Envoy(Sparkle)       Go Authzd    Rust Authzd
   |                |                 |              |
   | GET /dashboard |                 |              |
   | (with cookies) |                 |              |
   |--------------->|                 |              |
   |                |                 |              |
   |                | 1. Extract      |              |
   |                |    ID token     |              |
   |                |                 |              |
   |                | 2. Validate JWT |              |
   |                |    ✓ Valid      |              |
   |                |                 |              |
   |                | 3. Check authz  |              |
   |                |---------------->|              |
   |                |                 |              |
   |                |                 | gRPC call    |
   |                |                 | (network)    |
   |                |                 |------------->|
   |                |                 |              |
   |                |                 | Evaluate     |
   |                |                 | policies     |
   |                |                 |<-------------|
   |                |                 |              |
   |                |  gRPC: OK       |              |
   |                |<----------------|              |
   |                |   + URT token in headers       |
   |                |                                |
   | 200 OK         |                                |
   | Dashboard HTML |                                |
   |<---------------|                                |
```

---

## Slide 6: The Dual Authzd Architecture

### Current: Go Sidecar + Rust Remote

```
+-----------------------------------------------------+
|                  Docker Container                   |
|                                                     |
|  +---------+    +--------------+    +----------+    |
|  |  Envoy  |--->| Go Authzd    |    | Sparkled |    |
|  | (local) |    |  (sidecar)   |    |   (App)  |    |
|  +---------+    +------+-------+    +----------+    |
|                        |                            |
+------------------------|----------------------------+
                         |
                         | gRPC call (fallback)
                         v
                 +---------------+
                 | ENVOY PROXY   |
                 |   (remote)    |
                 +-------+-------+
                         |
                         v
                 +---------------+
                 | Rust Authzd   |
                 |   (remote)    |
                 +---------------+
```

### Future: In-Process Library + Remote Fallback

```
+-----------------------------------------------------+
|                  Docker Container                   |
|                                                     |
|  +---------+    +--------------+    +----------+   |
|  |  Envoy  |--->| Rust Authzd  |    | Sparkled |  |
|  | (local) |    |  (library)   |    |   (App)  |   |
|  +---------+    +------+-------+    +----------+   |
|                        |                            |
+------------------------|----------------------------+
                         |
                         | HTTP call (fallback)
                         v
                 +---------------+
                 | Rust Authzd   |
                 |   (remote)    |
                 +---------------+
```

### Benefits:
1. **Local authzd** - Fast, no network latency, basic policies
2. **Remote authzd** - Centralized policy management, complex rules
3. **Future**: In-process library eliminates gRPC overhead

---

## Slide 7: Envoy Configuration Deep Dive

### ⚠️ **Architecture Evolution Note**
The OAuth2 and JWT filters shown below may be removed in future versions:
- **Option 1**: Move to Rust authzd's Envoy configuration
- **Option 2**: Implement as code inside Rust authzd
- **Goal**: Replace JWT with URT (Unified Request Token) via ext_authz

### Current Filter Chain (order matters!)

```yaml
http_filters:
  - name: envoy.filters.http.oauth2      # 1. Handle login/logout
  - name: envoy.filters.http.jwt_authn   # 2. Validate tokens
  - name: envoy.filters.http.ext_authz   # 3. Check authorization
  - name: envoy.filters.http.router      # 4. Route to app
```

Each filter processes the request and can:
- Allow it to continue to the next filter
- Return an immediate response (redirect, error, etc.)
- Modify headers before passing along

---

## Slide 8: OAuth2 Filter - Authentication (Current)

### ⚠️ **Future Architecture**
This OIDC authentication may move to Rust authzd for centralized token management.

### Configuration
```yaml
- name: envoy.filters.http.oauth2
  config:
    authorization_endpoint: "https://gitlab.com/oauth/authorize"
    token_endpoint: "https://gitlab.com/oauth/token"
    credentials:
      client_id: "OAUTH_CLIENT_ID"
      cookie_names:
        id_token: id_token
        bearer_token: bearer_token
    pass_through_matcher:  # Skip auth for these paths
      - name: ":path"
        string_match:
          safe_regex:
            regex: ^.+\.(css|js|png)$
```

### What it does:
1. Intercepts unauthenticated requests
2. Manages OAuth2 flow with GitLab
3. Stores tokens in encrypted cookies
4. Handles token refresh automatically

---

## Slide 9: JWT Filter - Token Validation (Current)

### ⚠️ **Future Architecture**
JWT validation may move to authzd, which will:
1. Validate JWT from identity provider
2. **Replace JWT with URT (Unified Request Token)**
3. Inject URT as header via ext_authz response

### Configuration
```yaml
- name: envoy.filters.http.jwt_authn
  providers:
    id_token_provider:
      issuer: https://gitlab.com
      audiences: [OAUTH_CLIENT_ID]
      remote_jwks:
        uri: https://gitlab.com/oauth/discovery/keys
      claim_to_headers:  # Extract claims to headers
        - claim_name: sub
          header_name: x-jwt-claim-sub
        - claim_name: nickname
          header_name: x-jwt-claim-username
```

### Current headers passed to app:
```
x-jwt-claim-sub: 123456
x-jwt-claim-username: john.doe
x-jwt-payload: <base64 encoded JWT>
```

---

## Slide 10: Ext_Authz Filter - Authorization

### The gRPC Call

```
+------------+      CheckRequest       +------------+
|   Envoy    | ---------------------> |   Authzd   |
|            |                        |            |
|            | <--------------------- |            |
+------------+      CheckResponse     +------------+
```

### CheckRequest includes:
```protobuf
message CheckRequest {
  AttributeContext attributes = 1;
}

message AttributeContext {
  Request request = 1;  // HTTP method, path, headers
  // ... context about the request
}
```

### CheckResponse:
```protobuf
message CheckResponse {
  Status status = 1;  // OK or Permission Denied
  // Can add/remove headers
}
```

### **Key Feature: URT Token Injection**
Authzd can inject **URT (Unified Request Token)** headers:
```
x-urt-token: <downscoped_token>
x-user-id: 123456
x-user-groups: ["developers", "maintainers"]
```

---

## Slide 11: Authzd Implementation

### Current Cedar Policy

```cedar
// Allow requests with valid bearer token
permit(principal, action == Action::"check", resource)
when {
  context has bearer_token &&
  context.bearer_token == "valid-token"
};

// Allow static assets
permit(principal, action, resource)
when {
  context has path && 
  context has method && 
  context.method == "GET" && 
  context.path like "*.css"
};

// Allow specific Sparkle endpoints
permit(principal, action, resource)
when {
  context has host && 
  context.host == "sparkle.runway.gitlab.net" &&
  context.path == "/health"
};
```

---

## Slide 12: How Authzd Makes Decisions

```
                    CheckRequest from Envoy
                            |
                            v
                 +---------------------+
                 | Extract from request |
                 | - Bearer token       |
                 | - Path               |
                 | - Method             |
                 | - Host               |
                 +----------+----------+
                            |
                            v
                 +---------------------+
                 | Create Cedar Request |
                 | - Principal: User    |
                 | - Action: check      |
                 | - Resource: resource |
                 | - Context: {token,..}|
                 +----------+----------+
                            |
                            v
                 +---------------------+
                 | Evaluate Policies    |
                 | using Cedar engine   |
                 +----------+----------+
                            |
                    +-------+--------+
                    v                v
               ALLOW (200)      DENY (401)
```

---

## Slide 13: Benefits of This Architecture

### 1. **Separation of Concerns**
   - Envoy handles auth complexity
   - App focuses on business logic
   - Policies managed separately

### 2. **Security**
   - OAuth secrets never reach app
   - Token validation at edge
   - Consistent policy enforcement

### 3. **Performance**
   - Early request rejection
   - No auth overhead in app
   - Local authzd = low latency

### 4. **Flexibility**
   - Easy to add new auth methods
   - Policy changes without app changes
   - Gradual migration path

---

## Slide 14: Demo Scenarios

### Scenario 1: Unauthenticated Access
```bash
curl http://localhost:10000/dashboard
# → 302 Redirect to GitLab login
```

### Scenario 2: Static Asset (No Auth Required)
```bash
curl http://localhost:10000/style.css
# → 200 OK (bypasses auth)
```

### Scenario 3: Authenticated Access
```bash
curl -H "Cookie: id_token=..." http://localhost:10000/dashboard
# → 200 OK (if authorized)
```

### Scenario 4: Invalid Token
```bash
curl -H "Cookie: id_token=expired" http://localhost:10000/dashboard
# → 401 Unauthorized
```

---

## Slide 15: Cedar Policy Language

### Why Cedar?

- **Simple** - Easy to read and write
- **Fast** - Optimized for authorization decisions
- **Safe** - Prevents common policy mistakes
- **Auditable** - Clear decision logs

### Example: Group-based Access
```cedar
permit(
  principal,
  action == Action::"view",
  resource == Resource::"admin_panel"
)
when {
  principal.groups.contains("admins")
};
```

### Example: Time-based Access
```cedar
permit(principal, action, resource)
when {
  context.current_hour >= 9 &&
  context.current_hour < 17  // Business hours only
};
```

---

## Slide 16: Debugging Authorization

### Envoy Access Logs
```json
{
  "app": "envoy",
  "path": "/dashboard",
  "method": "GET",
  "response_code": "401",
  "duration": "5",
  "ext_authz_status": "denied"
}
```

### Authzd Decision Logs
```json
{
  "level": "INFO",
  "message": "Processing HTTP request",
  "method": "GET",
  "path": "/dashboard",
  "decision": "Deny",
  "diagnostics": {
    "reason": "No matching permit policy",
    "policies_evaluated": ["policy0", "policy1"]
  }
}
```

---

## Slide 17: Migration Strategy

### Phase 1: Parallel Running
```
                     +----------+
                +--->|  Rails   | (existing auth)
                |    +----------+
   Browser -----+
                |    +----------+
                +--->|  Envoy   | (new auth)
                     +----------+
```

### Phase 2: Gradual Cutover
- Start with read-only endpoints
- Move non-critical paths
- Finally migrate sensitive operations

### Phase 3: Full Migration
- Remove auth code from Rails
- Rely entirely on edge authorization

---

## Slide 18: Key Takeaways

1. **Authorization at the edge** is more secure and performant

2. **Envoy handles the complex parts** - OAuth flows, token validation

3. **Cedar policies** are easier to audit than code

4. **Separation of concerns** - Apps do business logic, not auth

5. **Gradual migration** is possible - no big bang required

---

## Slide 19: Questions & Discussion

### Architecture Questions
- How does this compare to Rails + Devise?
- What about API authentication?
- How do we handle service-to-service auth?

### Implementation Questions
- How complex can Cedar policies get?
- What's the performance impact?
- How do we test authorization rules?

### Migration Questions
- Which services should adopt this first?
- How do we maintain backwards compatibility?
- What's the rollback strategy?

---

## Appendix A: Running the Demo

### Local Development
```bash
# Terminal 1: Start the services
make run

# Terminal 2: Watch the logs
make logs

# Terminal 3: Test requests
curl -v http://localhost:10000/
```

### Docker Deployment
```bash
# Build the image
make build-image

# Run everything
docker run -p 10000:10000 \
  -e OAUTH_CLIENT_ID=xxx \
  -e OAUTH_CLIENT_SECRET=yyy \
  sparkle:latest
```

---

## Appendix B: Resources

### Documentation
- Envoy ext_authz: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter
- Cedar Language: https://www.cedarpolicy.com/
- Warsaw Accord Design Doc: See pages 3-5

### Code Repositories
- Sparkled: `/sparkled` - Demo application
- Authzd: `/authzd` - Authorization daemon

### Key Files
- `/sparkled/etc/envoy/envoy.yaml` - Envoy configuration
- `/authzd/etc/authzd/policy0.cedar` - Authorization policies
- `/sparkled/share/man/ENVOY.md` - Detailed Envoy documentation