Externer Autorisierungsdienst

Übersicht

Sie können den Zugang zu einem Meeting auf verschiedene Arten einschränken. Bei einer davon entscheidet ein Dienst von Ihnen, wer beitreten darf. So gelten für das Meeting genau die Regeln, die Ihre Systeme ohnehin durchsetzen, etwa ein Kundenportal, eine Patientenakte oder ein Falldossier.

Diese Seite zeigt Ihnen, wie Sie diesen Dienst bauen.

Verwendung mit einem KI-Assistenten

Viele Integrationen entstehen heute mit einem KI-Assistenten. Arbeiten Sie ebenso, dann kopieren Sie den folgenden Text in Ihren Assistenten und schreiben Sie einen Satz dazu, was Sie bauen möchten.

Der Text schickt den Assistenten zuerst auf diese Seite und warnt ihn vor den wenigen Dingen, die er sonst gerne falsch macht.

Lies zuerst diese Seite, bevor Du Code schreibst:
https://www.veeting.com/de/developer-documentation/external-meeting-authorization-service

Sie beschreibt, wie ich Teilnehmer mit meinem eigenen Dienst
autorisiere. Halte Dich an diese fünf Regeln:

1. Der Tokentausch läuft von Server zu Server. Die URL enthält ein
   gemeinsames Geheimnis. Rufe sie also nie aus einem Browser auf
   und logge sie nie.
2. Prüfe beim Tausch responseCode 0, nicht nur HTTP 200.
3. Leite zurück auf /meeting/<MEETING-TOKEN>/join und hänge
   meetingAccessToken als Query-Parameter an.
4. Der Tausch braucht die 24-stellige meetingId, die Rückleitung
   die meetingToken mit Bindestrichen. Verwechsle die beiden
   nicht.
5. Der Request-Token belegt, dass die Plattform die Person zu mir
   geschickt hat. Er authentifiziert sie NICHT. Das muss ich
   selbst tun.

Was ich bauen möchte:

Wie der Austausch funktioniert

Der Ablauf ist eine dreistufige Weiterleitung und ähnlich aufgebaut wie OAuth.

1. Ein Teilnehmer öffnet ein eingeschränktes Meeting. Die Plattform erzeugt einen Request-Token und leitet den Browser mit diesem Token zu Ihrem Dienst.
2. Ihr Dienst authentifiziert die Person auf Ihre Weise und entscheidet, ob sie beitreten darf.
3. Darf sie beitreten, ruft Ihr Dienst uns von Server zu Server auf und tauscht den Request-Token gegen einen Access-Token.
4. Ihr Dienst leitet den Browser mit dem Access-Token zurück zum Meeting. Dieser Token öffnet der Browsersession den Zugang.

Der Request-Token belegt, dass die Plattform die Person zu Ihnen geschickt hat. Der Access-Token belegt, dass Sie sie zurückgeschickt haben.

Schritt 1: die Weiterleitung entgegennehmen

Bauen Sie einen Endpunkt, der auf HTTP GET antwortet. Dorthin leiten wir den Browser, und wir hängen mindestens diese Query-Parameter an:

Wir können weitere Parameter anhängen. Lesen Sie die Parameter, die Sie brauchen, deshalb über ihren Namen aus und nicht über ihre Position.

Lautet Ihr Endpunkt https://external.example.org/auth, kommt der Browser hier an:

https://external.example.org/auth?hostname=webmeeting.example.com&meetingId=5f521a93c20ff6721fbb6a6c&meetingToken=8320-2640-2482-3499&requestToken=dedf1722-661f-4004-9aaf-d3e56c498859-a27fd10f-b697-4c83-bca0-cb764cfd6c43

Schritt 2: den Request-Token eintauschen

Sobald Sie entschieden haben, dass die Person beitreten darf, rufen Sie uns auf und tauschen den Request-Token gegen einen Access-Token:

GET https://<HOSTNAME>/api/v6/meeting-room/auth/<SECRET>/access-token/<MEETING-ID>/<REQUEST-TOKEN>

Wir prüfen, ob wir den Request-Token für dieses Meeting ausgestellt haben. Stimmt alles, antworten wir so:

