Support vertec.com

API Token

Die API Tokens erhöhen die Anmeldesicherheit der Vertec XML Schnittstelle und der BI API Schnittstelle.

Standard

|

Expert

CLOUD ABO

|

ON-PREMISES

Leistung & CRM

Budget & Teilprojekt

Fremdkosten

Ressourcen & Projektplanung

Business Intelligence

Erstellt: 13.10.2022
Aktualisiert: 23.11.2022 | Erstpublikation

Mit Vertec Version 6.6 wurden API Tokens für die Erhöhung der Anmeldesicherheit von Web API Zugriffen eingeführt. Die API Tokens erhöhen die Anmeldesicherheit der Vertec XML Schnittstelle und der BI API Schnittstelle.

Hinweis:
Aus Gründen der Rückwärtskompatibilität wird das alte System (die Authentisierung via Username und Passwort) weiterhin unterstützt. Ab Vertec Version 6.7 jedoch nicht mehr. Die Umstellung sollte also dennoch bald erfolgen.

API Token generieren

API Tokens können auf der Seite Weitere Info eines Bearbeiters generiert werden:

Mit einem Klick auf den Button Generieren… wird das API Token generiert und im entsprechenden Feld angezeigt:

Dieses muss sogleich kopiert werden, da es beim nächsten Aufruf der Seite nicht mehr angezeigt wird. Anstelle des Tokens wird folgender Text angezeigt und das Token kann nur noch gelöscht werden:

Wird das Token gelöscht, kann es danach nicht mehr verwendet werden, und anstelle des Löschen… Buttons steht wieder der Button Generieren… zur Verfügung.

Authentisierung per API Token beim XML Server

Die Authentisierung per API Token geschieht beim XML Server, indem anstelle von vertec_username und password der Parameter api_token übergeben wird. Beispiel:

import requests
url = 'http://localhost:8081/xml'
api_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.MGVhZmUzMzYtNmVhMi00MDdhLTgxNjQtZDYxZmI0NzU2MWZi._r16YlvWmZCMJ3qdDX3bK5_DJHwcczTYaWoKUYUNZuk'
headers = {'Authorization': 'Bearer %s' % api_token}
xmlquery = """
<Envelope>
  <Body>
    <Query>
      <Selection>
        <ocl>projektbearbeiter</ocl>
      </Selection>
    </Query>
  </Body>
</Envelope>
"""
response = requests.post(url, headers=headers, data=xmlquery)
print(response.text)

Es braucht keinen /xml/auth Aufruf mehr, der Zugriff erfolgt direkt auf /xml.

Auch werden nicht mehr laufend neue Sessions erzeugt. Innerhalb des Timeout-Intervalls wird immer die gleiche Session verwendet.

Mehrere Sessions starten

Falls explizit eine neue (parallele) Session verwendet werden möchte, kann optional ein HTTP Header VertecSessionTag mit einem beliebigen Wert (z.B. 1) mitgegeben werden. Es sind maximal 36 Zeichen erlaubt. Pro VertecSessionTag wird eine neue Session gestartet. Somit basiert die Session Affinität auf der Kombination von API Token und Session-Id.

Beispiel:

headers = {'Authorization': 'Bearer %s' % api_token, 'VertecSessionTag': '1'}

Authentisierung per API Token beim BI API

Beim BI API muss das API Token als Bearer Token in einem Authorization Header mitgegeben werden:

impport requests
url = 'http://localhost:8081/api/bi/measures'
api_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.MGVhZmUzMzYtNmVhMi00MDdhLTgxNjQtZDYxZmI0NzU2MWZi._r16YlvWmZCMJ3qdDX3bK5_DJHwcczTYaWoKUYUNZuk'
headers = {'Authorization': 'Bearer %s' % api_token}
r = requests.get(url, headers=headers)
measures = r.text

Wenn sowohl API Token als auch Username/Password in einem Request angegeben sind, wird nur das API Token berücksichtigt. Ist es ungültig, wird nicht automatisch ein Login-Versuch mit Username/Password vorgenommen.

Alle API Tokens löschen

Benutzer mit Administratorrecht können die generierten API Tokens aller Bearbeiter im Menü Einstellungen mithilfe der Option Alle API Tokens löschen... auf einmal löschen:

Es erscheint zunächst eine Warnabfrage, die nochmals nachfragt, ob wirklich alle API Tokens gelöscht werden sollen.

Berechtigungen

Der Abschnitt API Token auf der Seite Weitere Info des Bearbeiters wird nur angezeigt, wenn der eingeloggte Benutzer das Administratorrecht hat oder ihm das Schreibrecht auf Projektbarbeiter.ApiToken gewährt wird.

Authorization-Header in Excel

Werden die Daten wie in der Beispielanwendung in Excel geladen, dann werden die Anmeldedaten wie folgt gesetzt:

  1. Datenquelleneinstellungen öffnen:
  2. Datenquelle auswählen > Berechtigungen bearbeiten > Anmeldeinformationen bearbeiten > Anonym:
  3. Daten aus dem Web > Weitere > Parameter des HTTM Anforderungsheaders setzen:
Bitte wählen Sie Ihren Standort