Zugriffskontrolle

Unternehmensgerechte Zugriffskontrolle für KI-Agenten mithilfe von adk-auth.

Übersicht

adk-auth bietet rollenbasierte Zugriffskontrolle (RBAC) mit Audit-Protokollierung und SSO-Unterstützung für ADK-Agenten. Es ermöglicht sichere, feingranulare Kontrolle darüber, welche Benutzer auf welche Tools zugreifen können.

Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        Agent Request                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     SSO Token Validation                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ Google      │  │ Azure AD    │  │ OIDC Discovery          │  │
│  │ Provider    │  │ Provider    │  │ (Okta, Auth0, etc)     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                          │                                       │
│                   ┌──────┴──────┐                                │
│                   │ JWKS Cache  │  ← Auto-refresh keys          │
│                   └─────────────┘                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ TokenClaims
┌─────────────────────────────────────────────────────────────────┐
│                       Claims Mapper                              │
│                                                                  │
│    IdP Groups          →        adk-auth Roles                  │
│    ─────────────────────────────────────────                    │
│    "AdminGroup"        →        "admin"                         │
│    "DataAnalysts"      →        "analyst"                         │
│    (default)           →        "viewer"                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ Roles
┌─────────────────────────────────────────────────────────────────┐
│                      Access Control                              │
│                                                                  │
│    Role: admin                                                   │
│    ├── allow: AllTools                                          │
│    └── allow: AllAgents                                          │
│                                                                  │
│    Role: analyst                                                 │
│    ├── allow: Tool("search")                                    │
│    ├── allow: Tool("summarize")                                 │
│    └── deny:  Tool("code_exec")  ← Deny takes precedence        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼ Check Result
┌─────────────────────────────────────────────────────────────────┐
│                      Audit Logging                               │
│                                                                  │
│    {"user":"alice","resource":"search","outcome":"allowed"}     │
│    {"user":"bob","resource":"exec","outcome":"denied"}          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Tool Execution                               │
│               (only if access granted)                          │
└─────────────────────────────────────────────────────────────────┘

Entwurfsprinzipien

1. Verweigerung hat Vorrang

Wenn eine Rolle sowohl Erlaubnis- als auch Verweigerungsregeln hat, gewinnt die Verweigerung immer:

let role = Role::new("limited")
    .allow(Permission::AllTools)      // Alles erlauben...
    .deny(Permission::Tool("admin")); // ...außer admin

// Ergebnis: Kann auf jedes Tool ZUGREIFEN, AUSSER "admin"

2. Multi-Rollen-Vereinigung

Benutzer mit mehreren Rollen erhalten die Vereinigung der Berechtigungen, aber Verweigerungsregeln aus jeder Rolle gelten weiterhin:

let ac = AccessControl::builder()
    .role(reader)    // erlauben: search
    .role(writer)    // erlauben: write
    .assign("alice", "reader")
    .assign("alice", "writer")
    .build()?;

// Alice kann sowohl auf "search" ALS AUCH auf "write" zugreifen

3. Explizit vor Implizit

Berechtigungen sind explizit – standardmäßig wird kein Zugriff gewährt:

let role = Role::new("empty");
// Diese Rolle gewährt KEINE Berechtigungen

ac.check("user", &Permission::Tool("anything")); // → Verweigert

4. Trennung von Authentifizierung und Autorisierung

• Authentifizierung (SSO): Überprüft, WER der Benutzer ist (via JWT)
• Autorisierung (RBAC): Bestimmt, WORAUF sie zugreifen können

// Authentifizierung: JWT validieren, Claims extrahieren
let claims = provider.validate(token).await?;

// Autorisierung: spezifische Berechtigung prüfen
ac.check(&claims.sub, &Permission::Tool("search"))?;

// Kombiniert: SsoAccessControl erledigt beides
sso.check_token(token, &permission).await?;

Installation

[dependencies]
adk-auth = "0.2.0"

# Für SSO/OAuth-Unterstützung
adk-auth = { version = "0.2.0", features = ["sso"] }

Kernkomponenten

Berechtigung

pub enum Permission {
    Tool(String),     // Spezifisches Tool nach Name
    AllTools,         // Wildcard: alle Tools
    Agent(String),    // Spezifischer Agent nach Name  
    AllAgents,        // Wildcard: alle Agents
}

Rolle

let analyst = Role::new("analyst")
    .allow(Permission::Tool("search".into()))
    .allow(Permission::Tool("summarize".into()))
    .deny(Permission::Tool("code_exec".into()));

Zugriffskontrolle

let ac = AccessControl::builder()
    .role(admin)
    .role(analyst)
    .assign("alice@company.com", "admin")
    .assign("bob@company.com", "analyst")
    .build()?;

