Zugriffsschlüssel

Einführung

Mit einer zugehörigen Strategie können Zugriffsschlüssel die Grundlage für einen unabhängigen oder nebenläufigen Autorierungsansatz schaffen. Eine wesentliche Motivation ist die Autorisierung unabhängig vom Nutzersystem (Nutzer) für Dritte (Gäste), exemplarisch beleuchtet etwa für Peer-Reviews. Dabei zielt der Ansatz auf das Lesen, aber auch Schreiben von Objekten oder Derivaten.
Denn fundamental wird zwischen Lese- und Schreibzugriffsschlüssel unterschieden, die persistent oder temporär aktiviert werden kann, siehe Gebrauch. Ein Nutzer kann für ein Objekt oder Derivat genau einen Zugriffsschlüssel persistent aktivieren. Zusätzlich können Gäste oder Nutzer gegebenenfalls Zugriffsschlüssel temporär für ein Objekt oder Derivat aktivieren. Hierbei unterliegt der Zugriffsschlüssel der Browser-Session. Zugriffsschlüssel können grundsätzlich deaktiviert werden. Die Gültigkeit kann optional zeitlich über ein Ablaufdatum beschränkt werden. Die REST-API V2 bietet eine Möglichkeit für die Verwaltung von Zugriffsschlüsseln. Bis LTS 2024.06 muss ein Nutzer oder Gast dafür mindestens über Schreibrechte verfügen. Gegebenenfalls muss die REST-API zusätzlich aktiviert werden, wenn beispielsweise die Verwaltung von Zugriffsschlüsseln für Gäste zugelassen werden soll. Ab LTS 2025.06 sind dafür eigene Berechtigungen erforderlich. Darüber hinaus steht ein Ansatz für eine Webapplikation zur Verwaltung von Zugriffsschlüsseln bereit.

Konfiguration

Zusammenfassung aller Properties mit default Werten und Beispielen, die Zugriffsschlüssel betreffen:

1
2
3
4

MCR.ACL.AccessKey.Strategy.AllowedObjectTypes=
# MCR.ACL.AccessKey.Strategy.AllowedObjectTypes=mods,derivate
MCR.ACL.AccessKey.Strategy.AllowedSessionPermissionTypes=read
# MCR.ACL.AccessKey.Strategy.AllowedSessionPermissionTypes=read,writedb

Die Ablage der Secrets wird bis LTS 2023.06 wie folgt konfiguriert:

1
2
3

# plain, crypt oder hash
MCR.ACL.AccessKey.Secret.Storage.Mode=hash
MCR.ACL.AccessKey.Secret.Storage.Mode.Hash.Iterations=1000

Ab LTS 2024.06 wird die Ablage über einen SecretProcessor konfiguriert. Das Verfahren für das Hashing ist unverändert, bestehende Zugriffsschlüssel bleiben daher gültig. Eine abweichend konfigurierte Anzahl an Iterationen muss in das neue Property übernommen werden.

1
2
3

MCR.ACL.AccessKey.Service.SecretProcessor.Class=org.mycore.mcr.acl.accesskey.service.processor.MCRAccessKeyHashSecretProcessor
# MCR.ACL.AccessKey.Service.SecretProcessor.Class=org.mycore.mcr.acl.accesskey.service.processor.MCRAccessKeyPlainSecretProcessor
MCR.ACL.AccessKey.SecretProcessor.Hash.HashIterations=1000

Struktur eines Zugriffsschlüssels

Strukturell betrachtet setzt sich ein Zugriffsschlüssel substanziell aus einem Secret und Type zusammen. Secret definiert das Geheimnis, das ein Nutzer kennen muss, um den Zugriffsschlüssel zu aktivieren. Der Wert kann frei gewählt werden, jedoch kann der Wert nach dem Hinzufügen des Zugriffsschlüssels nicht mehr eingesehen oder geändert werden. Das Secret wird default gehasht im Backend abgelegt, siehe Konfiguration. Type spiegelt die Berechtigung wieder, die sich aus der Aktivierung des Zugriffsschlüssels für ein Objekt oder Derivat ergibt. Der Ansatz unterstützt Lese- und Schreibzugriffsschlüssel: Der Type eines Lesezugriffschlüssels wird mit dem Wert read beschrieben, ein Schreibzugriffsschlüssel mit dem Wert writedb.

Optional kann der Status eines Zugriffsschlüssels mit IsActive beschrieben werden. Hiermit kann der Zugriffsschlüssel de- und aktiviert werden IsActive wird mit true (aktiviert) oder false (deaktiviert) beschrieben. Mit Expiration kann ein Ablaufdatum für den Zugriffsschlüssel gesetzt werden. Damit lässt sich die Gültigkeit zeitlich einschränken. Als Wert wird prinzipiell ein Unix Timestamp erwartet. Comment dient für zusätzliche Informationen, die eventuell wichtig für die Verwaltung sind.
Die folgende Ansicht zeigt einen Zugriffsschlüssel im JSON-Format mit allen manipulierbaren Eigenschaften:

1
2
3
4
5
6
7

{
"secret": "mycore+accesskey==love",
"type": "read",
"isActive": true,
"expiration": "1631256328",
"comment": "Test"
}

Ab LTS 2025.06 werden Zugriffsschlüssel über die REST-API nicht mehr pro Objekt, sondern über eine eigene Ressource verwaltet. Ein Zugriffsschlüssel enthält deshalb zusätzlich seine Referenz (Reference, in der Regel eine Objekt- oder Derivat-ID) und wird über eine eindeutige Id (UUID) angesprochen. Außerdem werden Ersteller, Erstelldatum, letzter Bearbeiter und Datum der letzten Änderung (createdBy, created, lastModifiedBy, lastModified) ausgegeben. Beim Erstellen werden secret, reference und type erwartet:

