Tech-Wissen

Neos Backend-URL ändern

Oftmals ist es sinnvoll die Backend-URL einer Website aus Sicherheitsgründen zu ändern. Wir erklären die notwendige Konfiguration in Neos.

Vorbereitung der Konfiguration

Neos (bzw. das darunter liegende Flow-Framework) bietet schon von Haus aus eine einfache Möglichkeit zur Definition und Priorisierung der einzelnen Routen (URLs). Dabei kann es sich um statische oder dynamische Routen handeln.

Um die Backend-URL zu ändern, benötigen wir also zunächst eine passende Konfigurationsdatei namens Routes.yaml. Optimaler Weise liegt diese im eigenen Site-Package innerhalb des Ordners "Configuration". (Packages/Sites/Vendor.Site/Configuration/Routes.yaml).

Falls nicht schon vorhanden, kann in diesem Zug auch direkt die Datei Settings.yaml im selben Ordner angelegt werden ( Packages/Sites/Vendor.Site/Configuration/Settings.yaml).

Beim Erstellen der Dateien unbedingt auf Groß- und Kleinschreibung achten.

Bestehende Neos Routen übernehmen

Damit nach dem URL-Wechsel auch noch alle Funktionen des Neos-Backends funktionieren, müssen auch alle entsprechenden Routen übernommen werden. Glücklicherweise wurden diese auf demselben Weg konfiguriert, wie sie auch geändert werden müssen.

Also werfen wir einfach mal einen Blick in die Routes.yaml von Neos selbst:
https://github.com/neos/neos/blob/master/Configuration/Routes.yaml.

Die hier aufgeführten Routen werden für die Neos-Anmeldung und Weiterleitung in das Backend genutzt. Die letzte Route "Frontend" fängt alle übrigen URLs für das Frontend ab und muss daher in unserer eigenen Routes.yaml am Schluss stehen.

Seit Einführung der neuen Neos.Ui sind noch ein paar weitere Routen hinzugekommen. Falls die neue UI also zum Einsatz kommt, brauchen wir auch diese: https://github.com/neos/neos-ui/blob/master/Configuration/Routes.yaml. Um sicherzustellen, dass die UI-Routen auch vor den eigentlichen Neos-Routen greifen, müssen diese also vor den Neos-Routen platziert werden.

Beide Dateien können also kopiert und in die eigene Routes.yaml eingefügt werden. Anschließend muss nur noch der Pfad "neos" in die beliebige neue Backend-URL geändert werden. (Reihenfolge beachten / siehe Beispiel unten).

Neue Backend-Url bestimmen (Beispielkonfiguration)

Um das oben beschriebene Vorgehen am Beispiel deutlich zu machen, haben wir die notwendigen Änderungen der URL von "/neos" nach "/backend" zusammengestellt. In den markierten Zeilen wurde "neos" durch "admin" ersetzt.

Wichtig: Diese Konfiguration wurde für die Neos Version 4.1 mit der Neos.Ui 1.4.0 erstellt. Nach jedem Update sollten die Routes.yaml Dateien auf Änderungen geprüft werden.

##
# Backend

-
  name:  'Backend'
  uriPattern: 'admin/<BackendSubRoutes>'
  defaults:
    '@package':    'Neos.Neos.Ui'
    '@action':     'index'
    '@format':     'html'
  subRoutes:
    'BackendSubRoutes':
      package: 'Neos.Neos.Ui'
      suffix:  'Backend'

##
# Service

-
  name:  'Backend'
  uriPattern: 'admin/ui-services/<ServiceSubRoutes>'
  defaults:
    '@package':    'Neos.Neos.Ui'
    '@action':     'index'
    '@format':     'html'
  subRoutes:
    'ServiceSubRoutes':
      package: 'Neos.Neos.Ui'
      suffix:  'Service'

##
# Authentication

-
  name:  'Authentication'
  uriPattern: 'admin/<AuthenticationSubRoutes>'
  defaults:
    '@package':    'Neos.Neos'
    '@controller': 'Login'
    '@action':     'index'
    '@format':     'html'
  subRoutes:
    'AuthenticationSubRoutes':
      package: 'Neos.Neos'
      suffix:  'Authentication'

##
# Backend

-
  name:  'Backend'
  uriPattern: 'admin/<BackendSubRoutes>'
  defaults:
    '@package':    'Neos.Neos'
    '@action':     'index'
    '@format':     'html'
  subRoutes:
    'BackendSubRoutes':
      package: 'Neos.Neos'
      suffix:  'Backend'

##
# Service

-
  name:  'Service'
  uriPattern: 'admin/service/<ServiceSubRoutes>'
  defaults:
    '@package':    'Neos.Neos'
    '@action':     'index'
  subRoutes:
    'ServiceSubRoutes':
      package: 'Neos.Neos'
      suffix:  'Service'

##
# Frontend

-
  name:  'Frontend'
  uriPattern: '<FrontendSubRoutes>'
  defaults:
    '@package':    'Neos.Neos'
    '@controller': 'Frontend\Node'
    '@action':     'show'
    '@format':     'html'
  routeParts:
    'node':
      handler:     'Neos\Neos\Routing\FrontendNodeRoutePartHandlerInterface'
  subRoutes:
    'FrontendSubRoutes':
      package: 'Neos.Neos'
      suffix:  'Frontend'
      variables:
        'defaultUriSuffix': ''

Neue Neos Backend-Url aktivieren

Wer die Beispielkonfiguration einfach mal ausprobiert wird feststellen, dass diese vermutlich noch nicht funktioniert. Das liegt dann daran, dass die Routes.yaml aus dem eigenen Site-Package noch gar nicht eingelesen werden. Um dies zu tun, sind noch ein paar wenige Zeilen in der Settings.yaml notwendig:

Neos:
  Flow:
    mvc:
      routes:
        'Vendor.Site': true

Alte Neos Backend-URL deaktivieren

Nun sollten die neu definierten Routen bereits funktionieren. Ggf. wird der Nutzer jedoch noch auf die alte Backend-URL weitergeleitet. Die standardmäßige Backend-URL ist aktuell ebenfalls noch aktiv. Da dies in den meisten Fällen nicht gewollt ist, gilt es nun die originalen Routen-Konfigurationen zu deaktivieren. Dazu erweitern wir einfach unsere Konfiguration in der Settings.yaml:

Neos:
  Flow:
    mvc:
      routes:
        'Vendor.Site': true
        'Neos.Neos': false
        'Neos.Neos.Ui': false

Fehler in den Routen einfach finden

Manchmal kommt es durch andere, schon vorhandene Routen dazu, dass die neu konfigurierten Routen nicht richtig greifen. Meist ist dies auf die Reihenfolge der Routen zurückzuführen. In diesem Fall lässt sich die Routing-Rangfolge mit dem Befehl ./flow routing:list ausgeben und entsprechend debuggen.