Integrationsanleitung für die Remote Access API

Keine Bewertungen

Dieser Artikel richtet sich an TeamViewer Integrationspartner.

Allgemein

Mit der REACH API bietet TeamViewer eine API für die Integration in RMM- oder MDM-Lösungen, die eine Initiierung unbeaufsichtigter und beaufsichtigter Fernsteuerungssitzungen ermöglicht.

Dieser Artikel erläutert die grundlegenden Konzepte hinter der REACH API. Zudem enthält er Anweisungen und Empfehlungen für die Integration der API in eine Lösung zur Geräteverwaltung.

Der Artikel ist deshalb in unterschiedliche Abschnitte unterteilt, die Informationen über die verschiedenen Themen enthalten.

Das erste Kapitel erläutert den grundlegenden Ansatz und enthält eine Übersicht, weshalb bestimmte Sicherheitsmechanismen angewendet werden.

Anschließend wird die Implementierung exemplarisch erklärt. Diese basiert auf dem beispielhaften Quellcode einer Beispielintegration – die von TeamViewer entwickelte VendorExampleApp.

Im letzten Kapitel werden Einzelheiten zur Implementierung der Integration auf Android beschrieben.

Hinweis: Alle Code-Beispiele in diesem Artikel werden im Rahmen einer MIT-Lizenz veröffentlicht:

Copyright (c) 2018 TeamViewer GmbH

Hiermit wird unentgeltlich jeder Person, die eine Kopie der Software und der zugehörigen Dokumentationen (die „Software“) erhält, die Erlaubnis erteilt, sie uneingeschränkt zu nutzen, inklusive und ohne Ausnahme mit dem Recht, sie zu verwenden, zu kopieren, zu verändern, zusammenzufügen, zu veröffentlichen, zu verbreiten, zu unterlizenzieren und/oder zu verkaufen, und Personen, denen diese Software überlassen wird, diese Rechte zu verschaffen, unter den folgenden Bedingungen:

Der obige Urheberrechtsvermerk und dieser Erlaubnisvermerk sind in allen Kopien oder Teilkopien der Software beizulegen.

DIE SOFTWARE WIRD OHNE JEDE AUSDRÜCKLICHE ODER IMPLIZIERTE GARANTIE BEREITGESTELLT, EINSCHLIESSLICH DER GARANTIE ZUR BENUTZUNG FÜR DEN VORGESEHENEN ODER EINEM BESTIMMTEN ZWECK SOWIE JEGLICHER RECHTSVERLETZUNG, JEDOCH NICHT DARAUF BESCHRÄNKT. IN KEINEM FALL SIND DIE AUTOREN ODER COPYRIGHTINHABER FÜR JEGLICHEN SCHADEN ODER SONSTIGE ANSPRÜCHE HAFTBAR ZU MACHEN, DIE INFOLGE DER ERFÜLLUNG EINES VERTRAGES, EINES DELIKTES ODER ANDERS IM ZUSAMMENHANG MIT DER SOFTWARE ODER SONSTIGER VERWENDUNG DER SOFTWARE ENTSTANDEN SIND.

Wenn Sie die Software verwenden oder verbreiten, berücksichtigen Sie dabei gegebenenfalls etwaige Lizenzen von enthaltener Software von Dritten.

 

REACH API – Konzepte und Sicherheit

Die Konzepte der REACH API fallen letzten Endes in drei Anwendungsfälle:

  • Registrierung von Geräten, die über die REACH API verwaltet werden, auch als Rollout-Phase bezeichnet.
  • Aufhebung der Registrierung von Geräten, um den Zugriff über die REACH API zu beenden.
  • Die Steuerungsphase gestattet die Initiierung unbeaufsichtigter Sitzungen (Verbindung auf Geräte ohne Eingreifen von Benutzern an den entfernten Geräten) und beaufsichtigter Sitzungen (Benutzer an den entfernten Geräten erlauben die Verbindung manuell) auf registrierte Geräte.
    Beide Sitzungsmodi können Fernsteuerungssitzungen mit vollem Funktionsumfang umfassen oder auf Verbindungen mit reinen Leserechten beschränkt sein (nur auf bestimmten Plattformen unterstützt).

Registrierung von Geräten