// Berechtigung prüfen
ac.check("bob@company.com", &Permission::Tool("search".into()))?;

Geschütztes Tool

Umschließt ein Tool mit automatischer Berechtigungsprüfung:

use adk_auth::ToolExt;

let protected = my_tool.with_access_control(Arc::new(ac));

// Bei Ausführung wird die Berechtigung vor dem Start geprüft
protected.execute(ctx, args).await?;

Auth-Middleware

Schützt mehrere Tools im Batch-Modus:

let middleware = AuthMiddleware::new(ac);
let protected_tools = middleware.protect_all(tools);

SSO-Integration

Unterstützte Anbieter

TokenClaims

Aus validierten JWTs extrahierte Claims:

pub struct TokenClaims {
    pub sub: String,              // Subjekt (Benutzer-ID)
    pub email: Option<String>,    // E-Mail
    pub name: Option<String>,     // Anzeigename
    pub groups: Vec<String>,      // IdP-Gruppen
    pub roles: Vec<String>,       // IdP-Rollen
    pub hd: Option<String>,       // Von Google gehostete Domain
    pub tid: Option<String>,      // Azure Mandanten-ID
    // ... weitere standardmäßige OIDC-Ansprüche
}

ClaimsMapper

Ordnet IdP-Gruppen adk-auth-Rollen zu:

let mapper = ClaimsMapper::builder()
    .map_group("AdminGroup", "admin")
    .map_group("Users", "viewer")
    .default_role("guest")
    .user_id_from_email()
    .build();

SsoAccessControl

Kombiniert SSO-Validierung mit RBAC in einem Aufruf:

let sso = SsoAccessControl::builder()
    .validator(GoogleProvider::new("client-id"))
    .mapper(mapper)
    .access_control(ac)
    .audit_sink(audit)
    .build()?;

// Token validieren + Berechtigung prüfen + Audit-Protokoll
let claims = sso.check_token(token, &Permission::Tool("search".into())).await?;

Audit-Protokollierung

FileAuditSink

let audit = FileAuditSink::new("/var/log/adk/audit.jsonl")?;
let middleware = AuthMiddleware::with_audit(ac, audit);

Ausgabeformat (JSONL)

{"timestamp":"2025-01-01T10:30:00Z","user":"bob","session_id":"sess-123","event_type":"tool_access","resource":"search","outcome":"allowed"}
{"timestamp":"2025-01-01T10:30:01Z","user":"bob","session_id":"sess-123","event_type":"tool_access","resource":"code_exec","outcome":"denied"}

Benutzerdefinierte Audit-Sink

use adk_auth::{AuditSink, AuditEvent, AuthError};
use async_trait::async_trait;

pub struct DatabaseAuditSink { /* ... */ }

#[async_trait]
impl AuditSink for DatabaseAuditSink {
    async fn log(&self, event: AuditEvent) -> Result<(), AuthError> {
        // In Datenbank einfügen
        sqlx::query("INSERT INTO audit_log ...")
            .bind(event.user)
            .bind(event.resource)
            .execute(&self.pool)
            .await?;
        Ok(())
    }
}

Beispiele

# Core RBAC
cargo run --example auth_basic          # Rollenbasierte Zugriffskontrolle
cargo run --example auth_audit          # Audit-Protokollierung

# SSO (erfordert --features sso)
cargo run --example auth_sso --features sso     # Vollständiger SSO-Ablauf
cargo run --example auth_jwt --features sso     # JWT-Validierung
cargo run --example auth_oidc --features sso    # OIDC-Erkennung
cargo run --example auth_google --features sso  # Google Identity

Best Practices für die Sicherheit

Fehlerbehandlung

use adk_auth::{AccessDenied, AuthError};
use adk_auth::sso::TokenError;

// RBAC-Fehler
match ac.check("user", &Permission::Tool("admin".into())) {
    Ok(()) => { /* Zugriff gewährt */ }
    Err(AccessDenied { user, permission }) => {
        eprintln!("Verweigert: {} kann nicht auf {} zugreifen", user, permission);
    }
}

// SSO-Fehler
match provider.validate(token).await {
    Ok(claims) => { /* Token gültig */ }
    Err(TokenError::Expired) => { /* Token abgelaufen */ }
    Err(TokenError::InvalidSignature) => { /* Signatur ungültig */ }
    Err(TokenError::InvalidIssuer { expected, actual }) => { /* falscher Aussteller */ }
    Err(e) => { /* anderer Fehler */ }
}

---

Zurück: ← Evaluierung | Weiter: Entwicklungsrichtlinien →