Externer Meeting Autorisierungs–Service

Überblick

Mit der Web-Meeting-Plattform können Benutzer den Zugang zu Sitzungen auf verschiedene Weise einschränken. Eine Möglichkeit besteht darin, den Autorisierungsprozess an einen externen Webdienst zu delegieren. Dieser externe Webservice ist für die Authentifizierung und Autorisierung der Sitzungsteilnehmenden verantwortlich.

Dieses Dokument beschreibt, wie ein solcher Sitzungs-Autorisierungsdienst implementiert werden muss.

Architektur

Um einer geschützen Sitzung beizutreten, fordert der Webbrowser ein "Request Token" von der Web-Meeting-Plattform an. Das System leitet den Browser danach automatisch an den vorkonfigurierten Autorisierungsdienst weiter. Diese Weiterleitung enthält neben anderen Informationen auch disen "Request Token".

Der externe Autorisierungsdienst führt den Autorisierungs- und Genehmigungsprozess durch. Der Dienst kontaktiert den Web-Meeting-Server, um das "Request Token" gegen ein "Access Token" auszutauschen, sobald er festgestellt hat, dass der Benutzer am Meeting teilnehmen darf. Um den Vorgang abzuschliessen, wird der Browser an die Web-Meeting-Plattform weitergeleitet. Diese Weiterleitung enthält das "Access Token", welcher dem Browser den Zugang zu dieser Sitzung gewährt.

Implementierungsdetails - HTTP GET zum Autorisierungsdienst

Der externe Meeting-Autorisierungsdienst muss eine "HTTP GET"-API implementieren und diese URL in der Web-Meeting-Plattform konfigurieren (siehe unten)

Der Webbrowser wird zu dieser API-URL umgeleitet. Die Anfrage wird mindestens die folgenden URL-Parameter enthalten:

Neben den oben definierten Pflichtparametern können weitere Abfrageparameter übergeben werden.

Beispiel:

Wenn die neue API auf https://external.example.org/auth, hört, dann leitet die Web-Meeting-Plattform den Benutzer an folgende URL weiter:

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&optionalParameter1=optionalValue1&optionalParameter2=optionalValue2

Implementierungsdetails - Austausch von Request Token gegen Access Token

Sobald der Dienst den Nutzer autorisiert hat, muss er den Request-Token gegen ein Access-Token austauschen. Die Web-Meeting-Plattform bietet hierfür eine API:

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

Ersetzen Sie im obigen Beispielaufruf die Werte zwischen den Klammern (z. B. <HOSTNAME>) durch die folgenden Parameter:

Die Web-Meeting-Plattform überprüft den Request-Token, um sicherzustellen, dass er für die Meeting-ID ausgestellt wurde. Bei Erfolg antwortet die API mit einem JSON-Dokument in der folgenden Form:

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

Der responseCode ist 0 (Null), das Objekt "data" enthält eine Zeichenkette "accessToken". Dieser Access-Token wird im letzten Schritt verwendet.

Implementierungsdetails - Weiterleitung des Benutzers zurück zur Web-Meeting-Plattform

Sobald ein Access Token empfangen wurde, muss der Benutzer zur Web-Meeting-Plattform umgeleitet werden. Die URL muss wie folgt lauten:
https://<HOSTNAME>/join/<MEETING-TOKEN>?meetingAccessToken=<ACCESS-TOKEN>

Ersetzen Sie im obigen Beispiel die Werte zwischen den Klammern (z. B. <HOSTNAME>) durch die folgenden Parameter:

Zusätzlich können folgende URL Parameter weitergegeben werden:

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

Konfigurieren Sie die Web-Meeting-Plattform

Nachdem der Autorisierungsdienst implementiert wurde, müssen Sie die Web-Meeting-Plattform entsprechend konfigurieren. Wählen Sie unter "Plattformeinstellungen" -> "Systemkonfiguration" -> "Sitzungsraum" die Option "Externer Dienst" als "Standardauthentifizierungstyp für Sitzungen". aus Daraufhin werden zwei zusätzliche Konfigurationsfelder geöffnet:

Geben Sie die vollständige API-URL in das Feld "URL des externen Authentifizierungsservers" ein. Ausserdem müssen Sie das oben definierte SECRET in das Feld "API-Schlüssel des externen Authentifizierungsservers" eingeben. Die Web-Meeting-Plattform speichert das SECRET in verschlüsselter Form. Alle API-Aufrufe zum Austausch eines "Request Token" gegen ein "Access Token" werden anhand dieses SECRET überprüft.

Beispielimplementation in NodeJS

const express = require('express')
const app = express()
const port = 3000

const SECRET = "MySecret"

app.get('auth', (req, res) => {
  // Read mandatory parameters
  const hostname = req.query.hostname;
  const meetingId = req.query.meetingId;
  const meetingToken = req.query.meetingToken;
  const requestToken = req.query.requestToken;

  // TODO: Implement authentication and authorization process here

  // User is authorized to join the meeting, exchange request token for access token
  const url = `https://${hostname}/api/v6/meeting-room/auth/${SECRET}/access-token/${meetingId}/${requestToken}`;

  const options = {
    url: url,
    method: "GET",
    headers: { "Content-Type": "application/json; charset=utf-8"},
  };

  request(options, (err, res, body) => {
    const response = JSON.parse(body);

    // Access token received
    const accessToken = response.data.accessToken;

    const redirectUrl = `https://${hostname}/${meetingToken}/join?meetingAccessToken=${accessToken}`;

    res.redirect(redirectUrl)
  });
})

app.listen(port, () => {
  console.log(`Example app listening on https://external.example.org`)
})