====== Separate Domain für Projektadministration ======

Die Administration von SoSci Survey (Verzeichnis ''admin/'') kann auf eine eigene (Sub-)Domain geschaltet werden, z.B. ''%%https://admin.example.org%%'', während die Befragungen weiterhin unter ''%%https://www.example.org%%'' laufen. Das erhöht die Sicherheit, denn JavaScript in einem Fragebogen (etwa aus importierten Vorlagen) kann dann nicht auf die Administration zugreifen, wenn eine angemeldete Person den Fragebogen aufruft.

Die Trennung ist optional, wird aber empfohlen, wenn eine größere Zahl Personen mit der Installation arbeiten. Ohne weitere Konfiguration bleiben Befragungsprojekte und Projektadministration unter einer gemeinsamen Domain erreichbar.

Die folgenden Beispiele verwenden ''%%www.example.org%%'' für die Server-URL (Befragungen) und ''admin.example.org'' für die Administration.


===== Neue Installation =====

==== Webserver einrichten ====

  * Die Administration benötigt einen **eigenen Host** (Domain oder Subdomain). Ein anderer Port auf demselben Host reicht nicht aus, weil Browser Login-Cookies nicht nach Port trennen.
  * Legen Sie einen virtuellen Host für ''%%admin.example.org%%'' an, dessen Document-Root das Verzeichnis ''admin/'' der Installation ist.
  * Der virtuelle Host ''%%www.example.org%%'' zeigt wie bisher auf das Hauptverzeichnis der Installation. Dort liegen weiterhin die Projektordner, Bilder, Skripte und Plugins.
  * Verwenden Sie für beide Hosts HTTPS.

=== Beispiel für Apache ===

<code apache>
<VirtualHost *:443>
    ServerName admin.example.org
    DocumentRoot /var/www/sosci/admin
    # SSL-Konfiguration wie für www.example.org
</VirtualHost>
</code>

=== Beispiel für nginx ===

<code nginx>
server {
    listen 443 ssl;
    server_name admin.example.org;
    root /var/www/sosci/admin;
    index index.php;
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass <php-fpm>;
    }
}
</code>

==== SoSci Survey installieren ====

