ADFS Authentication einrichten

Diese Anleitung führt Sie durch die Integration von RAMP mit Active Directory Federation Services (ADFS) für föderierte Authentifizierung und Single Sign-On.

Was ist ADFS-Authentifizierung?

Active Directory Federation Services (ADFS) bietet föderiertes Identitäts- und Zugriffsmanagement über Organisationsgrenzen hinweg. Vorteile:

• Single Sign-On (SSO) – Benutzer authentifizieren sich einmal für mehrere Anwendungen
• Föderierte Authentifizierung – Funktioniert über Organisationen und Vertrauensstellungen hinweg
• Anspruchsbasierter Zugriff – Feinkörnige Autorisierung basierend auf Benutzerattributen
• Integration mit Active Directory – Vorhandenes Benutzerverzeichnis nutzen

Geeignet für: Organisationen mit vorhandener ADFS-Infrastruktur, föderierte Zugriffsszenarien (Partner, Tochtergesellschaften), Compliance-Anforderungen für zentralisierte Authentifizierung, Windows Server-Umgebungen.

Voraussetzungen

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

• ADFS-Server (Version 2016 oder höher für OIDC-Unterstützung)
• Active Directory-Domain
• SSL-Zertifikat auf dem ADFS-Server installiert
• Administratorzugriff auf die ADFS-Verwaltungskonsole
• RAMP-Deployment (Backend + Frontend)

Hinweis

Diese Anleitung verwendet OpenID Connect (OIDC), das ADFS 2016+ erfordert. Für ältere ADFS-Versionen mit WS-Federation wenden Sie sich an Ihren Systemadministrator.

Architekturübersicht

+--------------+                         +--------------+
|   Browser    |---(1) RAMP aufrufen---->|  RAMP Web    |
|   (Client)   |                         |  (Frontend)  |
+--------------+                         +--------------+
      |                                         |
      | (2) Weiterleitung zu ADFS               |
      v                                         |
+--------------+                                |
|     ADFS     |<---(3) Auth-Anfrage------------+
|    Server    |
+--------------+
      |
      | (4) Benutzer authentifiziert sich
      v
+--------------+                         +--------------+
|   Active     |<---(5) Benutzer prüfen--|     ADFS     |
|  Directory   |                         |    Server    |
+--------------+                         +--------------+
                                                |
                  (6) Tokens zurückgeben        |
                  <-----------------------------+

---

Schnellstart

1. ADFS-Anwendung konfigurieren

   Anwendungsgruppe hinzufügen

   1. ADFS-Verwaltungskonsole öffnen (adfs.msc)
   2. Zu Anwendungsgruppen navigieren
   3. Rechtsklick -> Anwendungsgruppe hinzufügen…
   4. Konfiguration:
      • Name: RAMP Application
      • Beschreibung: RAMP Runbook Automation Platform
      • Vorlage: Webbrowser, der auf eine Webanwendung zugreift auswählen
      • Weiter klicken

   Webanwendung konfigurieren

   Native Anwendungseinstellungen:

   • Name: RAMP Web Client
   • Redirect-URI: https://ramp.yourdomain.com/_auth/callback
   • Client-Bezeichner: (Automatisch generiert – für später notieren, z. B. abc123-def456)
   • Weiter klicken

   Zugriffssteuerungsrichtlinie:

   • Alle zulassen auswählen (oder benutzerdefinierte Richtlinie erstellen)
   • Weiter klicken

   Zusammenfassung:

   • Einstellungen überprüfen
   • Weiter -> Schließen klicken

   Weitere Redirect-URIs hinzufügen

   Für Entwicklung und zusätzliche Endpunkte:

   1. Rechtsklick auf RAMP Application -> Eigenschaften
   2. Die Webbrowser-Anwendung auswählen
   3. Bearbeiten… klicken
   4. Hinzufügen klicken, um weitere Redirect-URIs hinzuzufügen:
      • https://ramp.yourdomain.com/_auth/callback (Produktion)
      • http://localhost:5173/_auth/callback (Entwicklung)
      • https://localhost:5173/_auth/callback (Entwicklung mit SSL)
   5. OK -> Übernehmen klicken

