STARFACE WIKI (Deutsch)

Page tree

Suche

Alter Login-Mechanismus abgekündigt

Mit der Einführung von STARFACE 10 und den STARFACE Cloud Services wird der klassische Login-Mechanismus in zukünftigen Versionen nicht mehr verfügrabr sein. Aus Kompatibilitätsgründen ist der klassische Login-Mechanismus in dieser Version der STARFACE noch verfügbar, er wird jedoch mit der STARFACE 11 endgültig wegfallen. Die Zeit bis zur Version 11 der STARFACE sollte daher unbedingt genutzt werden, um Integration auf den neuen Authentifizierungsmechanismus umzustellen.

In bestimmten Szenarien kann aber schon mit der STARFACE 10 der klassische Login-Mechanimsus nicht mehr genutzt werden. Im Folgenden wird deshalb erläutert, wie sich die Einführung von OAuth 2.0 auf Module und Integrationen auswirkt und welche Anpassungen an bestehenden API-Clients erforderlich sind.

Hinweise zur Migration

Ab STARFACE 10 ist OAuth 2.0 der Standard-Authentifizierungsmechanismus. Daher wird empfohlen, alle Integrationen auf OAuth 2.0 umzustellen.

Auch wenn der klassische Login-Mechanismus in der STARFACE 10 prinzipiell noch funktioniert, gibt es Szenarien in denen dieser nicht nutzbar ist:

  • Wenn ein externer IdP aktiviert wird (z.B. Microsoft Entra ID oder Google)
  • Wenn die Cloud Services (aka. STARFACE Hub) aktiviert sind

Um sicherzustellen, dass Integrationen mit diesen beiden Szenarien kompatibel sind, ist eine Anpassung auf Clientseite zwingend erforderlich, da sich API-Clients sonst nicht mehr anmelden können.

Anpassung der Authentifizierung

In der STARFACE 10 unterstützen alle Schnittststellen (APIs) OAuth 2.0 als Authentifiziermechanismus. Die STARFACE PBX und Cloud Services verhalten sich standardkonform, sodass auf Integrationsseite beliebige OAuth-Implementierungen genutzt werden können.

Die STARFACE PBX unterstützt folgende OAuth 2.0 Grant Typen:

Die Endpunkte können über die Discovery URL der PBX abgerufen werden

https://<pbx-host>/.well-known/openid-configuration.

In bestimmten Ausnahmefällen ist es jedoch nicht ganz offensichtlich, wie die Authentifizierung durchzuführen ist. Für zwei dieser Szenarien wird im Folgenden exemplarisch eine Lösung aufgezeigt.

Szenario 1: Desktop-Applikation mit Zugriff auf UCI3-Schnittstelle

Beschreibung der Ausgangssituation:

Die Integration läuft auf dem gleichen System wie die STARFACE App für Windows und authentifiziert sich bisher über Login-ID und Passwort des Benutzers, zum Beispiel um Ruflisteneinträge von der STARFACE PBX abzurufen und in ein externes System zu exportieren.

STARFACE 10 und höher:

Die Integration nutzt den OAuth 2.0 Authorization Code Flow mit PKCE. 

Client-Einstellungen:

client_id = "rest-client" # public client, daher kein secret benötigt
redirect_uri = http://127.0.0.1:8000 # Beispiel, weitere redirect URIs siehe unten
grant_type = code
scopes = ["pbx-admin pbx-login"] # pbx-admin ist optional und wird nur für den Zugriff auf die Admin REST-API benötigt

Hinweis: Bei den Scopes, ist das Präfix pbx zu beachten! Die Namen der Scopes haben sich gegenüber der OAuth für Admins-Implementierung der STARFACE 9 geändert.

Weitere akzeptierte redirect URIs:

  • AUTO_DETECT_BASE_URL/**
  • http://127.0.0.1/**
  • http://127.0.0.1:**/**
  • http://[::1]/**
  • http://[::1]:**/**

Zusätzlich ist zu beachten:
  • Die AUTO_DETECT_BASE_URL entspricht dem Hostname, der STARFACE PBX über den die Web UI der STARFACE PBX aufgerufen wurde.
  • Der “localhost” wird in der redirect uri nicht unterstützt. Der OAuth-Standard sieht stattdessen vor, für diesen Fall die loopback-IP als Redirect URI zu nutzen.