Beim Rollout werden die Verschlüsselungscodes zwischen den Geräten und der Verwaltungslösung ausgetauscht. Diese Verschlüsselungscodes werden für die Phasen der Steuerung und der Aufhebung der Registrierung verwendet. Sie gewährleisten, dass die gesamte Kommunikation mit einem Gerät sicher ist.

Das Diagramm erläutert den Ablauf der Registrierung (auf Englisch):

REACH

Der Management Solution Agent (MSA) ist eine Komponente, die auf dem Gerät laufen muss. Dieser Agent muss über Administratorrechte auf dem Gerät verfügen und ruft die Daten ab, die für das erfolgreiche Abschließen der Rollout-Phase erforderlich sind.

Um den Rollout zu starten, liest der MSA eine spezielle Datei (Schritt 1), die beim Start des TeamViewer Client und nach jeder erfolgreichen oder fehlgeschlagenen Anfrage an den TeamViewer Client geschrieben wird.

Hinweis: Schritt 1 kann von Plattform zu Plattform variieren. Der Datei-Ansatz gilt nur für die Betriebssysteme Windows und macOS. Die für den Rollout bereitgestellten Daten sind jedoch bei allen Plattformen gleich. Konkrete Angaben zu Android finden Sie im Kapitel Android.

Die Datei enthält den RolloutKey (der ROK ist für eine Anfrage gültig und wird zur Entschlüsselung der API-Antwort verwendet), eine global eindeutige Kennung (GUID) sowie die RemotecontrolID des Geräts (TeamViewer ID).

Mit der RemotecontrolID und der GUID der Rollout-Daten und den Berechtigungen erfolgt ein API-Aufruf (POST /oem/devices/createdevicekey), um einen neuen Geräteschlüssel zu erstellen (Schritt 3).

Dieser API-Aufruf initiiert die Kommunikation vom TeamViewer Backend zum TeamViewer Ziel-Client.

Wenn die Daten gültig sind, erstellt der TeamViewer Client ein Schlüsselpaar für künftige Fernsteuerungssitzungen.

Der TeamViewer Client verschlüsselt den Private Key (=DeviceKey) des neu erstellten Schlüsselpaars mit dem RolloutKey und sendet dieses mit einer Kennung für dieses Schlüsselpaar sowie einem Stilllegungstoken als Antwort auf den API-Aufruf, wobei es das TeamViewer Backend durchläuft (Schritt 4).

Die Verwaltungslösung muss den zuvor erhaltenen RolloutKey zur Entschlüsselung des DeviceKey verwenden. Der DeviceKey ist mit dem Standard-PEM-Format verschlüsselt, um den Entschlüsselungsprozess zu vereinfachen .

Der DeviceKey und die DeviceKeyID werden in der Steuerungsphase verwendet, wohingegen das Stilllegungstoken verwendet wird, um die Registrierung eines DeviceKeys aufzuheben.

Hinweis: Der verschlüsselte DeviceKey, die DeviceKeyID und das Stilllegungstoken müssen auf der Seite der Verwaltungslösung sicher verwahrt werden.

Steuerungsphase

Nachdem der erste Schritt abgeschlossen wurde, ist es ab jetzt möglich, Fernsteuerungssitzungen zum registrierten Gerät zu initiieren. Mit den folgenden Schritten können Sie eine Fernsteuerungssitzung initiieren (auf Englisch):

REACH

 

Die Fernsteuerung ist erst möglich, nachdem das Gerät erfolgreich registriert wurde, da der DeviceKey und die DeviceKeyID für die Initiierung einer Fernsteuerungssitzung benötigt werden.

Der erste Schritt besteht in einem WebAPI-Aufruf (POST /oem/devices/requestcontrol) mit den Parametern RemotecontrolID, DeviceKeyID und dem Steuerungstyp. Diese Parameter werden an den Ziel-Client weitergegeben. Dieser verifiziert, dass der DeviceKey über die Steuerungsberechtigungen verfügt, die im API-Aufruf angefordert werden.

Nachdem die Anfrage erfolgreich verifiziert wurde, generiert der TeamViewer Ziel-Client einen temporären Authentifizierungscode zur einmaligen Verwendung (eine Authentifizierungsnachricht, die auf einer Hash-Funktion basiert, HMAC). Diese ist vergleichbar mit einem Sitzungskennwort.