2. Claims-Regeln konfigurieren

   Claims-Regeln ordnen Active Directory-Attribute den Tokens zu, die RAMP empfängt.

   LDAP-Attribute als Claims hinzufügen

   1. In der ADFS-Verwaltung Anwendungsgruppen erweitern
   2. Rechtsklick auf RAMP Application -> Eigenschaften
   3. Die Anwendung auswählen -> Bearbeiten… klicken
   4. Zur Registerkarte Ausstellungstransformationsregeln wechseln
   5. Regel hinzufügen… klicken
   6. Regelvorlage: LDAP-Attribute als Claims senden
   7. Weiter klicken
   8. Name der Claimregel: AD-Attribute senden
   9. Attributspeicher: Active Directory
   10. Zuordnungen konfigurieren:

   LDAP-Attribut	Ausgehender Claimtyp
   SAM-Account-Name	Name-ID
   E-Mail-Addresses	E-Mail-Adresse
   Display-Name	Name
   Given-Name	Vorname
   Surname	Nachname
   User-Principal-Name	UPN

   11. Fertig stellen -> OK -> Übernehmen klicken

   Name-ID in Subject-Claim (sub) umwandeln

   OIDC erfordert einen sub-Claim:

   1. Erneut Regel hinzufügen… klicken
   2. Regelvorlage: Eingehenden Claim transformieren
   3. Weiter klicken
   4. Name der Claimregel: Name-ID in sub umwandeln
   5. Eingehender Claimtyp: Name-ID
   6. Ausgehender Claimtyp: Subject (oder sub eingeben, falls nicht in der Dropdown-Liste)
   7. Format der ausgehenden Name-ID: (leer lassen)
   8. Alle Claimwerte weiterleiten: Aktiviert
   9. Fertig stellen -> OK -> Übernehmen klicken

3. ADFS-Konfigurationsdetails abrufen

   OIDC-Discovery-Endpunkt überprüfen

   Browser öffnen und zu folgendem Adresse navigieren:

   https://adfs.yourdomain.com/adfs/.well-known/openid-configuration

   Erwartet: JSON-Dokument mit OIDC-Endpunkten

   Wichtige Werte zum Notieren:

   • Authority: https://adfs.yourdomain.com/adfs
   • Autorisierungsendpunkt: https://adfs.yourdomain.com/adfs/oauth2/authorize
   • Token-Endpunkt: https://adfs.yourdomain.com/adfs/oauth2/token
   • UserInfo-Endpunkt: https://adfs.yourdomain.com/adfs/userinfo

   Client-ID notieren

   Die Client-ID wurde im ersten Schritt automatisch generiert. So finden Sie sie:

   1. ADFS-Verwaltung -> Anwendungsgruppen -> RAMP Application
   2. Auf die Anwendung doppelklicken -> Eigenschaften
   3. Client-Bezeichner kopieren (z. B. abc123-def456-ghi789)

4. RAMP-Frontend konfigurieren

   Erstellen oder aktualisieren Sie .env.production in src/RAMP.Web/:

   Produktion

   # OIDC-Authentifizierung aktivieren
   VITE_OIDC_ENABLED=true
   
   # ADFS OIDC-Konfiguration
   VITE_OIDC_AUTHORITY=https://adfs.yourdomain.com/adfs
   VITE_OIDC_CLIENT_ID=your-client-id-from-step-1
   VITE_OIDC_REDIRECT_URI=https://ramp.yourdomain.com/_auth/callback
   VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://ramp.yourdomain.com
   VITE_OIDC_SCOPE=openid profile email allatclaims
   VITE_OIDC_RESPONSE_TYPE=code
   
   # API-Endpunkt
   VITE_API_BASE_URL=https://ramp.yourdomain.com/api

   Entwicklung

   VITE_OIDC_ENABLED=true
   VITE_OIDC_AUTHORITY=https://adfs.yourdomain.com/adfs
   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
   VITE_OIDC_SCOPE=openid profile email allatclaims

   Konfigurationshinweise:

   • Der allatclaims-Scope fordert alle konfigurierten Claims von ADFS an
   • Der code-Response-Typ verwendet den Authorization Code-Flow (sicherste Option)