1
2
3
4
5
6
7
8

{
"id": "0f6a4a1e-3c2b-4f4e-9a57-5d6c1f0b7e21",
"secret": "mycore+accesskey==love",
"reference": "mir_mods_00000001",
"type": "read",
"isActive": true,
"comment": "Test"
}

Berechtigungen

Bis LTS 2024.06 reicht für die Verwaltung von Zugriffsschlüsseln das Recht writedb auf dem Objekt bzw. Derivat sowie auf restapi:/.

Mit der neuen REST-API (ab LTS 2024.06.1 als Draft, ab LTS 2025.06 ausschließlich) wird für jeden Zugriffsschlüssel das Recht manage-access-key-{type} auf der Referenz des Schlüssels geprüft, also z.B. manage-access-key-read für einen Lesezugriffsschlüssel eines Objekts. Die Prüfung erfolgt über die konfigurierte Zugriffsstrategie, sodass die Rechte etwa über default_mods vergeben werden können. Das Recht manage-access-key auf POOLPRIVILEGE erlaubt die Verwaltung aller Zugriffsschlüssel.

Zusätzlich erfordert die REST-API das Recht manage-access-key auf restapi:/access-keys bzw. restapi:/. Existiert nur für eine dieser IDs eine Regel, wird diese verwendet, existieren beide, müssen beide erfüllt sein. Ohne Regel ist der Zugriff nur dem Superuser erlaubt.

Gebrauch

Zugriffsschlüssel können persistent oder temporär aktiviert werden. Persistent bedeutet, dass der Zugriffsschlüssel als Attribut im Nutzerdatensatz in der Datenbank abgelegt wird. Diese Funktionalität kann derzeit noch nicht über das Front-End genutzt werden. Temporär bedeutet, dass der Zugriffsschlüssel in der HTTP-Session abgelegt wird und nach Ablauf der Session erneut übermittelt werden muss.

Filter

Für die temporäre Aktivierung steht der AccessKeyFilter bereit, der default für das Object-Servlet aktiviert werden kann. In Kombination mit der bereitgestellten Strategie kann der Filter abgeleitet aus MCR.ACL.AccessKey.Strategy.AllowedSessionPermissionTypes eingeschaltet werden. Sofern der Filter eingeschaltet ist, wird der Query-String auf das Secret über den Parameter accesskey geprüft - beispielhaft: receive/<object>?accesskey=<secret>. Nur nur wenn der Zugriffsschlüssel zum angefragten Objekt passt, wird dieser temporär für die HTTP-Session aktiviert - ansonsten ignoriert. Sonderzeichen (Secret) sollten im Pfad codiert werden, siehe URL-Encoding.

Kommandos

Über die MyCoRe Kommandozeile können auch administrative Operationen für Zugriffsschlüssel ausgeführt werden. Für den Export von Objekten/Derivaten liegt jeweils ein Style-Sheet save-accesskey bereit, das alle Zugriffsschlüssel in einem JSON-Array in einem ServFlag accesskeys abelegt. Allgemein werden Zugriffsschlüssel bei einem Update eines Objekts/Derivates nicht berücksichtigt. Beim Löschen eines Objekts/Derivats werden alle zugehörigen Zugriffsschlüssel gelöscht. Beim Import eines Objekts/Derivats werden die ServFlags mit dem Typ accesskeys erwartet im JSON-Array-Format.

clear all access keys

Das Kommando löscht alle Zugriffsschlüssel.

clear all access keys for {0}

Das Kommando löscht alle Zugriffsschlüssel eines Objekts/Derivats.

create access key for {0} from file {1}

Das Kommando erwartet einen Pfad für einen Zugriffsschlüssel, der im JSON-Format spezifiziert werden muss, und erstellt jenen für ein Objekt/Derivat.

update access key for {0} with secret {1} from file {2}

Das Kommando erwartet einen Pfad für einen Zugriffsschlüssel, der im JSON-Format spezifiziert werden muss, und updatet jenen für ein Objekt/Derivat. Dabei wird das Secret zusätzlich als Referenz erwartet und muss ggf. gehasht werden.

delete access key for {0} with secret {1}

Das Kommando löscht einen Zugriffsschlüssel eines Objekts/Derivats. Dabei wird zusätzlich das Secret als Referenz erwartet und muss ggf. gehasht werden.

import access keys for {0} from file {1}

Das Kommando importiert alle Zugriffsschlüssel für ein Objekt/Derivat, etwa ein Back-up. Dabei wird der Pfad einer Datei erwartet, die Zugriffsschlüssel in einem JSON-Array spezifiziert. Achtung: Beim Import werden Zugriffsschlüssel nicht mehr verarbeitet, sondern direkt übernommen, und ggf. müssen die Secrets gehasht werden. Das Kommando sollte als das Inverse des Export-Kommandos gesehen werden.

export access keys for {0} to file {1}

Das Kommando exportiert alle Zugriffsschlüssel für ein Objekt/Derivat. Dabei wird der Pfad des Speicherorts erwartet. Die Zugriffsschlüssel werden in einem JSON-Array spezifiziert. Dieses Kommando eignet sich für ein Back-up für ein Objekt/Derivat.

clean up access key user attributes

Das Kommando überprüft die Beständigkeit der Zugriffsschlüssel-User-Attribute aller User und löscht diese ggf., wenn der zugehörige Schlüssel nicht mehr existiert.

hash access key secret {0} for {1}

Das Kommando hasht einen String für ein Objekt/Derivat.