Die Berechnung des HMAC erfolgt auf Basis der über die Steuerungsanfrage empfangenen Daten und weiterer Informationen (Ziel-Nonce, DeviceSecret), die vom TeamViewer Client generiert wurden.

Nach der Berechnung des HMAC verschlüsselt der Client das DeviceSecret mit dem DeviceKey, der im API-Aufruf mittels DeviceKeyID angegeben wurde.

Das DeviceSecret wird als Antwortparameter des API-Aufrufs EncryptedDeviceSecret zusammen mit dem Ziel-Nonce und einer URL-Vorlage für eine TeamViewer Protokoll-URL (teamviewerapi://) zurückgegeben, die den Platzhalter YOURMASTERSECRET enthält.

Die ISV Implementierung entschlüsselt das EncryptedDeviceSecret mit dem DeviceKey und berechnet den HMAC auf Grundlage des entschlüsselten Gerätekennworts, der Ziel-Nonce und anderer Informationen, die im API-Aufruf für die Steuerung gesendet werden.

Sobald der HMAC berechnet wurde, muss der Platzhalter YOURMASTERSECRET durch den HMAC ersetzt werden, um eine gültige TeamViewer Protokoll-URL zu erstellen.

Die komplette URL mit dem HMAC muss dem TeamViewer Ursprungs-Client präsentiert werden, um eine Verbindung aufzubauen.

Dies kann durch einen Browser oder als Befehlszeilenparameter erfolgen (das TeamViewer Protokoll wird am Betriebssystem registriert, wenn TeamViewer installiert wird und ist mit der TeamViewer Anwendung verknüpft).

Der TeamViewer Ursprungs-Client verwendet nun die Informationen in der URL einschließlich HMAC, um eine Verbindung zum Ziel-Client herzustellen.

Aufhebung der Registrierung

Falls ein DeviceKey nicht mehr verwendet werden soll, kann die Registrierung des DeviceKeys aufgehoben werden. Die Grafik stellt das Grundprinzip dar (auf Englisch):

REACH

Um die Registrierung eines DeviceKeys aufzuheben, wird der WebAPI-Aufruf DELETE /oem/devices/unregister verwendet.

Für eine erfolgreiche Durchführung muss der DeviceKeyID den richtigen Schlüssel, die RemotecontrolID des Geräts sowie das Stilllegungstoken identifizieren, das während des Rollouts im API-Aufruf POST /oem/devices/createdevicekey API ausgegeben wurde.

Diese Informationen werden anschließend vom TeamViewer Client auf dem Gerät verarbeitet.

Wenn die Informationen in der API mit den Informationen auf dem Client übereinstimmen, wird der lokale Teil des beim Rollout erstellten Schlüsselpaars gelöscht und eine Bestätigung über die WebAPI zurückgesendet.

Von diesem Zeitpunkt an kann keine weitere Fernsteuerungssitzung unter Verwendung dieses DeviceKey aufgebaut werden.

Integrationsbeispiel – die VendorExampleApp

Voraussetzungen

Um dieser Anleitung zu folgen und die Integration tatsächlich durchzuführen, sind während der verschiedenen Integrationsphasen einige Informationen erforderlich. Diese umfassen

  • Hersteller-ID
  • Tenant-Konto
  • Skript-Token mit Fernsteuerungsberechtigungen

Die Hersteller-ID wurde dem ISV von einem TeamViewer Repräsentanten mitgeteilt.

Das Tenant-Konto kann mithilfe eines Skript-Tokens des Hersteller-Kontos mit Berechtigungen für die Tenant-Verwaltung erstellt werden.

Beispielsweise könnte ein Tool wie Postman verwendet werden, um die WebAPI-Aufrufe auszugeben.

Schließlich wird ein Skript-Token vom Tenant-Konto benötigt, das die Berechtigungen hat, Geräteschlüssel zu erstellen, die Steuerung anzufordern und Geräteschlüssel zu löschen.

Anweisungen für die Erstellung eines Skript-Tokens finden Sie unter https://www.teamviewer.com/de/for-developers/teamviewer-api/#create-script-section.

Die für diese Beispielintegration bereitgestellten Code-Beispiele nutzen die folgenden Technologien und Bibliotheken:

  • C# und .NET Runtime
  • Bibliothek BouncyCastle mit kryptographischen Programmierschnittstellen

Für Android werden darüber hinaus folgende Informationen benötigt:

  • APK-Signaturwert für Ihren MSA
  • ID für APK-Signatur (durch WebAPI von TeamViewer ausgegeben)
  • Konto-ID des TeamViewer Kontos

Der AppKey ist die Signatur des MSA auf dem Android-Gerät, die AppKeyID wird zusammen mit der Konto-ID als Index verwendet. Beide Werte werden mit der Antwort des WebAPI-Aufrufs für die Registrierung des AppKey in der Webkonsole zurückgesendet.

Tipp: Bitte beachten Sie, dass alle in diesem Beispiel verwendeten Werte im konkreten Anwendungsfall durch Ihre eigenen Werte ersetzt werden müssen.

Übersicht über die Implementierung der herstellerseitigen Integration

Die folgende Grafik gibt eine kurze Übersicht über die Elemente auf Herstellerseite, bei denen die Integration erfolgen muss (auf Englisch):

REACH

Rollout eines Geräts für REACH API

Der API-Aufruf kann mit jeder beliebigen Klasse an HTTP-Clients erfolgen.

Die Voraussetzung für diesen WebAPI-Aufruf ist das Lesen der Rollout-Datei, die vom TeamViewer Client geschrieben wird.

Diese Datei ist auf den Betriebssystemen Windows und macOS mit Administratorrechten lesbar.

Auf Android-Geräten ist eine Registrierung der MSA App erforderlich, bevor der Zugriff auf die Rollout-Daten versucht wird. Dies wird im Kapitel Android-Integration weiter unten eigens beschrieben.

In unserem Beispiel beziehen wir uns auf den Code, da dieser auch in der VendorExampleApp bereitgestellt wird, die im Quellcode verfügbar ist. Zunächst müssen Sie einen JSON-Anforderungsbody erstellen. Dies kann zum Beispiel durch Verwendung einer Datenklasse erfolgen, wie die folgende beispielhafte Erstellung einer solchen Datenklasse.

Beachten Sie, dass die Informationen für RemotecontrolID und RequestID aus der Rollout-Datei stammen:

Erstellung eines Anforderungsbodys

var createDeviceKeyRequest = new CreateDeviceKeyRequest
{
    key_permissions = "unattended",
    remotecontrol_id = "r124124124",
    request_id = "{8c4fa1a7-9d1c-41e9-be17-70e95c289080}",
    tenant_id = "t0001"
};

Nach Erstellung dieser Datenklasse und gefüllt mit Informationen kann der WebAPI-Aufruf ausgegeben werden. Hierzu werden die URL und die Methode angegeben, der HTTP-Anforderungsheader mit den benötigten Authentifizierungsinformationen befüllt und anschließend der JSON-Anforderungsbody mit der serialisierten Datenklasse von oben angefügt.

Um eine Autorisierung zum HTTP-Header hinzuzufügen, muss in derTeamViewer Management Console ein Skript-Token der Anwendung erstellt werden.

Dieses Skript-Token muss die korrekten Berechtigungen haben, um die WebAPI-Aufrufe auszuführen.

Diese Berechtigungen können nur für das Skript-Token vergeben werden, wenn das zum Skript-Token zugehörige Konto ein Tenant ist.

Das folgende Feld zeigt einen Beispielcode, der einen Aufruf zur Antwortanalyse ausgibt und die deserialisierte Datenklasse mit den Antwortwerten zurücksendet. Dieser Beispielcode entstammt der Anbieter App.

Fordern Sie den DeviceSecretKey an

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices/createdevicekey");
 
webReq.Method = "POST";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer "+accessToken);
 
using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var createSecretKeyRequestJson = JsonConvert.SerializeObject(createDeivceKeyRequest);
 
    streamWriter.Write(createDeviceKeyRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}
 
var httpResponse = (HttpWebResponse) await webReq.GetResponseAsync();
if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}
 
