Die advoware API nutzt eine Token-Authentifizierung.

Wir gehen hier auf die einzelnen Schritte ein, wie die Token-Authentifizierung zu nutzen ist.

Daten

Für die Nutzung der Token-Authentifizierung benötigt man folgende Daten:

App-ID
API-Key
Product = 64

Das Product ist für Drittanbieter immer die 64.

Schritt 1: URL-Abfrufen

Die URL zur Token-Authentifizierung wird über einen vorherigen GET-Aufruf abgefragt, dieser sieht wie folgt aus.

https://www2.advo-net.net/AdvonetConfigurator/api/Url?Kanzlei=KANZLEIKENNUNG-HIER-EINTRAGEN

Man erhält eine JSON-Struktur zurück die in etwa so aussieht:

{"relayUrl":"https://www2.advo-net.net:90/","connectorUrl":null,"securityGateway":"https://security.advo-net.net/"}

Der Wert “securityGateway” ist der entscheidende, da er die Basis-URL für die Anfrage zur Authentifizierung bereitstellt.

Schritt 2: URL zusammenbauen

Die Basis-URL aus Schritt 1 wird um folgenden Pfad ergänzt:

Basis-URL + /api/v1/Token

Am konkreten Beispiel sieht die endgültige URL wie folgt aus:

https://security.advo-net.net/api/v1/Token

Schritt 3: JSON-Struktur an das Security Gateway senden

Das Security Gateway nimmt die Anfragen entgegen und entscheidet ob Zugriff gewährt werden kann oder nicht. Dazu muss man eine JSON-Struktur via POST-Aufruf an die aus Schritt 2 zusammengesetzte URL schicken. Hierfür werden unter anderem die Daten wie App-ID, API-Key und Product benötigt. Zusätzlich werden weitere Werte benötigt, die nach dem Beispiel erläutert werden:

{
    "AppID": "APPID",
    "Kanzlei": "KANZLEIKENNUNG",
    "Database": "DATENBANK",
    "User": "MITARBEITERKUERZEL",
    "Role": 2,
    "Product": 64,
    "Password": "????????",
    "Nonce": "76f895f8-3d7b-447b-825b-7b1ff67dc637",
    "HMAC512Signature": "uzp2lp0K4AbiSQH5hTErvyF1yiGO20Y6reWjLgA10RK9ExNfrCZWMQxfK8x+c/Q+egF6ArTkt95zXgdSbl6Jvg==",
    "RequestTimeStamp": "2021-01-29T14:04:26.7955547Z"
}

Neben der bereits erwähnten App-ID muss man folgende Daten angeben:

Kanzlei	Die Kanzleikennung die bereits für die Einrichtung des advoware Manager benötigt wird oder auch zuvor schon vom Freigabedienst verwendet wurde. Wenn diese nicht vorhanden ist kann man sich registrieren, z.B. aus advoware heraus.
Database	Die Datenbank beim Kunden auf die man zugreifen möchte. Bei einer Standard-Installation wäre dies “ADVOWARE”.
User	Kürzel des Mitarbeiters oder des API-Nutzers.
Role	2
Product	64
Password	Das hier genutzte Password wird in der advoware Kanzleisoftware in den Einstellungen des Benutzers hinterlegt. Dabei handelt es sich um das “Passwort advoware online Dienste”, nicht zu verwechseln mit dem “Passwort”, welches rein für die Anmeldung in der advoware Kanzleisoftware vorgesehen ist.
Nonce	Zufällig generierter Wert, welcher sich aber für die HMAC-Signierung gemerkt werden muss. Wir nutzen z.B. die GUID.
HMAC512Signature	HMAC512-Signierung der Daten → wird weiter unten erläutert
RequestTimeStamp	Zeitstempel im ISO-8601 Format. Auch dieser Zeitstempel wird für die HMAC512-Signierung noch einmal benötigt und muss sich gemerkt werden.

Bei den Daten die man übertragen kann ist die Groß-/Kleinschreibung immer essenziell wichtig! Ebenso Leerzeichen!

Generierung der HMAC512-Signatur

Das hier aufgeführte Beispiel ist C#/.NET-Code und muss ggf. an die Programmiersprache angepasst bzw. übertragen werden.

public static string GenerateHMAC(int productId, string appId, string apiKey, string requestTimeStamp, string nonce = "") {
  if (String.IsNullOrEmpty(nonce))
    nonce = System.Guid.NewGuid().ToString();

  byte[] dataToSign = Encoding.UTF8.GetBytes($"{productId}:{appId}:{nonce}:{requestTimeStamp}");
  //string to encode e.g.: "64:APPID:76f895f8-3d7b-447b-825b-7b1ff67dc637:2021-01-29T14:04:26.7955547Z"
  byte[] apiKeyBytes = Convert.FromBase64String(apiKey);
  using (HMACSHA512 hmac = new HMACSHA512(apiKeyBytes)) {
    using (MemoryStream streamToSign = new MemoryStream(dataToSign)) {
      byte[] signatureBytes = hmac.ComputeHash(streamToSign);
      return Convert.ToBase64String(signatureBytes);
    }
  }
}

