Technische Dokumentation

Diese Seite ist in Bearbeitung.

1. Projektstruktur

In Bearbeitung

2. Authentifizierung

Die Authentifizierung im BKT-System erfolgt über mehrere Stufen und nutzt sowohl das externe KT-System (kompetenztest.de) als auch eigene JWT Tokens für die Session-Verwaltung.

Erläuterung des Authentifizierungsprozesses im Frontend und Backend:

1. Frontend Login-Prozess

• Es gibt zwei Arten von Logins: SCHOOL und ADMIN
• Die Authentifizierung beginnt mit einem KT-Token (kompetenztest.de Token)

2. Backend Auth Service

// Datei: backend/src/modules/auth/auth.service.ts
@Injectable()
export class AuthService {
    async authenticate(ktToken: string, type: AuthType): Promise<TokenResponseDto> {
        // 1. Verifiziere KT-Token
        let authResponse: KtAuthResponse;
        try {
            authResponse = await this.verifyToken(ktToken, type);
        } catch (err: any) {
            // Fehlerbehandlung für ungültige Tokens
            if (err instanceof AxiosError) {
                if (err.response) {
                    const message = err.response.data?.status_message;
                    throw new UnauthorizedException(message);
                }
                // ... weitere Fehlerbehandlung
            }
        }

        // 2. Prüfe Auth Response
        if (authResponse.status === false) {
            throw new UnauthorizedException(authResponse.status_message);
        }

        // 3. Erstelle JWT Token
        const payload = {
            sub: type === AuthType.Admin ? authResponse.user_id : authResponse.id,
            type: type,
            ktToken: ktToken,
        };

        // 4. Sende JWT Token zurück
        return {
            access_token: await this.jwtService.signAsync(payload),
        };
    }

    private async verifyToken(ktToken: string, type: AuthType) {
        // Token-Header basierend auf Type
        const tokenHeaderName = type === AuthType.School ? 'X-API-KEY-SCHOOL' : 'X-API-KEY-USER';

        const headers = {};
        headers[tokenHeaderName] = ktToken;

        // Optional: Hostname Header
        if (this.ktAuthHostname) {
            headers['Host'] = this.ktAuthHostname;
        }

        // Verifiziere Token gegen KT Auth System
        const response = await lastValueFrom(
            this.httpService.get<KtAuthResponse>(this.ktAuthUrl, {
                headers: headers,
            })
        );

        return response.data;
    }
}

3. Authentifizierungsfluss:

• Frontend sendet KT-Token an /auth/login
• Backend verifiziert Token gegen KT-Auth-System
• Bei erfolgreicher Verifizierung wird JWT Token generiert
• JWT Token wird ans Frontend zurückgesendet
• Frontend speichert JWT Token und nutzt ihn für weitere Requests

4. JWT Verwendung:

• Jeder API Request vom Frontend enthält den JWT Token im Authorization Header
• Backend validiert JWT Token mit AuthGuard
• Token enthält Informationen über:
  • Benutzer ID (sub)
  • Token Typ (SCHOOL oder ADMIN)
  • Original KT-Token

5. Guards im Backend:

@UseGuards(AuthGuard, SchoolGuard) // Beispiel für geschützte Route
@Controller('registrations')
export class RegistrationController {
    // ... Controller Logik
}

6. Frontend API Store:

// Beispiel für API Konfiguration im Frontend
const httpClient = axios.create({
    baseURL: import.meta.env.VITE_API_BASEURL,
    headers: {
        'Content-Type': 'application/json',
    },
});

// Automatisches Hinzufügen des JWT Tokens
httpClient.interceptors.request.use((config) => {
    const token = getStoredToken();
    if (token) {
        config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
});

Der Prozess stellt sicher, dass:

1. Nur authentifizierte Benutzer Zugriff haben
2. Verschiedene Benutzertypen (SCHOOL/ADMIN) unterschiedliche Rechte haben
3. Die Kommunikation mit dem KT-System sicher ist
4. Sessions über JWT Tokens verwaltet werden

3. Datenbankschema