var responseStream = httpResponse.GetResponseStream();
if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}
 
using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();
    return JsonConvert.DeserializeObject<CreateDeviceKeyResponse>(result);
}

Mit der API-Antwort sind Sie nun im Besitz des verschlüsselten DeviceKeys.

Zur Entschlüsselung des im PEM-Format verschlüsselten DeviceKeys wählen wir BouncyCastle als Bibliothek, da dadurch vieles einfacher wird.

BouncyCastle ist auch für Java verfügbar. Doch es gibt zahlreiche weitere Bibliotheken für jede Programmiersprache, die mit PEM-Dateien arbeiten können.

Der Verschlüsselungsalgorithmus wird direkt in der PEM-Datei angegeben, die Sie von der API-Anfrage erhalten.

Beispiel:

"-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\nDEK-Info: AES-256-CBC,309AA16\n-----END RSA PRIVATE KEY-----\n"


Aufgrund von Sicherheitsbedenken EMPFEHLEN WIR DRINGEND, dass Sie eine Bibliothek für diese Arbeit verwenden, da solche Bibliotheken den korrekten Algorithmus in der Regel automatisch erkennen.

Im Falle eines Sicherheitsproblems mit dem Algorithmus selbst, können und werden wir ihn ändern.

ISV-seitig sind keine Änderungen erforderlich, wenn eine geeignete Bibliothek verwendet wird. Eine manuelle Implementierung wäre niemals so flexibel.

