Vergleichsreport

Externe Clients (Kiosk-Terminals External clients (kiosk terminals, mobile Appsapps, Integrationenintegrations) sprechen Webdesk über die REST-Schnittstelle an (Pfad talk to Webdesk through its REST interface (path /rest/... unterhalb des Webdesk-Kontextpfads). Diese Seite beschreibt, wie sich ein solcher Client authentifiziert, wie ein API-Key angelegt und verwaltet wird und wie über Zugriffsrechte und Zugriffsrecht-Sets festgelegt wird, welche REST-Aufrufe er ausführen darf. Sie richtet sich an Systemadministratoren und Berater. Die Zugriffsrechte für REST-Endpunkte sind unabhängig von den Aktionsberechtigungen der Berechtigungssteuerung (siehe Berechtigungstypen): Diese steuern, wer eine Aktion in der Oberfläche aufrufen darf, die hier beschriebenen Zugriffsrechte steuern, welche REST-URLs mit welcher HTTP-Methode aufgerufen werden dürfen.

Zwei Wege der Authentifizierung

Merkmal

Anmeldung mit Benutzer (Session)

API-Key

Typischer Einsatz

Integrationen und Apps, die im Namen eines Webdesk-Benutzers arbeiten

Geräte und Systeme ohne Benutzeranmeldung, z. B. Kiosk-Terminals

Ablauf

below the Webdesk context path). This page describes how such a client authenticates, how an API key is created and managed, and how access rights and access right sets define which REST calls it may make. It is intended for system administrators and consultants. The access rights for REST endpoints are independent of the action permissions of the authorization control (see permission types): those control who may open an action in the user interface, whereas the access rights described here control which REST URLs may be called with which HTTP method.

Two ways to authenticate

Aspect	Login with a user (session)	API key
Typical use	Integrations and apps that act on behalf of a Webdesk user	Devices and systems without a user login, e.g. kiosk terminals
Flow	POST /rest/auth/login mit JSON-Body with a JSON body containing username, password und optional and optionally rememberLogin. Antwort 200 mit Sitzungsdaten (u. a. Response 200 with session data (including authentication-state, session-timeout, login-token) bzw. 401 bei falscher Anmeldung. Die folgenden Aufrufe müssen das Sitzungs-Cookie mitsenden.Jeder Aufruf trägt den HTTP-Header , or 401 if the login fails. Subsequent calls must send the session cookie.	Every call carries the HTTP header X-Auth-Token: <your-api-key>. Eine vorherige Anmeldung ist nicht nötig.
Berechtigung	Zugriffsrechte der Rollen des Benutzers (Rollen-Reiter "Zugriffsrechte")	Zugriffsrechte des API-Keys (direkt am Key und über zugeordnete Zugriffsrecht-Sets)

Ist der Header

No prior login is needed.
Authorization	Access rights of the user's roles (role tab "Access Rights")	Access rights of the API key (directly on the key and via assigned access right sets)

If the X-Auth-Token gesetzt, wird der Aufruf als API-Key-Aufruf behandelt, andernfalls als Session-Aufruf. (Nur im Betriebsmodus dev oder test wird zusätzlich Basic Authentication über den Header Authorization akzeptiert; sie ist für Tests gedacht.) Der Aufruf header is set, the call is handled as an API key call, otherwise as a session call. (Only in running mode dev or test is Basic Authentication via the Authorization header accepted as well; it is intended for tests.)

The /rest/auth/login sowie einige weitere öffentliche Endpunkte (z. B. Passwort-Rücksetzung, Systemzeit) werden von der REST-Authentifizierung nicht geprüft. Für Browser-Anmeldungen ist der normale Weg weiterhin die Webdesk-Login-Seite call and a few other public endpoints (e.g. password reset, system time) are not checked by the REST authentication. For browser logins the normal way remains the Webdesk login page; /rest/auth/login ist für externe Clients vorgesehen.

Session-Aufrufe: Berechtigung über Rollen

Externe Clients mit Benutzeranmeldung benötigen rollenbasierte Zugriffsrechte. Es zählen alle Zugriffsrechte und Zugriffsrecht-Sets aller Rollen, die der angemeldete Benutzer innehat. Ist für URL und HTTP-Methode weder ein erlaubendes noch ein verbietendes Recht vorhanden, wird der Aufruf mit 403 abgewiesen. Einige Endpunkte, die für jeden angemeldeten Benutzer gedacht sind (z. B. unter is meant for external clients.

Session calls: authorization via roles

External clients that log in with a user need role-based access rights. All access rights and access right sets of all roles held by the logged-in user count. If neither a granting nor a denying right exists for the URL and HTTP method, the call is rejected with 403. A few endpoints intended for every logged-in user (e.g. under /rest/po/systeminfo/, /rest/po/users/, /rest/po/actionpermissions/) , sind von der Rechteprüfung ausgenommen; für sie genügt die Anmeldung. Ruft die Oberfläche selbst REST-Endpunkte auf (Erkennung über den Referer), gelten stattdessen die in der jeweiligen Aktion hinterlegten Zugriffsrechte (siehe unten).

API-Key mit Benutzer-Identifikation (Impersonation)

Ein API-Key kann zusätzlich im Namen eines Webdesk-Benutzers handeln, z. B. wenn ein Kiosk-Terminal nach dem Scannen einer NFC-Karte Daten dieser Person abruft. Dazu sendet der Client einen der beiden Header:

Header

Erklärung

are exempt from the rights check; being logged in is sufficient for them. When the user interface itself calls REST endpoints (detected through the Referer), the access rights stored in the respective action apply instead (see below).

API key with user identification (impersonation)

An API key can additionally act on behalf of a Webdesk user, e.g. when a kiosk terminal fetches the data of a person after scanning an NFC card. For this, the client sends one of the two headers:

Header	Description
User-Identification-NfcCard	ID der of the NFC -Karte; der Benutzer ist die Person, der die Karte zugewiesen istcard; the user is the person to whom the card is assigned.
User-Identification-Useruid	UID der Person.

Einschränkungen:

• Der Key muss zuerst für den aufgerufenen Endpunkt berechtigt sein (gleiche Prüfung wie ohne Header).
• Es dürfen nicht beide Header gleichzeitig gesendet werden und der Wert darf nicht leer sein (Antwort 401).
• Ist keine Person zur Karte bzw. UID zu finden, lautet die Antwort 401.
• Impersonation ist nur für Kiosk-Keys erlaubt, also Keys, die einem Kiosk zugeordnet sind, und nur für Personen desselben Mandanten wie der Kiosk. Bei einem Key ohne Kiosk oder einer Person eines anderen Mandanten lautet die Antwort 403.

Die Zugriffsrechte des Keys bleiben auch bei Impersonation maßgeblich; die Rechte der identifizierten Person erweitern sie nicht.

API-Keys verwalten

Die Masken liegen im Admin-Menü unter "System" (im Ordner "Sicherheit

of the person.

Restrictions:

• The key must first be authorized for the called endpoint (same check as without the header).
• Both headers must not be sent at the same time and the value must not be empty (response 401).
• If no person can be found for the card or UID, the response is 401.
• Impersonation is only allowed for kiosk keys, i.e. keys assigned to a kiosk, and only for persons of the same client as the kiosk. For a key without a kiosk or a person of another client the response is 403.

The access rights of the key remain decisive even with impersonation; the rights of the identified person do not extend them.

Managing API keys

The screens are located in the admin menu under "System" (in the folder "Security"): "API Keys" (Listelist) und and "Zugriffsrecht SammlungAccessright Sets" (Zugriffsrecht-Sets). Je nach Menüaufbau des Systems kann der Eintrag "Zugriffsrecht Sammlung" auch direkt unter "System" stehen.

Liste "API Keys"

Die Liste zeigt alle Keys mit den Spalten access right sets). Depending on the menu layout of the system, the entry "Accessright Sets" may also appear directly under "System".

List "API Keys"

The list shows all keys with the columns "API Key" (der Schlüsselwert selbstthe key value itself), "API Consumer", "Gültig vonValid from" und and "Gültig bis"; auch ungültig gemachte Keys bleiben sichtbar. Über das Symbol in der ersten Spalte wird ein Key geöffnet, über die Schaltfläche Valid till"; keys that have been invalidated remain visible. The icon in the first column opens a key, the button "Generate New API Key" ein neuer angelegt.

Neuen Key anlegen

In der Liste

creates a new one.

Creating a key

1. In the "API Keys" auf list, click "Generate New API Key" klicken. Im Feld .
2. Enter the name of the client in the "API Consumer" den Namen des Clients eintragen (nur zur Beschreibung, z. B field (description only, e.g. "Terminal Eingang WienMain Entrance").
3. Im Abschnitt In the section "Api Key Zugriffsrecht-Access Right Sets" über "Hinzufügen" ein oder mehrere Zugriffsrecht-Sets zuordnen und/oder im Abschnitt "Api Key-Spezifische Zugriffsrechte" einzelne Rechte erfassen (siehe unten).
4. Speichern. Es erscheint "API Schlüssel erfolgreich gespeichert"; im Feld "API Key" steht nun der erzeugte Schlüsselwert, der im Client einzutragen ist.

Achtung: Ein neuer Key ohne Zugriffsrecht-Set und ohne eigene Rechte ist zwar gültig, darf aber keinen einzigen Endpunkt aufrufen (Antwort 403).

Achtung: Der Schlüsselwert ist das Geheimnis, mit dem sich der Client ausweist, und wird in der Liste und in der Maske im Klartext angezeigt. Der Zugriff auf diese Masken sollte entsprechend eingeschränkt sein; Keys gehören in keine Dokumentation, kein Ticket und keine URL. Webdesk bietet für Bilder

1. assign one or more access right sets using "Add", and/or enter individual rights in the section "Api Key Specific Access Rights" (see below).
2. Save. "API Key saved successfully" is shown; the field "API Key" now contains the generated key value, which has to be entered in the client.

Warning: A new key without an access right set and without its own rights is valid, but may not call a single endpoint (response 403).

Warning: The key value is the secret with which the client identifies itself, and it is displayed in clear text in the list and in the screen. Access to these screens should be restricted accordingly; keys do not belong in documentation, tickets or URLs. For images (/image/...) zwar zusätzlich den Parameter apiKey an, der Header Webdesk additionally accepts the parameter apiKey, but the header X-Auth-Token ist aber vorzuziehen.

Key bearbeiten, ungültig machen, löschen

is preferable.

Editing, invalidating, deleting a key

• "API Consumer" und die Zugriffsrechte können jederzeit geändert werden. "Gültig von" und "Gültig bis" sind in der Maske nur Anzeige. Beim Speichern werden die Sets und Rechte des Keys durch den Inhalt der Maske ersetzt. Bereits gespeicherte Rechtezeilen sind nur lesbar und können nur gelöscht werden; geänderte Rechte werden als gelöschte und neu erfasste Zeile umgesetzt. Änderungen an den Rechten gelten für die folgenden Aufrufe; eine Neuanmeldung des Clients ist nicht nötig.
• "ungültig machen" (Rückfrage: "Sind Sie sicher, dass Sie diesen API-Schlüssel ungültig machen wollen?"): Der Key wird beendet (Gültig bis = Vortag) und liefert sofort 401. Der Eintrag bleibt in der Liste erhalten; die Schaltfläche verschwindet. Ein ungültiger Key kann in der Oberfläche nicht wieder gültig gemacht werden.
• "Löschen" (Rückfrage: "Sind Sie sicher, dass Sie diesen API-Schlüssel löschen wollen?", Bestätigung "API-Schlüssel löschen"): Der Key wird endgültig entfernt.

Gehört der (gültige) Key zu einem Kiosk, weist die Rückfrage darauf hin, dass dieser Kiosk danach nicht mehr funktioniert. Das Ungültigmachen oder Löschen löst die Verbindung zwischen Kiosk und Key; einen neuen Key erzeugt man in der Kiosk-Maske (siehe unten).

Keys von Kiosks

Für Kiosks (Menü "Karten u. Kiosk" > "Kiosks") verwaltet Webdesk den Key selbst:

• Beim Anlegen oder Registrieren eines Kiosks wird automatisch ein Key erzeugt (API Consumer = Kioskname) und diesem das Standard-Zugriffsrecht-Set des Kiosk-Typs zugeordnet (siehe unten).
• In der Kiosk-Maske zeigt das Feld "API key" mit der Schaltfläche "API-Schlüssel anzeigen" den Schlüssel an. Die Schaltfläche steht nur Benutzern zur Verfügung, die alle Mandanten einsehen dürfen (Systemadministration).
• Hat der Kiosk keinen gültigen Key, erscheint die Schaltfläche "API-Schlüssel generieren". Sie erzeugt einen neuen Key mit dem Standard-Set und entfernt den alten Key.
• Wird ein Kiosk gelöscht, wird sein Key ungültig gemacht bzw. mitgelöscht.
• Wird ein bestehender PTM-Kiosk zusätzlich als TA-Kiosk registriert (oder umgekehrt), wird er zum Typ PTM_TA und erhält ebenfalls einen neuen Key.

Zugriffsrechte und Zugriffsrecht-Sets

Aufbau eines Zugriffsrechts

Eigenschaft

Erklärung

mögliche Wert(e)

"Selektor"

Pfad des REST-Endpunkts, ohne Kontextpfad und ohne Query-Parameter, beginnend mit /rest/..., z. B

• and the access rights can be changed at any time. "Valid from" and "Valid till" are display-only in the screen. When saving, the sets and rights of the key are replaced by the content of the screen. Already saved right rows are read-only and can only be deleted; a changed right is implemented as a deleted row and a newly entered row. Changes to the rights apply to the following calls; the client does not need to log in again.
• "Invalidate" (confirmation: "Are you sure you want to invalidate this API-key?"): the key is terminated (Valid till = previous day) and immediately returns 401. The entry stays in the list; the button disappears. An invalidated key cannot be made valid again in the user interface.
• "Delete" (confirmation: "Are you sure you want to delete this API-key?", button "Delete API-Key"): the key is removed permanently.

If the (valid) key belongs to a kiosk, the confirmation points out that this kiosk will no longer work afterwards. Invalidating or deleting breaks the link between kiosk and key; a new key is generated in the kiosk screen (see below).

Keys of kiosks

For kiosks (menu "Cards and Kiosks" > "Kiosks") Webdesk manages the key itself:

• When a kiosk is created or registered, a key is generated automatically (API Consumer = kiosk name) and the default access right set of the kiosk type is assigned to it (see below).
• In the kiosk screen, the field "API key" with the button "Show API Key" displays the key. The button is only available to users who may view all clients (system administration).
• If the kiosk has no valid key, the button "Generate API Key" appears. It generates a new key with the default set and removes the old key.
• If a kiosk is deleted, its key is invalidated or deleted along with it.
• If an existing PTM kiosk is additionally registered as a TA kiosk (or vice versa), it becomes type PTM_TA and also receives a new key.

Access rights and access right sets

Structure of an access right

Erlaubte Art des Zugriffs. Zuordnung zur HTTP-Methode siehe unten

Property	Description	Possible value(s)
"Selector"	Path of the REST endpoint, without context path and without query parameters, starting with /rest/..., e.g. /rest/po/kiosks. PlatzhalterWildcards: * = beliebige Zeichenfolge (auch über / hinwegany string (also across /), ? = genau ein beliebiges Zeichen. Der Selektor muss auf den gesamten Pfad passenexactly one arbitrary character. The selector must match the entire path.	Text, Pflichtfeldrequired
"Privileg"	Privilege"	Permitted kind of access. For the mapping to the HTTP method see below.	READ, CREATE, UPDATE, DELETE, FULL
"Ablehnen"	Bei gesetztem Haken verbietet das Recht den Zugriff, statt ihn zu erlauben.	Ja/Nein (Standard: Nein, das Recht erlaubt)
HTTP-Methode	benötigtes Privileg
Deny"	If checked, the right forbids the access instead of allowing it.	Yes/No (default: No, the right allows)

HTTP method	required privilege
GET	READ
POST	CREATE
PUT, PATCH	UPDATE
DELETE	DELETE

FULL entspricht corresponds to READ, CREATE, UPDATE und and DELETE zusammentogether. Andere Other HTTP -Methoden methods (ze. Bg. HEAD) können nicht zugeordnet werden und führen zu einer Fehlerantwort 401.

Wo Zugriffsrechte vergeben werden

Ort

Wirkung

API-Key (Abschnitte "Api Key Zugriffsrecht-Sets" und "Api Key-Spezifische Zugriffsrechte")

Für Aufrufe mit X-Auth-Token. Es gilt die Summe aus den eigenen Rechten des Keys und den Rechten aller zugeordneten Sets.

Rolle (Reiter "Zugriffsrechte" in der Rollenmaske, Abschnitte "Rollenspezifische Zugriffsrecht-Sets" und "Rollenspezifische Zugriffsrechte"; siehe Rollen)

Für Session-Aufrufe aller Rolleninhaber. Der Reiter ist nur für Systemadministratoren und nicht bei abgeleiteten Mandanten-Rollen sichtbar.

Aktion (Datei

cannot be mapped and result in an error response 401.

Where access rights are assigned

Place	Effect
API key (sections "Api Key Access Right Sets" and "Api Key Specific Access Rights")	For calls with X-Auth-Token. The sum of the key's own rights and the rights of all assigned sets applies.
Role (tab "Access Rights" in the role screen, sections "Role Access Right Sets" and "Role Specific Access Rights"; see Roles)	For session calls of all role holders. The tab is only visible to system administrators and not for derived client roles.
Action (file act-descr.xml)	Für REST-Aufrufe, die die Oberfläche aus dieser Aktion heraus tätigt. Nicht über die Oberfläche änderbar: Die Aktion zeigt sie im Reiter "Zugriffsrechte" nur an, Änderungen dort werden nicht gespeichert.	Zugriffsrecht-Set	Wiederverwendbare Sammlung von Rechten, die beliebig vielen Keys und Rollen zugeordnet werden kannFor REST calls that the user interface makes from this action. Cannot be changed in the user interface: the action only displays them in the tab "Access Rights", changes made there are not saved.
Access right set	Reusable collection of rights that can be assigned to any number of keys and roles.

In act-descr.xml werden Rechte als rights are declared as <accessrights><accessright selector="/rest/po/audit/label/*" privilege="GET"/></accessrights> deklariert. Das Attribut privilege nimmt eine oder mehrere (durch Komma getrennte) HTTP-Methoden entgegen, z. BThe attribute privilege takes one or more HTTP methods separated by commas, e.g. GET,POST. Solche Rechte erlauben immer; ein Ablehnen ist nicht möglich.

Zugriffsrecht-Sets pflegen

Admin-Menü

Such rights always allow; denying is not possible.

Maintaining access right sets

1. Open the admin menu "System" > "Zugriffsrecht SammlungAccessright Sets" öffnen (Liste list "Accessright Sets" mit der Spalte with the column "Name").
2. Auf "Neues Zugriffsrecht Set" klicken bzw. ein bestehendes Set öffnen.
3. Einen eindeutigen Click "New Access Right Set" or open an existing set.
4. Enter a unique "Name" vergeben (Pflichtfeld; der Name darf nur einmal vorkommen).
5. Über "Hinzufügen" Zeilen mit "Selektor", "Privileg" und gegebenenfalls "Ablehnen" erfassen.
6. Speichern. Bestehende Zeilen sind nur lesbar und können nur gelöscht werden; für eine Änderung die Zeile löschen und neu erfassen. Das Set kann anschließend im API-Key bzw. in der Rolle zugeordnet werden (Auswahlfeld "Zugriffsrecht-Set"; ein Sprung-Symbol öffnet das Set).

Achtung: Änderungen an einem Set wirken auf alle Keys und Rollen, denen es zugeordnet ist.

Standard-Sets für Kiosks

Für Kiosk-Keys legt Webdesk beim ersten Bedarf ein Set mit dem Namen Default <Typ> Kiosk Access Right Set an (Typ = PTM, TA oder PTM_TA) und ordnet es dem neuen Key zu. Die Sets enthalten (alle erlaubend):

Selektor

Privileg

in Set

1. required; the name may only exist once).
2. Using "Add", enter rows with "Selector", "Privilege" and, if needed, "Deny".
3. Save. Existing rows are read-only and can only be deleted; to change one, delete the row and enter it again. The set can then be assigned in the API key or role (selection field "Access Right Set"; a jump icon opens the set).

Warning: Changes to a set affect all keys and roles to which it is assigned.

Default sets for kiosks

For kiosk keys, Webdesk creates a set named Default <type> Kiosk Access Right Set on first demand (type = PTM, TA or PTM_TA) and assigns it to the new key. The sets contain (all granting):

Selector	Privilege	in set
/rest/po/kiosks*	FULL	PTM, TA
/rest/po/nfctags*	FULL	PTM, TA
/rest/ptm/*	FULL	PTM, TA
/image/*	READ	PTM, TA
/rest/ta/*	FULL	nur TA only

"Default PTM_TA Kiosk Access Right Set" vereinigt die Rechte beider Sets. Ein einmal angelegtes Set wird über seinen Namen wiedergefunden; spätere Änderungen an der Standardkonfiguration verändern ein bestehendes Set nicht. Man kann ein Set jedoch in der "Zugriffsrecht Sammlung" bearbeiten, dann ändern sich die Rechte aller Kiosks dieses Typs.

Wie die Berechtigung eines Aufrufs entschieden wird

Für einen API-Key-Aufruf werden die Rechte des Keys und aller seiner Sets zusammengeführt und gegen Pfad und HTTP-Methode des Aufrufs geprüft:

Der Pfad des Aufrufs (ohne Kontextpfad, z. B

combines the rights of both sets. A set that has been created once is found again by its name; later changes to the default configuration do not change an existing set. However, a set can be edited in "Accessright Sets", which changes the rights of all kiosks of that type.

How the authorization of a call is decided

For an API key call, the rights of the key and of all its sets are merged and checked against the path and HTTP method of the call:

1. The path of the call (without context path, e.g. /rest/po/kiosks/4711) wird mit den Selektoren verglichen. Methode und benötigtes Privileg ergeben sich aus der obigen Tabelle.
2. Ein Selektor ohne Platzhalter, der genau dem Pfad entspricht und für das benötigte Privileg ein Recht enthält, entscheidet sofort (erlaubt oder abgelehnt).
3. Sonst entscheidet unter den passenden Selektoren mit Platzhalter der spezifischste, das ist der mit den meisten Zeichen, die keine Platzhalter sind. Selektoren ohne Recht für das benötigte Privileg zählen dabei nicht. Bei gleich spezifischen Selektoren ist die Reihenfolge nicht festgelegt; solche Überschneidungen sollten vermieden werden.
4. Innerhalb desselben Selektors gewinnt "Ablehnen" immer gegen "erlauben", unabhängig von der Reihenfolge.
5. FULL wirkt wie READ, CREATE, UPDATE und DELETE. Erlaubt ein Selektor UPDATE oder CREATE, ist READ für diesen Selektor mit erlaubt (sofern READ dort nicht abgelehnt ist).
6. Trifft kein Recht zu, ist der Aufruf nicht berechtigt (403). Es gibt keinen Standard-Zugriff.

Für Session-Aufrufe werden dieselben Regeln auf die Rechte der Rollen des Benutzers angewendet. Auch hier gilt: kein passendes Recht bedeutet 403.

Beispiel: Schlüssel für ein Terminal, das nur lesen darf

Ein externes Terminal soll Personendaten abrufen, aber nichts verändern. (Die Pfade sind Beispiele; die tatsächlichen Pfade eines Endpunkts zeigt die Swagger UI

1. is compared with the selectors. Method and required privilege result from the table above.
2. A selector without wildcards that equals the path exactly and contains a right for the required privilege decides immediately (allowed or denied).
3. Otherwise, among the matching selectors with wildcards the most specific one decides, i.e. the one with the most characters that are not wildcards. Selectors without a right for the required privilege are not considered. For selectors of equal specificity the order is not defined; such overlaps should be avoided.
4. Within the same selector, "Deny" always wins over "allow", regardless of the order.
5. FULL acts like READ, CREATE, UPDATE and DELETE. If a selector allows UPDATE or CREATE, READ is also allowed for that selector (unless READ is denied there).
6. If no right applies, the call is not authorized (403). There is no default access.

For session calls, the same rules are applied to the rights of the user's roles. Here too, no matching right means 403.

Example: a key for a terminal that may only read

An external terminal is to retrieve person data but change nothing. (The paths are examples; the Swagger UI shows the actual paths of an endpoint.)

1. "System" > "Zugriffsrecht SammlungAccessright Sets" > "Neues Zugriffsrecht New Access Right Set": "Name" = Terminal nur lesen. Zeile hinzufügenread only.
2. Add a row: "SelektorSelector" = /rest/po/persons/*, "PrivilegPrivilege" = READ, "AblehnenDeny" nicht gesetztnot checked. SpeichernSave.
3. "System" > "API Keys" > "Generate New API Key": "API Consumer" = Terminal Eingang Wien; im Abschnitt "Api Key Zugriffsrecht-Sets" das Set "Terminal nur lesen" hinzufügen; speichern. Den angezeigten Schlüssel im Terminal als Header Main Entrance; add the set "Terminal read only" in the section "Api Key Access Right Sets"; save.
4. Enter the displayed key in the terminal as the header X-Auth-Token eintragen.

Ergebnis Result: GET /rest/po/persons/... wird beantwortet is answered. POST, PUT oder DELETE auf denselben Pfad sowie jeder Aufruf eines anderen Pfads liefern 403. Wird später der Zugriff entzogen, genügt es, das Set zu ändern oder den Key über "ungültig machen" zu sperren (401). Hinweis: Der Terminal-Key aus diesem Beispiel ist keinem Kiosk zugeordnet und kann daher keine Benutzer-Identifikation or DELETE on the same path, and every call to another path, return 403. If access is to be withdrawn later, it is enough to change the set or to block the key with "Invalidate" (401).

Note: The terminal key in this example is not assigned to a kiosk and therefore cannot use user identification (User-Identification-...) verwenden. Keys für Kiosks entstehen über die Kiosk-Verwaltung.

Fehlersuche: 401 und 403

Antwort

mögliche Ursachen und Prüfung

401 (nicht authentifiziert)

Header X-Auth-Token fehlt oder ist leer und es gibt keine Session.

Der Key ist unbekannt (Tippfehler, gelöscht) oder nicht mehr gültig: in "API Keys" "Gültig von"/"Gültig bis" prüfen.

Impersonation: beide

for kiosks are created through the kiosk administration.

Troubleshooting: 401 and 403

Der Key ist gültig, aber kein Recht passt auf Pfad und Methode, oder ein "Ablehnen"-Recht greift. Im API-Key die Sets und Rechte prüfen: stimmt der Selektor (beginnt mit /rest/, ohne Kontextpfad)? Passt das Privileg zur Methode

Response	Possible causes and what to check
401 (not authenticated)	The header X-Auth-Token is missing or empty and there is no session. The key is unknown (typo, deleted) or no longer valid: check "Valid from"/"Valid till" in "API Keys". Impersonation: both User-Identification-...-Header gleichzeitig, leerer Wert oder keine Person zur Karte bzw. UID gefunden. Nicht unterstützte HTTP-Methode (z. B. HEAD) oder ein unerwarteter Fehler; dann steht im Server-Log headers at the same time, an empty value, or no person found for the card or UID. Unsupported HTTP method (e.g. HEAD) or an unexpected error; the server log then contains "Problem during authentication/authorization.". Session -Aufruf: Sitzung abgelaufen oder nie angemeldet call: session expired or never logged in (/rest/auth/login liefert bei falscher Anmeldung 401 returns 401 for a failed login).
403 (nicht berechtigt)	not authorized)	The key is valid, but no right matches path and method, or a "Deny" right applies. Check the sets and rights in the API key: is the selector correct (starts with /rest/, without context path)? Does the privilege match the method (GET = READ, POST = CREATE)? Endet der Pfad mit einem Schrägstrich, den der Selektor nicht abdeckt? Impersonation mit einem Key, der keinem Kiosk zugeordnet ist, oder mit einer Person eines anderen Mandanten. Session-Aufruf: die Rollen des Benutzers haben kein passendes Recht (Rollenmaske, Reiter "Zugriffsrechte").

Zusätzlich protokolliert der Dienst auf Debug-Ebene für jede Prüfung eine Zeile der Art

Does the path end with a slash that the selector does not cover? Impersonation with a key that is not assigned to a kiosk, or with a person of another client. Session call: the user's roles have no matching right (role screen, tab "Access Rights").

In addition, the service logs a line of the form "Check if api key ... has permission to make a GET call over /rest/..." . Sie nennt Methode und Pfad des Aufrufs (Logger at debug level for every check. It names the method and path of the call (logger at.workflow.webdesk.po.impl.PoAccessRightServiceImpl).

Browser -Clients: CORS

Für Aufrufe aus Browsern, die von einer anderen Adresse stammen, setzt Webdesk die CORS-Header. Die erlaubten Ursprünge stehen im Systemparameter allowedOriginsForCORS der Bean SecurityHeadersOptions (Maske

clients: CORS

For calls from browsers originating from a different address, Webdesk sets the CORS headers. The allowed origins are defined in the system parameter allowedOriginsForCORS of the bean SecurityHeadersOptions (screen "Systemparameter"). Eine Anfrage mit passendem Origin erhält A request with a matching Origin receives Access-Control-Allow-Origin mit diesem Wert und with that value and Access-Control-Allow-Credentials: true. Einträge dürfen Entries may contain * enthalten, ze. Bg. https://app.example.com oder or https://*.example.com. Erlaubte Request-Header sind u. a. Allowed request headers include X-Auth-Token, User-Identification-NfcCard und and User-Identification-Useruid. Native Apps und Terminals senden keinen Origin-Header und sind davon nicht betroffen.

Achtung: Im ausgelieferten Standard ist die Liste leer. In diesem Fall wird jeder gesendete Origin unverändert zurückgegeben, d. h. es wird jeder Ursprung erlaubt. Für Systeme, die aus dem Internet erreichbar sind, sollten die erlaubten Ursprünge eingetragen werden.

Sicherheitshinweise

• CSRF ist in Webdesk derzeit nicht implementiert. Der Schutz über die sitzungsgebundene Continuation-ID der Formulare gilt nicht für REST-Aufrufe und login_process. Das ist bei der Bewertung von Sicherheitsthemen und beim Hinzufügen neuer POST-Endpunkte zu beachten.
• Kurzlebige Anmelde-Tokens (LoginTokenUtils, z. B. für serverseitige Report-Downloads mit Benutzerwechsel) und der temporäre Zugriff über security-key liegen im Cache des jeweiligen Knotens. Im Cluster können Aufrufe, die auf einem anderen Knoten landen, deshalb scheitern, wenn die Requests nicht auf einen Knoten fixiert werden.
• Session- und Cookie-Einstellungen (z. B. SameSite, Header, Timeouts) sind umgebungsabhängig und müssen vor Ort geprüft werden.

Swagger UI und Postman-Collection

Swagger UI: Der Menüeintrag

apps and terminals do not send an Origin header and are not affected.

Warning: In the delivered default the list is empty. In that case every Origin that is sent is returned unchanged, i.e. every origin is allowed. For systems reachable from the internet, the allowed origins should be entered.

Security notes

• CSRF is currently not implemented in Webdesk. The protection through the session-bound continuation id of forms does not apply to REST calls and login_process. Keep this in mind when assessing security topics and when adding new POST endpoints.
• Short-lived login tokens (LoginTokenUtils, e.g. for server-side report downloads with user switching) and temporary access via security-key reside in the cache of the respective node. In a cluster, calls that land on another node can therefore fail unless requests are pinned to one node.
• Session and cookie settings (e.g. SameSite, headers, timeouts) depend on the environment and must be verified on site.

Swagger UI and Postman collection

• Swagger UI: The menu entry "Swagger Rest-API Explorer" (Admin-Menü admin menu "System") öffnet in einem neuen Fenster opens rest/swagger-ui/index.html mit den REST-Endpunkten von Webdesk, ihren Pfaden, Methoden und Parametern. Aufrufe aus der Swagger UI laufen mit der Sitzung des angemeldeten Benutzers. Zulässig sind sie für Systemadministratoren und für Benutzer, die über irgendeine ihrer Aktionen Zugriffsrechte auf den Endpunkt haben. Die Swagger UI eignet sich, um Pfade für Selektoren nachzuschlagen. Postman-Collection: Im Repository liegt in a new window, showing the REST endpoints of Webdesk with their paths, methods and parameters. Calls from the Swagger UI run with the session of the logged-in user. They are permitted for system administrators and for users who have access rights for the endpoint through any of their actions. The Swagger UI is useful for looking up paths for selectors.
• Postman collection: The repository contains postman/Webdesk - Public API.postman_collection.json. Sie enthält den Aufruf It contains the call "Login" (POST {{restURL}}/auth/login) sowie Beispielaufrufe zur Zeitwirtschaft (Abwesenheitsgründe, eigene Buchungen, aktueller Status, Buchung auslösen). Die Variable restURL ist in der Collection nicht vorbelegt und muss auf die REST-Basisadresse des Systems (Webdesk-Adresse mit Zusatz /rest) gesetzt werden. Die Collection verwendet die Anmeldung per Session, keine API-Keysand sample calls for time and attendance (absence reasons, own bookings, current state, performing a booking). The variable restURL is not preset in the collection and has to be set to the REST base address of the system (Webdesk address plus /rest). The collection uses the session login, not API keys.