OIDC / OAuth2-Einrichtung

Diese Anleitung führt Sie durch die Konfiguration von RAMP zur Verwendung von OpenID Connect (OIDC)-Authentifizierung mit gängigen Identitätsanbietern wie Azure AD, Okta, Keycloak oder Auth0.

Was ist OIDC-Authentifizierung?

OpenID Connect (OIDC) ist ein modernes Authentifizierungsprotokoll, das es RAMP ermöglicht, die Benutzerauthentifizierung an den Identitätsanbieter Ihrer Organisation zu delegieren. Vorteile:

• Single Sign-On (SSO) – Benutzer melden sich einmal für alle Anwendungen an
• Zentrale Benutzerverwaltung – Benutzer an einem Ort verwalten
• Erhöhte Sicherheit – MFA, bedingter Zugriff und Sicherheitsrichtlinien werden von Ihrem IdP verwaltet
• Keine Passwortspeicherung – RAMP speichert oder verarbeitet niemals Passwörter

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Einen OIDC-konformen Identitätsanbieter (Azure AD, Okta, Keycloak, Auth0 usw.)
• Administratorzugriff zur Registrierung von Anwendungen in Ihrem IdP
• RAMP-Backend-API bereitgestellt und zugänglich
• RAMP-Frontend bereitgestellt oder in der Entwicklung laufend

Schnellstart