Durch Verwendung von BouncyCastle besteht der PEM-Schlüssel nunmehr lediglich aus einem Code wie im folgenden Beispiel.

Zur Vereinfachung speichern wir den DeviceKey als entschlüsselten String im PEM-Format, da die Bibliothek BouncyCastle damit gut zurecht kommt und die Speicherung als String möglich ist.

Entschlüsseln Sie den PEM-Schlüssel

TextReader textReader = new StringReader(encryptedDeviceKey);
PemReader pemReader = new PemReader(textReader, new PasswordFinder(password));
object deviceKeyObject = pemReader.ReadObject();
 
AsymmetricCipherKeyPair rsaPrivatekey = (AsymmetricCipherKeyPair)deviceKeyObject;
 
TextWriter tw = new StringWriter();
var pemWriter = new PemWriter(tw);
pemWriter.WriteObject(rsaPrivatekey.Private);
pemWriter.Writer.Flush();
string deviceKey = tw.ToString();
return deviceKey;

Es ist wichtig, dass Sie nach diesem Schritt den DeviceKey zusammen mit der DeviceKeyID und der RemotecontrolID im Kontext Ihrer Verwaltungslösung speichern, die in der Antwort auf den WebAPI-Aufruf zurückgesendet wurden.

Darüber hinaus müssen Sie das Stilllegungstoken aufbewahren, das schließlich erforderlich ist, um die Registrierung des DeviceKeys wieder aufzuheben.

Aufbau einer Fernsteuerungssitzung

Mit den Daten aus der bisherigen Phase, dem DeviceKey und der DeviceKeyID kann eine Verbindung auf das registrierte Gerät aufgebaut werden.

Es ist wichtig, dass Sie bei der Anforderung der Fernsteuerung denselben Steuerungstyp verwenden, für den Sie beim Rollout Berechtigungen angefordert haben.

Auch hier wird zunächst eine Datenklasseninstanz mit den benötigten Informationen für den WebAPI-Aufruf befüllt.

Fordern Sie die Steuerungsdatenklasse an

var requestControlRequest = new RequestControlRequest()
{
    control_type = "attended",
    device_key_id = "{114fa1a7-abab-41e9-be17-70e95c289080}",
    remotecontrol_id = "r124124124",
    tenant_id = "t0001",
    tenant_nonce = "243dd78d07324ab7befa41390d08d35f"             
};

Mit dieser Dateninstanz kann der WebAPI-Aufruf wie im folgenden C#-Code ausgegeben werden.

Wieder wird zunächst die URL hinzugefügt, dann der HTTP-Autorisierungsheader mit dem Skript-Token und schließlich die serialisierte Datenklasseninstanz als JSON-Body.

Sobald die Anfrage mit einer Antwort zurückgegeben wurde, können die Daten in eine eigene Datenklasseninstanz deserialisiert werden, die die Vorlage für den TeamViewer Link bildet.