Szenario 2: Module mit XML-RPC-Schnittstelle

Beschreibung der Ausgangssituation

Die Integration läuft als Modul auf der PBX und bietet nach außen hin eine oder mehrere XML-RPC-Funktionen an. Eine autonome Client-Anwendung (ohne Benutzerinteraktion) greift auf diese XML-RPC-Funktionen zu und authentifiziert sich mittels Login-ID und Passwort eines vordefinierten Benutzers auf der PBX (sog. "Service Account").

STARFACE 10 und höher:

Die Integration nutzt den OAuth 2.0 Resource Owner Password Credentials Flow (RPOC).

Client-Einstellungen:

client_id = "rest-client-headless"
client_secret = "rest-client-headless-xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb" # Client Secret wie in der Admin UI der PBX (Server) angegeben (siehe Abb. unten)
grant_type = password
scopes = ["pbx-login"]
username = "8983" # Login-ID des Service Accounts
password = <local_user_pw> # Passwort des Service Accounts auf der PBX
token_endpoint = https://<PBX_HOST>/auth/realms/pbx/oauth2/token

Die Anbindung findet sich auf der STARFACE PBX im Bereich Server → Status (siehe auch Serverkonfiguration der STARFACE konfigurieren)

Damit die Anmeldung über OAuth RPOC funktioniert, benötigt der Benutzer (Service Account) die Berechtigung "API Zugriff mit OAuth Password Grant" (siehe Rechte eines Benutzer konfigurieren).

Beispiel für die Authentifizierung mittels OAuth 2.0 RPOC
curl --location 'http://<PBX_HOST>/auth/realms/pbx/oauth2/token' \
	 --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'client_id=rest-client-headless' \
     --data-urlencode 'client_secret=rest-client-headless-XXXXXXXXXXXXXXXXXXXXX-SEE-ADMIN-UI' \
     --data-urlencode 'username=8983' \
     --data-urlencode 'password=localuserpw'

Wenn auf der PBX ein externer Idenity Provider (IdP) konfiguriert ist, funktioniert der RPOC mit den o.g. Einstellungen weiterhin. Allerdings, müssen für die Anmeldung Zugangsdaten eines lokalen Benutzerkontos auf der PBX verwendet werden.

Hinweis: Die Zugangsdaten eines externen IdP funktionieren hier hingegen nicht.

Der in der JSON-Response enthaltene „access_token“ im JWT-Format, muss dann mit jedem Aufruf als String über den query-parameter „de.vertico.starface.jwt“ an die XML-RPC-Schnittstelle übergeben werden:

https://<PBX_HOST>/xml-rpc?de.vertico.starface.jwt=eyJraWQiOiJrZXktMSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiJhYmNkZTExMi0zNDU2LTdhODktYmNkZC04ZjczZWIxMjM0NTYiLCJpc3MiOiJodHRwczovL2V4YW1wbGUuc3RhcmZhY2UtY2xvdWQuY29tL2F1dGgvcmVhbG1zL3BieCIsImF6cCI6InBieC1ndWkiLCJzdWIiOiI1N2U4ZjM1MC0xMjM0LTU2NzgtOWFiYy0xMjM0NTY4NzgyOTAiLCJ1aWQiOjEyMzQsInByZWZlcnJlZF91c2VybmFtZSI6IjAwMDIiLCJleHAiOjE3NjYyMjcyODQsImlhdCI6MTc2NjIyNjk4NCwicm9sZXMiOlsxMCw0LDgsMzAsNDQsMjYsMjIsMzYsNyw0MCw2LDI4LDE0LDIzLDI1LDMxLDE5LDE4LDQ2LDE2LDExLDMsMjcsNDEsOSwxLDEzLDI0LDQyLDUsNDcsMjksMzMsMTcsNDUsMzJdLCJzaWQiOiJyaXNlcm5kMTIzLTQ1NjctNzg5MC0xMjM0LWFiY2RlZnRoaWprbCIsInR5cCI6IkJlYXJlciIsInNjb3BlIjoicGJ4LWxvZ2luIHBieC1hZG1pbiJ9.wCN69HBywnlvNpYby2F1KUSRNz9cbxkIsYBmE5jBd-SYzZIMbDmxZhEZA_vzUudmV6l1vLXYKm5MxspjObgwDw