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, ob sie nun in einem Kundenportal, einer Patientenakte oder einem Falldossier stehen.

Diese Seite zeigt Ihnen, wie Sie diesen Dienst bauen.

Verwendung mit einem KI-Assistenten

Wenn Sie mit einem KI-Coding-Assistenten arbeiten, können Sie den folgenden Text in Ihren Assistenten kopieren und mit einem Satz ergänzen, der beschreibt, was Sie programmieren möchten.

Der Prompt verweist auf unsere Entwicklerdokumentation, die wir für Coding-Assistenten in einer separaten, token-optimierten KI-Version ausliefern.

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. Der Tausch war nur erfolgreich, wenn responseCode 0 ist,
   data.responseState VALID lautet und data.accessToken nicht null
   ist. Auch ein abgelaufener oder schon verwendeter Request-Token
   liefert HTTP 200 und responseCode 0. Leite nie mit einem
   null-Token weiter.
3. Leite zurück auf /meeting/<MEETING-TOKEN>/join und hänge
   meetingAccessToken als Query-Parameter an.
4. Der Tausch braucht die 24 Zeichen lange meetingId, die Rückleitung
   den meetingToken mit Bindestrichen. Verwechsle die beiden
   nicht.
5. Der Request-Token belegt, dass die Plattform die Person zu mir
   geschickt hat. Er authentifiziert die Person 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 verschafft der Browser-Session Zugang zum Meeting.

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

Schritt 1: die Weiterleitung entgegennehmen

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

Wir können weitere Parameter anhängen. Lesen Sie deshalb die Parameter, die Sie brauchen, über den Namen aus, nicht über die 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",
    "responseState": "VALID"
  }
}

Erfolg heisst dreierlei: responseCode ist 0, data.responseState lautet "VALID", und data.accessToken ist nicht null. Auch ein unbekannter, abgelaufener oder schon verwendeter Request-Token liefert HTTP 200 und responseCode: 0, dann aber mit data.accessToken: null, und data.responseState lautet "EXPIRED", "INVALID_REQUEST_TOKEN" oder "INVALID_CHALLENGE". Ein falsches Geheimnis oder ein nicht konfigurierter Dienst ergibt -33. Wie der Response-Wrapper aufgebaut ist, steht 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>

Sie können weitere Query-Parameter anhängen, damit die Person leichter ankommt. Am meisten bringen die Werte, die Sie aus der Authentifizierung ohnehin 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. Ihr gewähltes Geheimnis kommt in «API Key of external authentication server». Wir speichern das Geheimnis als Hash 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 secret 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 and responseCode 0 are not enough on their own: an expired
  // or reused request token also returns them, with a null accessToken.
  const data = response.data;
  if (response.responseCode !== 0 || !data
      || data.responseState !== "VALID" || !data.accessToken) {
    return res.status(502).send("Could not obtain an access token");
  }

  const accessToken = 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 Zeichen lange meetingId verwenden. Dort gehört der meetingToken mit Bindestrichen hin, beim Tokentausch ist es genau umgekehrt.
• HTTP 200 und responseCode: 0 beim Tokentausch als Erfolg werten. Prüfen Sie zusätzlich, dass data.responseState auf "VALID" steht und data.accessToken nicht null ist.
• 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.