Dieser Link wird anschließend durch einen HMAC (Hashed Method Authentication Message) vervollständigt.

Fernsteuerungsaufruf

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices/requestcontrol");
 
webReq.Method = "POST";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer " + accessToken);
 
 
using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var requestControlRequestJson = JsonConvert.SerializeObject(requestControlRequest);
 
    streamWriter.Write(requestControlRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}
 
var httpResponse =  (HttpWebResponse)(await webReq.GetResponseAsync());
 
if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}
 
var responseStream = httpResponse.GetResponseStream();
 
if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}
 
using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();
 
    return JsonConvert.DeserializeObject<RequestControlResponse>(result);
                     
}

Nachdem die API-Antwort nur eine Linkvorlage zurückgibt, muss der Link mit dem HMAC vervollständigt werden.

Das Secret zur Erstellung des HMAC wird verschlüsselt in der API-Antwort zurückgegeben. Daher besteht der erste Schritt darin, das Secret zu entschlüsseln.

Zur Entschlüsselung wird der DeviceKey verwendet, der beim Rollout mit der API-Antwort empfangen wurde.

Da der DeviceKey als String im PEM-Format gespeichert wurde, verwandelt der erste Teil des Codes den String in eine Struktur, die für BouncyCastle geeignet ist (die Variable vom Typ „AsymmetricCipherKeyPair“).

Entschlüsseln Sie das PreMasterSecret

using (var reader = new StringReader(DeviceKey))
{
    //Convert to right format
    var bytesToDecrypt = encryptedDeviceSecret.FromBase64SafeUrl();
 
    //--------DECRYPT WITH PEM DEVICE KEY-------------//
    AsymmetricCipherKeyPair keyPair = (AsymmetricCipherKeyPair) new PemReader(reader).ReadObject();
    var decryptEngine = new OaepEncoding(new RsaEngine());
    decryptEngine.Init(false, keyPair.Private);
    var decryptedDeviceSecret = decryptEngine.ProcessBlock(bytesToDecrypt, 0, bytesToDecrypt.Length);
}

Mit dem entschlüsselten DeviceSecret, der TenantID, der RemotecontrolID auf den Ziel- und Tenant-Nonces kann der HMAC wie im folgenden Beispiel erstellt werden. Auch dieses wurde mithilfe der Sicherheitsbibliothek BouncyCastle implementiert.

Generieren Sie das Mastersecret

//---------HMAC Values to be hashed, recombined in a string ------------//
var hashVerifier = $"{tenantNonce}{targetNonce}{tenantId.Substring(1)}{remotecontrolId.Substring(1)}";
 
 
HMACSHA512 hmacsha512 = new HMACSHA512(decryptedDeviceSecret);
byte[] hashmessage = hmacsha512.ComputeHash(Encoding.UTF8.GetBytes(hashVerifier));
var masterSecret =  hashmessage.ToBase64SafeUrl();

Das Ergebnis wird anstelle des Strings YOURMASTERSECRET in die Vorlage des TeamViewer Links eingefügt.

Mit dem vollständigen String kann die Fernsteuerungssitzung nun aufgebaut werden, entweder durch Öffnen des Links im Webbrowser eines Systems, auf dem der TeamViewer Enterprise-Client installiert ist, oder durch Weitergabe dieses Links an die Befehlszeile eines Aufrufs an TeamViewer.exe

Registrierung des Geräts aufheben

Der Geräteaufruf zur Aufhebung der Registrierung benötigt folgende Parameter, um die Aufhebung der Registrierung erfolgreich durchzuführen:

  • Gültiges Skript-Token mit der korrekten Berechtigung (Geräteschlüssel löschen)
  • Stilllegungstoken
  • Device Key ID
  • Remote control ID
  • Tenant ID

Wie in den vorangegangenen Phasen muss eine Datenklasseninstanz für diesen konkreten Aufruf erstellt werden. Diese muss mit den konkreten Daten für den eingehenden Aufruf zur WebAPI befüllt werden:

Datenstruktur erstellen