Installieren Sie SoSci Survey wie gewohnt unter der Server-URL (z.B. ''https://www.example.org/admin/install.php''). Die Trennung wird erst nach der Installation eingerichtet.

==== URLs in der Administration eintragen ====

Öffnen Sie in der **Server-Verwaltung** -> **Server-Einstellungen** -> **Konfiguration** den Karteireiter **Server**:

^ Einstellung ^ Wert ^ Hinweis ^
| URL des Servers | ''%%https://www.example.org%%'' | Bleibt das Hauptverzeichnis der Installation. Die Lizenz ist an diese URL gebunden. |
| URL der Administration | ''%%https://admin.example.org%%'' | Ohne ''/admin'' am Ende, die Domain zeigt direkt auf ''admin/''. |
| URL der Befragungen | (leer lassen) | Nur ausfüllen, wenn die Projektordner unter einer anderen Basis-URL liegen als die Server-URL (siehe unten). |

Klicken Sie auf **Speichern**.

==== URL der Administration verifizieren ====

Nach dem Speichern prüft der Server, ob die URL der Administration diese Installation erreicht. Erst nach dieser Prüfung wird die Trennung durchgesetzt:

  * Gelingt die Prüfung, erscheint der Hinweis, dass die Administration ab sofort nur noch unter der neuen URL erreichbar ist. Melden Sie sich dort erneut an.
  * Kann der Server seine eigene öffentliche Adresse nicht erreichen (z.B. hinter einer Firewall), zeigen die Server-Einstellungen einen Link zur Verifizierung an. Öffnen Sie diesen Link im Browser.

Sobald die Trennung aktiv ist, verändert sich das Programmverhalten wie folgt.

  * Aufrufe der Administration unter einer anderen Adresse (z.B. ''https://www.example.org/admin/'') werden auf die URL der Administration umgeleitet.
  * Unter der Domain der Administration sind keine Befragungen erreichbar.
  * Die Anmelde-Cookies gelten nur für die Domain der Administration.

Wenn Sie die URL der Administration oder der Befragungen später ändern, ist die Trennung bis zur erneuten Verifizierung aufgehoben.

**Nicht betroffen** sind die Schnittstellen ''api.php'', ''interface.php'', ''privacy.php'' und ''remote.php''. Sie bleiben auch unter der Server-URL erreichbar, ebenso die bei SMS-Anbietern hinterlegten Report-URLs.

==== Optional: Projektordner außerhalb der Installation ====

Die Projektordner können in einem anderen Verzeichnis liegen als die Installation, z.B. auf einem eigenen Laufwerk. Tragen Sie den absoluten Pfad in der Datei ''system/config.php'' ein:

<code php>
$GLOBALS['oFb']['path']['projects'] = '/var/www/projects';
</code>

  * Der Webserver muss dieses Verzeichnis unter einer eigenen URL ausliefern. Tragen Sie diese URL unter **URL der Befragungen** ein (z.B. ''%%https://www.example.org%%'', wenn das Verzeichnis die Document-Root von ''www.example.org'' ist).
  * PHP muss das Verzeichnis lesen und beschreiben können.

==== Single-Sign-On (SSO) ====

Die Rücksprungadressen für das Single-Sign-On verwenden die URL der Administration.

**OpenID Connect (OIDC):** Registrieren Sie beim Identity-Provider als Redirect-URI ''https://admin.example.org/?sso=<Kennung>'' (die Kennung ist der Schlüssel des IdP in ''$GLOBALS['oFb']['sso']['idp']'').

**SAML (SimpleSAMLphp):** Der Identity-Provider kennt nur die Adresse von SimpleSAMLphp, nicht die der Administration. In der Konfiguration von SimpleSAMLphp (''config/config.php'') ist Folgendes zu beachten.

  * Die Domain der Administration muss als vertrauenswürdig eingetragen sein, sonst lehnt SimpleSAMLphp die Rückkehr zur Administration ab:<code php>
'trusted.url.domains' => ['www.example.org', 'admin.example.org'],
</code>Nur Hostnamen, ohne Protokoll und Pfad.
  * Läuft SimpleSAMLphp unter ''www.example.org'', muss sein Session-Cookie auch an die Domain der Administration gesendet werden:<code php>
'session.cookie.domain' => '.example.org',
</code>Verwendet SimpleSAMLphp die PHP-Session (''store.type'' = ''phpsession''), muss der Name seines Cookies (''session.phpsession.cookiename'') von dem Session-Cookie von SoSci Survey abweichen.
  * Alternativ kann SimpleSAMLphp unter der Domain der Administration laufen. Dann ändert sich die Adresse des Service Providers (ACS-URL), und die Metadaten müssen beim Identity-Provider bzw. in der Föderation aktualisiert werden.

==== Zwei-Faktor-Authentifizierung (FIDO2) ====

Sicherheitsschlüssel (FIDO2/WebAuthn) werden für die Domain registriert, unter der sie eingerichtet werden. Bei einer neuen Installation, die von Anfang an die eigene Domain für die Administration verwendet, ist nichts weiter zu tun. Wurden bereits Schlüssel unter der Server-URL eingerichtet, beachten Sie bitte den Abschnitt zu FIDO2 unter "Bestehende Server".

==== Eigene URLs für Projekte ====

Eine aufgeschaltete URL eines Projekts darf nicht die Domain der Administration verwenden, SoSci Survey lehnt eine solche Eingabe ab. Projekte mit einer eigenen Domain sind weiterhin möglich.

===== Bestehende Server =====

Für einen Server, auf dem SoSci Survey bereits unter einer Domain läuft, gelten die Schritte für neue Installationen ab Abschnitt 1. Zusätzlich ist Folgendes zu beachten.

==== Update der Installation ====

  * Spielen Sie die neue Version ein und führen Sie das Update der Installation durch, bevor Sie die URL der Administration eintragen.
  * Tragen Sie die URLs anschließend wie oben beschrieben ein (Abschnitt 3) und verifizieren Sie die URL der Administration (Abschnitt 4).

==== Auswirkungen auf die Nutzer ====

  * Nach der Umstellung müssen sich alle Nutzer unter der neuen Adresse erneut anmelden.
  * Lesezeichen auf ''https://www.example.org/admin/...'' funktionieren weiter, sie werden umgeleitet. Formulare, die vor der Umstellung geöffnet und danach abgesendet werden, werden abgelehnt und müssen neu geladen werden. Stellen Sie daher am besten zu einer Zeit um, zu welcher der Server nur wenig genutzt wird.
  * Links in E-Mails, die SoSci Survey nach der Umstellung versendet, verwenden die neue Adresse.

==== Single-Sign-On ====

**OpenID Connect (OIDC):** Die Redirect-URI ändert sich, sobald die URL der Administration eingetragen ist, also bereits vor der Verifizierung. Identity-Provider, bei denen bisher ''https://www.example.org/admin/?sso=<Kennung>'' registriert ist, würden die Anmeldung dann ablehnen. Sie haben zwei Möglichkeiten:

  - Der Identity-Provider registriert zusätzlich die neue Adresse ''https://admin.example.org/?sso=<Kennung>''. Die meisten Anbieter erlauben mehrere Redirect-URIs, sodass die neue Adresse schon vor der Umstellung eingetragen werden kann.
  - Oder Sie behalten die bisherige Adresse bei, indem Sie beim betreffenden IdP in ''system/config.php'' die Einstellung ''oidc.redirect'' ergänzen. Die Anmeldung kehrt dann zur alten Adresse zurück und wird an die Administration weitergeleitet:

<code php>
$GLOBALS['oFb']['sso']['idp']['<Kennung>'] = [
    'label' => '...',
    'handler.file' => '...',
    'handler.class' => '...',
    'oidc.redirect' => 'https://www.example.org/admin',
];
</code>

**SAML (SimpleSAMLphp):** Solange SimpleSAMLphp unter seiner bisherigen Adresse bleibt, müssen die Identity-Provider nichts ändern. Ergänzen Sie aber vor der Umstellung ''trusted.url.domains'' und ''session.cookie.domain'' wie in Abschnitt 6 beschrieben.

Testen Sie die Anmeldung möglichst vorab auf einem Testsystem mit je einem Identity-Provider pro Verfahren.

==== FIDO2-Sicherheitsschlüssel ====

Bereits eingerichtete Sicherheitsschlüssel sind an die Domain der Server-URL (''www.example.org'') gebunden. Damit sie auch unter ''admin.example.org'' funktionieren, muss der Browser unter der Server-URL die Datei ''/.well-known/webauthn'' abrufen können (WebAuthn "Related Origins"). SoSci Survey erzeugt diese Datei mit dem Skript ''admin/webauthn.php''.

Richten Sie auf dem virtuellen Host ''www.example.org'' eine interne Weiterleitung ein:

  * genau der Pfad ''/.well-known/webauthn'' im Hauptverzeichnis des Hosts, unabhängig vom Installationspfad von SoSci Survey,
  * **keine** Umleitung (kein 301/302, auch keine Umleitung auf HTTPS oder ''www''), weil Browser die Datei ohne Umleitungen und ohne Cookies abrufen,
  * nur HTTPS, ohne Authentifizierung.

=== Konfiguration nginx ===

<code nginx>
location = /.well-known/webauthn {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /var/www/sosci/admin/webauthn.php;
    fastcgi_pass <php-fpm>;
}
</code>

=== Konfiguration Apache ===

<code apache>
RewriteEngine On
RewriteRule ^/?\.well-known/webauthn$ /admin/webauthn.php [L]
</code>

Neue Sicherheitsschlüssel werden für die Domain der Administration registriert. Unterstützt ein Browser "Related Origins" nicht, zeigt die Anmeldung einen Hinweis statt der alten Schlüssel. Die Person meldet sich dann mit einem anderen Faktor an und richtet den Sicherheitsschlüssel neu ein.


==== Projektordner verschieben ====

Sie können die Projektordner an einen anderen Ort verschieben:

  - Verschieben Sie die Ordner und tragen Sie den neuen Pfad in ''system/config.php'' ein.
  - Tragen Sie die zugehörige Adresse unter **URL der Befragungen** ein.
  - Öffnen Sie **Server-Verwaltung** → **Server-Wartung** → **Verzeichnisse überprüfen** und wählen Sie unter //Projektverzeichnisse wiederherstellen// die Option "Index-Dateien (index.php) aller Projekte zurücksetzen". Die Index-Dateien verweisen dann auf den neuen Ort der Installation.

Beachten Sie, dass dabei auch Index-Dateien ersetzt werden, die manuell angepasst wurden, z.B. für eine Weiterleitung zu einem anderen Projekt.