5. RAMP-Backend konfigurieren (Optional)

   Das Backend validiert Tokens, benötigt aber keine ADFS-spezifische Konfiguration. Aktualisieren Sie appsettings.json:

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

   Vorsicht

   Speichern Sie Jwt:Secret über User Secrets (Entwicklung) oder Azure Key Vault (Produktion).

6. Integration testen

   RAMP-Frontend starten:

   cd src/RAMP.Web
   npm run dev

   Zu RAMP navigieren:

   • Entwicklung: http://localhost:5173
   • Produktion: https://ramp.yourdomain.com

   Erwarteter Ablauf:

   • Weiterleitung zur ADFS-Anmeldeseite
   • Domain-Anmeldedaten eingeben
   • Nach erfolgreicher Authentifizierung Weiterleitung zurück zu RAMP
   • Name und E-Mail erscheinen in der RAMP-Benutzeroberfläche

   Claims überprüfen:

   1. Browser-Entwicklertools öffnen (F12)
   2. Zur Netzwerk-Registerkarte wechseln
   3. Callback-Anfrage finden (z. B. /_auth/callback?code=...)
   4. JWT-Token prüfen (dekodieren unter jwt.io)
   5. Prüfen, ob Claims enthalten sind: sub, email, name

---

Erweiterte Konfiguration

Gruppenbasierte Zugriffssteuerung

RAMP-Zugriff auf bestimmte Active Directory-Gruppen einschränken:

# PowerShell – Auf dem ADFS-Server ausführen
$rule = @"
@RuleName = "Permit RAMP Users Only"
exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
        Value =~ "RAMP-Users"])
 => issue(Type = "http://schemas.microsoft.com/authorization/claims/permit",
          Value = "true");
"@

Set-AdfsRelyingPartyTrust -TargetName "RAMP Application" `
    -IssuanceAuthorizationRules $rule

Damit können nur Benutzer in der AD-Gruppe “RAMP-Users” sich authentifizieren. Andere werden von ADFS abgewiesen (bevor RAMP erreicht wird).

Multi-Faktor-Authentifizierung (MFA)

MFA für den RAMP-Zugriff vorschreiben:

# MFA für alle RAMP-Benutzer verlangen
Set-AdfsRelyingPartyTrust -TargetName "RAMP Application" `
    -AdditionalAuthenticationRules 'c:[] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn");'

Dies erzwingt eine MFA-Herausforderung (SMS, Microsoft Authenticator usw.) bei der Anmeldung. Die MFA-Richtlinie wird von ADFS durchgesetzt, nicht von RAMP.

Benutzerdefinierte Claims für Rollen

AD-Gruppen auf Rollen-Claims abbilden:

# Beispiel: AD-Gruppe auf Rollen-Claim abbilden
$ruleText = @"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
   Value =~ "(?i)^RAMP-Administrators$"]
 => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
          Value = "Administrator");

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",
   Value =~ "(?i)^RAMP-Coordinators$"]
 => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
          Value = "Coordinator");
"@

Set-AdfsRelyingPartyTrust -TargetName "RAMP Application" `
    -IssuanceTransformRules $ruleText

Token-Laufzeit-Konfiguration

Konfigurieren Sie, wie lange Tokens gültig bleiben:

# Zugriffstoken-Laufzeit auf 1 Stunde (60 Minuten) setzen
Set-AdfsRelyingPartyTrust -TargetName "RAMP Application" `
    -TokenLifetime 60