{
  "responseCode": 0,
  "data": {
    "meetingId": "5f521a93c20ff6721fbb6a6c",
    "accessToken": "81430667-540e-4755-b32a-b5c51f704c7b-03526573-1494-48fb-a648-e80073275976"
  }
}

Dieser Aufruf folgt den üblichen Konventionen der REST API. Prüfen Sie deshalb responseCode und nicht nur den HTTP-Status. Den Token lesen Sie aus data.accessToken. Wie der Response-Wrapper aufgebaut ist, lesen Sie unter REST APIs.

Dieser Aufruf führt Ihr Geheimnis in der URL mit. Rufen Sie ihn von Server zu Server auf, nie aus dem Browser. Und loggen Sie die vollständige URL nirgends.

Schritt 3: zurück zum Meeting leiten

Schicken Sie den Browser mit dem Access-Token zum Meetingraum:

https://<HOSTNAME>/meeting/<MEETING-TOKEN>/join?meetingAccessToken=<ACCESS-TOKEN>

Hängen Sie weitere Query-Parameter an, um der Person die Ankunft zu erleichtern. Am ehesten lohnen sich jene Werte, die Sie aus der eben erfolgten Authentifizierung schon kennen:

https://<HOSTNAME>/meeting/<MEETING-TOKEN>/join?meetingAccessToken=<ACCESS-TOKEN>&participantName=<NAME>&participantEmail=<EMAIL>

Die Plattform konfigurieren

Gehen Sie zu Platform Settings, dann System Configuration, dann Meeting Room. Wählen Sie dort als Standard-Authentifizierungsart für Meetings External Service. Danach erscheinen zwei Felder.

Tragen Sie die vollständige URL Ihres Endpunkts in «URL of external authentication server» ein und Ihr gewähltes Geheimnis in «API Key of external authentication server». Wir speichern das Geheimnis verschlüsselt und prüfen jeden Tokentausch dagegen.

Das Geheimnis erfinden Sie selbst. Behandeln Sie es wie ein Passwort: lang und zufällig. Gelangt es je nach aussen, wechseln Sie es.

Eine minimale Umsetzung

const express = require("express");
const app = express();
const port = 3000;

// Invent this yourself and configure the same value in the platform.
const SECRET = process.env.VEETING_SHARED_SECRET;

app.get("/auth", async (req, res) => {
  const { hostname, meetingId, meetingToken, requestToken } = req.query;

  // Decide here whether this person may join, using your own session,
  // directory or customer database. Redirect them away if they may not.
  if (!(await mayJoin(req, meetingId))) {
    return res.status(403).send("Not authorized to join this meeting");
  }

  // Server to server: this URL contains the shared secret.
  const url = `https://${hostname}/api/v6/meeting-room/auth/${SECRET}`
    + `/access-token/${meetingId}/${requestToken}`;

  const response = await fetch(url).then((r) => r.json());

  // HTTP 200 is not enough on its own, check responseCode too.
  if (response.responseCode !== 0) {
    return res.status(502).send("Could not obtain an access token");
  }

  const accessToken = response.data.accessToken;

  res.redirect(`https://${hostname}/meeting/${meetingToken}/join`
    + `?meetingAccessToken=${encodeURIComponent(accessToken)}`);
});

app.listen(port);

Häufige Fehler

• Auf den falschen Pfad weiterleiten. Der Meetingraum liegt unter /meeting/<MEETING-TOKEN>/join.
• Bei der Rückleitung die 24-stellige meetingId verwenden. Dort gehört die meetingToken mit Bindestrichen hin, beim Tokentausch ist es genau umgekehrt.
• Beim Tokentausch nur den HTTP-Status prüfen und responseCode übersehen.
• Den Tausch-Endpunkt aus dem Browser aufrufen und so Ihr Geheimnis preisgeben.
• Die Tausch-URL loggen und so das Geheimnis ebenfalls preisgeben.
• Die Person an Ihrem Endpunkt durchwinken, ohne sie wirklich zu authentifizieren. Der Request-Token belegt die Herkunft, nicht die Identität.