Man erhält folgende beispielhafte JSON-Struktur vom Security Gateway als Antwort, sofern die Authentifizierung geklappt hat:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration_utc": "2021-09-16T14:43:49.2078217Z",
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjAzOTAwRjIyMkI1NkNBMkIyQzJFMDI1MTQ0QkJCRkUxMTBGREZBQkMiLCJ4NXQiOiJBNUFQSWl0V3lpc3NMZ0pSUkx1XzRSRDktcnciLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJNUiIsImp0aSI6ImUyZjNlYjViLTVkMWEtNDNlNS1hNmVhLWJjYWJmNmQzNjBmNCIsIkthbnpsZWkiOiJtcnRlc3QiLCJEYXRhYmFzZSI6Ik1BVFQiLCJBcHBJRCI6IkFkdm93YXJlTW9iaWxlX1VXUF8xLjY0IiwiUHJvZHVjdCI6IkFXTW9iaWxlIiwibmJmIjoxNjMxNzk5ODI5LCJleHAiOjE2MzE4MDM0MjksImlhdCI6MTYzMTc5OTgyOSwiaXNzIjoiYWR2b25ldFNlY3VyaXR5R2F0ZXdheSIsImF1ZCI6ImFkdm9uZXRVc2VyIn0.D68f6yBqEQeMRhAJ1-w_4YnAu512SK-c2FIt-pUFBGEi8nCK_nf2dO0sk81F5TOR0y62Hd9ffu5O0V7v3MSK0zPjRp05v6wyrtgyiffcu9Kz3-3Vuu8lVzzA4ojT90D60neFMtwGpFcgC4SJl6c6SljiTmmOe1HadI1xlHFm_O4iWCUDMyb-Hz3XxcP8vs-jrh7DUzVsGLYkQn0pMThZSkqwtI-sbgR5ZT2beNWVeYI0Fmj76XXm5cPJe77VxZ81L7mADm8V3_KsTc5Jox_qZewQd3NLyFo5waLwvQFC0tqN63ZCjNQpQfqC-79O2TggDVg1vuefcLcD2_wBrlwgtcDKDAaA83zZBDZYEKXrKcBpJL825ZjKEyW50O8b5dP0CwTdKegv_FQcYrO06lHsTDpYwxfQNITu_Hy3RoZOmljvFKkXT-8F59FEJ-xp1R1sbYOswcEhPGKknpFpZoW4Vy9tPXULmeLMEyHKQ4GGlmvWkXrtBAcmYZn_EeLhdhRlP-yZPfP5oaxdJrQ9qrhBcfgEmOjX0Nz-YzFvR3Qthlu9yrCdnpMbSeTaEqVUJXLVIHQ3sLgCRAPYrDaLuPUXMWLSv_UnukRUv0x9IWophvbyiGSU1t_lo9KYhvTqCiZB8n8e-DQjlT8fQye46OaSrueVfPJ7op5nZkuVAZB8d38",
    "refresh_token": null
}

Hier noch ein Beispiel für die Generierung der HMAC512-Signatur in PHP:

<?php
 
class IdentityHMAC
{
    public $AppID;
    public $Kanzlei;
    public $Database;
    public $User;
    public $Role;
    public $Product;
    public $Password;
    public $Nonce;
    public $HMAC512Signature;
    public $RequestTimeStamp;
 
    public function Sign(string $apiKey) : string {
        // Fills $RequestTimeStamp and then HMAC512Signature with the signature and returns a json serialized string of the whole object
        $objDateTime = new DateTime('NOW');
        $objDateTime = $objDateTime->setTimezone(new DateTimeZone("UTC"));
        $this->RequestTimeStamp = $objDateTime->format(DateTime::ISO8601);
        $this->Nonce = uniqid();
        $dataToSign = sprintf("%s:%s:%s:%s", $this->Product, $this->AppID, $this->Nonce, $this->RequestTimeStamp);
        $this->HMAC512Signature = base64_encode(hash_hmac('sha512', utf8_encode($dataToSign), base64_decode($apiKey), true));
        return json_encode($this);
    }
}
 
$i = new IdentityHMAC();
$i->AppID = "Your AppID";
$i->Kanzlei = "test";
$i->Database = "DATABASE";
$i->User = "TEST";
$i->Password = "!!Secret!!";
$i->Role = 2;
$i->Product = 64;
 
echo $i->Sign('Your secret API Key');

Schritt 4: Statt Basic Authentication Header nun „Bearer“ Header setzen

Jede Anfrage, die bisher an den Connector ging (über das Relay) hatte den Basic Authentication Header gesetzt. Zukünftig muss hier der „Bearer“-Header gesetzt werden, dieser muss dann das Token, aus dem aus Schritt 3 zurückbekommenen JSON enthalten („access_token“).

Schritt 5: API-Endpunkte aufrufen

GET https://www2.advo-net.net:90/api/v1/Akten