# "Immer Authentifizierung verlangen" deaktivieren, um Refresh-Tokens zu erlauben
Set-AdfsRelyingPartyTrust -TargetName "RAMP Application" `
    -AlwaysRequireAuthentication $false

Tipp

Empfehlung: Zugriffstoken von 60 Minuten und Refresh-Token von 8 Stunden bieten eine gute Balance zwischen Sicherheit (kurzlebige Tokens) und Benutzerfreundlichkeit (weniger erneute Authentifizierungen).

---

Fehlerbehebung

Fehler bei Redirect-URI-Nichtübereinstimmung

Fehler: AADSTS50011: The reply URL specified in the request does not match

Lösung:

1. Sicherstellen, dass VITE_OIDC_REDIRECT_URI exakt mit der ADFS-Konfiguration übereinstimmt
2. In ADFS prüfen: Anwendungsgruppen -> RAMP -> Eigenschaften -> Bearbeiten -> Redirect-URIs
3. Protokoll prüfen (http vs. https)
4. Abschließende Schrägstriche prüfen (manche Systeme sind streng)
5. Portnummern müssen übereinstimmen (:5173 für Entwicklung, für Standard-HTTPS-Port 443 weglassen)

Ungültige Client-ID-Fehler

Fehler: invalid_client

Lösung:

1. Sicherstellen, dass VITE_OIDC_CLIENT_ID exakt übereinstimmt (Groß-/Kleinschreibung beachten)
2. In ADFS prüfen: Anwendungsgruppen -> RAMP -> Eigenschaften -> Client-Bezeichner
3. Sicherstellen, dass Sie die richtige Umgebung verwenden (Entwicklungs- vs. Produktions-Client-ID)

Fehlende Claims (Keine E-Mail oder Name)

Problem: Benutzer authentifiziert sich, aber E-Mail/Name erscheinen nicht in RAMP.

Lösung:

1. Claims-Regeln überprüfen:

   • ADFS-Verwaltung -> Anwendungsgruppen -> RAMP -> Eigenschaften -> Bearbeiten
   • Auf der Registerkarte Ausstellungstransformationsregeln sollte die Regel “AD-Attribute senden” angezeigt werden

2. AD-Attribute des Benutzers prüfen:

   Get-ADUser -Identity username -Properties mail, displayName, givenName, sn

   Sicherstellen, dass der Benutzer ausgefüllte Attribute hat

3. Claims im Token testen:

   • JWT-Token unter jwt.io dekodieren
   • Prüfen, ob Claims vorhanden sind: email, name, given_name, family_name

4. Fehlende Claims-Regeln hinzufügen (siehe Schritt 2)

CORS-Fehler

Problem: Browser-Konsole zeigt CORS-Richtlinienfehler.

Lösung:

ADFS unterstützt CORS für den Token-Endpunkt standardmäßig nicht. Stellen Sie sicher, dass Sie verwenden:

• Authorization Code-Flow (nicht Implicit Flow)
• OIDC-Bibliothek, die den Token-Austausch serverseitig handhabt
• RAMPs Frontend verwendet die oidc-client-ts-Bibliothek korrekt

In .env überprüfen:

VITE_OIDC_RESPONSE_TYPE=code  # NICHT "id_token" oder "token"

Benutzer authentifiziert, aber keine Rollen in RAMP

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

Lösung:

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

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

Alternativ können Sie Bootstrap-Administratoren konfigurieren, um Admin-Rollen automatisch zuzuweisen.

---

Sicherheits-Best-Practices

Produktions-Checkliste

• Überall HTTPS verwenden – RAMP und ADFS
• Gültige SSL-Zertifikate – Von einer vertrauenswürdigen CA (nicht selbstsigniert)
• Kurze Token-Laufzeiten – 60 Minuten für Zugriffstoken
• MFA aktivieren – Für alle Benutzer oder sensible Rollen
• Gruppenbasierte Zugriffssteuerung – Auf autorisierte AD-Gruppen einschränken
• Minimale Claims – Nur notwendige Benutzerattribute senden
• Audit-Protokollierung – In ADFS aktivieren (Anwendungs- und Dienstprotokolle -> AD FS -> Admin)
• Regelmäßige Updates – ADFS- und Windows Server-Patches anwenden
• Netzwerksicherheit – Firewall-Regeln, ADFS-Zugriff einschränken

Claims-Sicherheit

In Claims einschließen:

• Benutzer-ID (sub)
• E-Mail-Adresse
• Anzeigename
• Übergeordnete Rollen (optional)

NIEMALS in Claims einschließen:

• Sozialversicherungsnummern
• Passwörter oder Passwort-Hashes
• Sensible persönliche Informationen
• Detaillierte Zugriffsberechtigungen (stattdessen das RAMP-Rollensystem verwenden)

Token-Speicherung

RAMP speichert Tokens im Browser-Sitzungsspeicher:

• Wird beim Schließen des Browser-Tabs/-Fensters geleert
• Für andere Websites nicht zugänglich
• Nicht auf der Festplatte gespeichert
• Benutzer müssen sich nach einem Browser-Neustart erneut anmelden (by design)

---

Benutzerbereitstellung

Automatische Benutzererstellung

Wenn sich ein Benutzer zum ersten Mal über ADFS authentifiziert:

1. RAMP empfängt Claims von ADFS (sub, email, name)
2. RAMP prüft, ob ein Benutzer mit dieser ProviderSubjectId vorhanden ist
3. Falls nicht, erstellt RAMP ein neues Benutzerkonto:
   • Benutzername: Aus dem sub- oder upn-Claim
   • E-Mail: Aus dem email-Claim
   • Anzeigename: Aus dem name-Claim
   • IdentityProvider: ADFS
   • ProviderSubjectId: Eindeutiger Bezeichner von ADFS
4. Benutzer ist angemeldet, hat aber standardmäßig keine Rollen
5. Administrator muss Rollen zuweisen (oder Bootstrap-Administratoren verwenden)

Erforderliche Claims

ADFS muss diese Claims für RAMP bereitstellen:

Claim	Zweck	LDAP-Quelle
sub	Eindeutiger Benutzerbezeichner	SAM-Account-Name oder UPN
email	E-Mail-Adresse des Benutzers	E-Mail-Addresses
name	Anzeigename	Display-Name

Wenn einer fehlt, schlägt die automatische Benutzerbereitstellung fehl.

---

Migration von WS-Federation zu OIDC

Wenn Sie derzeit WS-Federation mit einer älteren ADFS-Version verwenden:

Warum zu OIDC migrieren?

• Moderner Standard – Branchenstandard-Authentifizierungsprotokoll
• Bessere SPA-Unterstützung – Für Single-Page-Anwendungen konzipiert
• JSON-basiert – Einfacher als XML (SAML/WS-Fed)
• Größeres Ökosystem – Mehr Bibliotheken und Tools
• Mobilfreundlich – Bessere Unterstützung für native Apps

Migrationsschritte

1. ADFS auf 2016 oder höher aktualisieren (für OIDC erforderlich)
2. OIDC-Anwendung in ADFS hinzufügen (parallel zur bestehenden WS-Fed)
3. OIDC in der Entwicklungsumgebung testen
4. RAMP-Frontend aktualisieren, um OIDC-Konfiguration zu verwenden
5. Deployment und Überwachung
6. WS-Fed-Anwendung dekommissionieren nach erfolgreicher Migration

---

Nächste Schritte

Nach der Konfiguration der ADFS-Authentifizierung:

• Bootstrap-Administratoren-Anleitung – Admin-Rollen automatisch zuweisen
• MFA-Einrichtung – Zusätzliche Sicherheitsebene hinzufügen
• Authentifizierungsübersicht – Alle Authentifizierungsanbieter vergleichen
• OIDC-Einrichtung – Generische OIDC-Konfigurationsanleitung

---

Verwandte Themen

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

OIDC / OAuth2-Einrichtung RAMP mit Azure AD, Okta, Keycloak oder einem beliebigen OIDC-Anbieter konfigurieren