var unregisterDeviceRequest = new UnregisterDeviceRequest
{
    tenant_id = "t0001",
    remotecontrol_id = "r124124124",
    device_key_id = "{114fa1a7-abab-41e9-be17-70e95c289080}",
    decommission_token = _mState.LastDecommissionToken
};

Auch hier wird das zuvor dargestellte Implementierungsmuster verwendet. Dabei werden die URL des WebAPI-Aufrufs, die Methode und das Skript-Token für die Anwendung zum HTTP-Autorisierungsheader hinzugefügt. Schließlich wird der serialisierte Inhalt der zuvor erstellten Datenklasse im JSON-Format angefügt.

Registrierung aufheben

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(apiUrl + "/api/v1/oem/devices");
 
webReq.Method = "DELETE";
webReq.ContentType = "application/json";
webReq.Headers.Add("Authorization", "Bearer " + accessToken);
 
using (var streamWriter = new StreamWriter(webReq.GetRequestStream()))
{
    var unregisterDeviceRequestJson = JsonConvert.SerializeObject(unregisterDeviceRequest);
 
    streamWriter.Write(unregisterDeviceRequestJson);
    streamWriter.Flush();
    streamWriter.Close();
}
 
var httpResponse = (HttpWebResponse)await webReq.GetResponseAsync();
if (httpResponse == null)
{
    throw new InvalidDataException("No response received");
}
 
var responseStream = httpResponse.GetResponseStream();
if (responseStream == null)
{
    throw new InvalidDataException("No response stream received.");
}
 
using (var streamReader = new StreamReader(responseStream))
{
    var result = streamReader.ReadToEnd();
    return;
}

In diesem Fall enthält das zurückgegebene Ergebnis keine Daten.

Der Erfolg dieses Vorgangs kann nur durch die Überprüfung des Rückgabewerts verifiziert werden, der 204 betragen sollte (siehe auch gebräuchliche HTTP-Rückgabewerte).

Spezielle Angaben für die Android-Integration

Aufgrund der Einschränkungen bei Android (keine richtige Trennung der Administratorrechte) unterscheidet sich der Rollout von anderen Plattformen. Es ist eine Verifizierung des MSA notwendig, bevor dieser mit der TeamViewer Android-App kommunizieren kann. Außerdem wird der RolloutKey auf andere Weise empfangen.

Der Hashwert SHA-256 des Signaturschlüssels des MSA (im Folgenden als AppKey bezeichnet) muss in TeamViewer mittels WebAPI-Aufruf POST /oem/appregistrations als hexadezimaler String registriert werden.

Dieser Registrierungsschritt ist pro AppKey nur einmal erforderlich und kann über einen REST-Client wie Postman erfolgen.

Die Kommunikation zwischen der TeamViewer App und dem MSA nutzt die native Schnittstelle Android Binder (https://developer.android.com/reference/android/os/Binder.html), wie in den AIDL-Dateien beschrieben, die Sie bei der Registrierung für die REACH-API erhalten.

Vor jedem anderen Aufruf muss die Verifizierungsmethode aufgerufen werden. Die Verifizierungsmethode benötigt die AccountID des Kontos, das für die Registrierung des MSA AppKey verwendet wurde, sowie die KeyID, die während der Registrierung zurückgegeben wurde. Wenn die Verifizierung erfolgreich ist, sollten Sie eine der Servicemethoden des Binder aufrufen. Andernfalls wird eine SecurityException ausgelöst.

Der wichtigste Unterschied auf Android, mit Ausnahme der App-Registrierung, ist die Art und Weise, wie der RolloutKey empfangen wird. Die Datei mit den Rollout-Daten wird in den privaten Anwendungsspeicher der TeamViewer App geschrieben. Diese Informationen können nur von der TeamViewer Anwendung gelesen werden. Deshalb muss die MSA-App die Rollout-Daten über Android Binder anfordern.Nachdem die Rollout-Daten erfolgreich mittels requestPreKeyData-Verfahren über Android Binder empfangen wurden, können Sie auf die gleiche Weise fortfahren, wie im Kapitel Rollout eines Geräts für REACH API

Versionsverlauf
Revision-Nr.
4 von 4
Letzte Aktualisierung:
‎24 Mai 2019, 1:18 PM
Aktualisiert von:
 
Beschriftungen (3)
Beitragleistende