1. RAMP in Ihrem Identitätsanbieter registrieren

   Sie müssen RAMP als Anwendung/Client in Ihrem Identitätsanbieter registrieren.

   Erforderliche Einstellungen:

   • Anwendungstyp: Öffentlich (SPA/Browser-Anwendung)
   • Grant-Typ: Authorization Code mit PKCE
   • Redirect-URI: https://your-ramp-domain.com/_auth/callback
   • Post-Logout-Redirect-URI: https://your-ramp-domain.com
   • Scopes: openid profile email

   Notieren Sie sich nach der Registrierung diese Werte:

   • Authority-URL (z. B. https://login.microsoftonline.com/{tenant-id}/v2.0)
   • Client-ID (z. B. abc123-def456-ghi789)

2. RAMP-Frontend konfigurieren

   Erstellen oder aktualisieren Sie .env.local (Entwicklung) oder .env.production in src/RAMP.Web/:

   Produktion

   # OIDC-Authentifizierung aktivieren
   VITE_OIDC_ENABLED=true
   
   # Authority-URL Ihres Identitätsanbieters
   VITE_OIDC_AUTHORITY=https://your-idp.com
   
   # Client-ID aus Schritt 1
   VITE_OIDC_CLIENT_ID=your-client-id
   
   # Redirect-URI (muss mit der IdP-Registrierung übereinstimmen)
   VITE_OIDC_REDIRECT_URI=https://your-ramp-domain.com/_auth/callback
   
   # Optional: Post-Logout-Redirect
   VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://your-ramp-domain.com
   
   # Optional: Benutzerdefinierte Scopes (Standard: "openid profile email")
   VITE_OIDC_SCOPE=openid profile email

   Entwicklung

   VITE_OIDC_ENABLED=true
   VITE_OIDC_AUTHORITY=https://your-idp.com
   VITE_OIDC_CLIENT_ID=your-dev-client-id
   VITE_OIDC_REDIRECT_URI=http://localhost:5173/_auth/callback
   VITE_OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:5173

3. RAMP-Backend konfigurieren (Optional)

   Das Backend benötigt eine minimale Konfiguration für OIDC, da die Authentifizierung im Frontend erfolgt. Sie sollten jedoch die JWT-Validierungseinstellungen konfigurieren.

   Aktualisieren Sie appsettings.json:

   {
     "Jwt": {
       "Secret": "YourSecretKeyAtLeast32CharactersLong!",
       "Issuer": "RAMP.API",
       "Audience": "RAMP.Web",
       "AccessTokenExpirationMinutes": 480,
       "RefreshTokenExpirationDays": 30
     }
   }

   Hinweis

   RAMP stellt nach der Validierung des OIDC-Tokens eigene JWTs aus. Jwt:Secret sollte sicher über User Secrets (Entwicklung) oder Azure Key Vault (Produktion) gespeichert werden.

4. Konfiguration testen

   RAMP-Frontend starten:

   cd src/RAMP.Web
   npm run dev

   Navigieren Sie in Ihrem Browser zu RAMP:

   • Entwicklung: http://localhost:5173
   • Produktion: https://your-ramp-domain.com

   Erwarteter Ablauf:

   • Sie werden zur Anmeldeseite Ihres Identitätsanbieters weitergeleitet
   • Melden Sie sich mit Ihren Anmeldedaten an
   • Nach erfolgreicher Authentifizierung werden Sie zurück zu RAMP weitergeleitet
   • Sie sollten das RAMP-Dashboard mit Ihrem Namen/Ihrer E-Mail sehen

   Im Browser-Konsolenfenster überprüfen:

   • Entwicklertools öffnen und die Konsole prüfen
   • Es sollten erfolgreiche Authentifizierungsmeldungen erscheinen
   • Keine CORS- oder Weiterleitungsfehler

---

Anbieterspezifische Beispiele

Azure AD

Authority-URL:

https://login.microsoftonline.com/{tenant-id}/v2.0

Konfiguration:

VITE_OIDC_AUTHORITY=https://login.microsoftonline.com/your-tenant-id/v2.0
VITE_OIDC_CLIENT_ID=your-application-client-id
VITE_OIDC_SCOPE=openid profile email User.Read

App-Registrierung:

1. Azure Portal -> Entra ID -> App-Registrierungen -> Neue Registrierung
2. Redirect-URI hinzufügen: https://your-ramp-domain.com/_auth/callback
3. Authentifizierung -> “Zugriffstoken” und “ID-Token” aktivieren
4. API-Berechtigungen -> User.Read aus Microsoft Graph hinzufügen

Okta

Authority-URL:

https://your-domain.okta.com/oauth2/default

Konfiguration:

VITE_OIDC_AUTHORITY=https://your-domain.okta.com/oauth2/default
VITE_OIDC_CLIENT_ID=your-client-id

App-Einrichtung:

1. Okta Admin-Konsole -> Anwendungen -> App-Integration erstellen
2. Anmeldemethode: OIDC
3. Anwendungstyp: Single-Page-Anwendung
4. Grant-Typ: Authorization Code
5. Redirect-URI hinzufügen

Keycloak

Authority-URL:

https://keycloak.your-domain.com/realms/your-realm

Konfiguration:

VITE_OIDC_AUTHORITY=https://keycloak.your-domain.com/realms/your-realm
VITE_OIDC_CLIENT_ID=ramp-web

Client-Einrichtung:

1. Keycloak Admin-Konsole -> Clients -> Client erstellen
2. Client-Typ: OpenID Connect
3. Client-ID: ramp-web
4. Client-Authentifizierung: AUS (öffentlicher Client)
5. Gültige Redirect-URIs: https://your-ramp-domain.com/_auth/callback
6. Web-Ursprünge: https://your-ramp-domain.com

Auth0

Authority-URL:

https://your-tenant.auth0.com

Konfiguration:

VITE_OIDC_AUTHORITY=https://your-tenant.auth0.com
VITE_OIDC_CLIENT_ID=your-client-id

Anwendungseinrichtung:

1. Auth0 Dashboard -> Anwendungen -> Anwendung erstellen
2. “Single Page Web Applications” auswählen
3. Einstellungen -> Erlaubte Callback-URLs: https://your-ramp-domain.com/_auth/callback
4. Erlaubte Abmelde-URLs: https://your-ramp-domain.com
5. Erlaubte Web-Ursprünge: https://your-ramp-domain.com

---

Fehlerbehebung

Fehler “Ungültige redirect_uri”

Problem: Der Identitätsanbieter lehnt die Redirect-URI ab.

Lösung:

• Sicherstellen, dass VITE_OIDC_REDIRECT_URI exakt mit dem übereinstimmt, was in Ihrem IdP registriert ist
• Protokoll prüfen (http vs. https)
• Portnummer prüfen (:5173 für Entwicklung, weglassen für Produktion bei Standardports)
• Abschließende Schrägstriche prüfen (manche IdPs sind streng)
• Groß-/Kleinschreibung prüfen

Fehler “Client nicht gefunden”

Problem: Der Identitätsanbieter erkennt die Client-ID nicht.

Lösung:

• Sicherstellen, dass VITE_OIDC_CLIENT_ID exakt übereinstimmt (Groß-/Kleinschreibung beachten)
• Sicherstellen, dass der Client/die Anwendung in Ihrem IdP aktiviert ist
• Prüfen, ob Sie die richtige Umgebung verwenden (Entwicklungs- vs. Produktions-Client-ID)

CORS-Fehler im Browser-Konsolenfenster

Problem: Browser blockiert Anfragen aufgrund der CORS-Richtlinie.

Lösung:

• Sicherstellen, dass Ihr IdP Anfragen vom RAMP-Ursprung erlaubt
• In der IdP-Konfiguration https://your-ramp-domain.com zu erlaubten Ursprüngen hinzufügen
• Für die Entwicklung http://localhost:5173 zu erlaubten Ursprüngen hinzufügen

Endlose Weiterleitungsschleife

Problem: Browser leitet ständig zwischen RAMP und IdP weiter.

Lösung:

• Prüfen, dass VITE_OIDC_SCOPE openid enthält
• Sicherstellen, dass der Client für den Authorization Code-Flow konfiguriert ist
• Browser-Cookies und lokalen Speicher leeren
• Browser-Konsole auf detaillierte Fehlermeldungen prüfen

Benutzer authentifiziert, aber ohne Rollen

Problem: Benutzer meldet sich erfolgreich an, hat aber keine Berechtigungen in RAMP.

Lösung:

Dieses Verhalten ist für OIDC-Erstbenutzer erwartet. Ein Administrator muss Rollen zuweisen:

1. Als Administrator anmelden
2. Zu Admin -> Benutzer navigieren
3. Benutzer suchen (nach E-Mail)
4. Rollen zuweisen klicken
5. Geeignete Anwendungsrollen zuweisen

Alternativ können Sie Bootstrap-Administratoren konfigurieren, um bestimmten Benutzern bei der ersten Anmeldung automatisch Rollen zuzuweisen.

---

Sicherheits-Best-Practices

Produktions-Deployment

• HTTPS verwenden – In der Produktion immer TLS/SSL-Zertifikate verwenden
• Redirect-URIs validieren – Nur notwendige Redirect-URIs registrieren
• Scope-Minimierung – Nur die von RAMP benötigten Scopes anfordern (openid profile email)
• Kurze Token-Laufzeiten – Tokens so konfigurieren, dass sie innerhalb einer Stunde ablaufen
• Sichere Client-Registrierung – Geeignete Client-Authentifizierungseinstellungen verwenden
• Fehlgeschlagene Anmeldungen überwachen – Audit-Protokollierung in Ihrem IdP aktivieren

Token-Speicherung

RAMP speichert Tokens im Browser-Sitzungsspeicher, der:

• Beim Schließen des Browser-Tabs/-Fensters geleert wird
• Für andere Websites nicht zugänglich ist
• Nicht auf der Festplatte gespeichert wird

Hinweis

Tokens überleben keinen Browser-Neustart – Benutzer müssen sich erneut anmelden. Dies ist by design aus Sicherheitsgründen so.

---

Benutzerbereitstellung

Automatische Benutzererstellung

Wenn sich ein Benutzer zum ersten Mal über OIDC anmeldet:

1. RAMP erhält Claims von Ihrem Identitätsanbieter (Name, E-Mail, sub)
2. RAMP prüft, ob ein Benutzer mit dieser ProviderSubjectId vorhanden ist
3. Falls nicht, erstellt RAMP automatisch ein neues Benutzerkonto
4. Das Benutzerprofil wird aus den OIDC-Claims gefüllt:
   • sub-Claim -> Eindeutiger Bezeichner
   • email-Claim -> E-Mail-Adresse
   • name oder preferred_username -> Anzeigename

Erforderliche Claims

Ihr Identitätsanbieter muss diese Claims zurückgeben:

Claim	Zweck	Beispiel
sub	Eindeutiger Benutzerbezeichner	248289761001
email	E-Mail-Adresse des Benutzers	john.doe@company.com
name oder preferred_username	Anzeigename	John Doe

Wenn diese Claims fehlen, schlägt die Benutzererstellung fehl.

---

Nächste Schritte

Nach der Konfiguration der OIDC-Authentifizierung:

• MFA-Einrichtungsanleitung – TOTP-basierte Multi-Faktor-Authentifizierung hinzufügen
• Bootstrap-Administratoren-Anleitung – Admin-Rollen automatisch zuweisen
• E-Mail-Einrichtungsanleitung – E-Mails für Passwort-Zurücksetzen aktivieren

---

Verwandte Themen

Authentifizierungsübersicht Alle Authentifizierungsmethoden vergleichen und die richtige wählen

LDAP-Authentifizierung einrichten Authentifizierung gegen Active Directory oder OpenLDAP mit Verzeichnissuche