API Keys

Mit dem Modul "API Keys" verwalten Sie die API Keys des BPC. Ein API Key ermöglicht Systemen und Skripten den Zugriff auf die BPC REST-API, ohne dass sich ein Benutzer anmelden muss. Jeder API Key ist eine eigene Komponente des Moduls und enthält Zuordnungen zu Organisationen, Rollen und Rechten sowie einen Gültigkeitszeitraum.

Wie ein API Key beim Aufruf der API verwendet wird, ist unter API Keys verwenden beschrieben.

Oberfläche

Die API Keys werden im Administrationsbereich im Reiter API Keys verwaltet. Die Komponenten-Übersicht links listet alle angelegten API Keys, rechts werden die Einstellungen des ausgewählten API Keys angezeigt.

Komponenten-Übersicht des Moduls API Keys mit einem gespeicherten API Key

Über das Plus-Icon (rot markiert, unten links) legen Sie einen neuen API Key an. Der Schlüssel eines gespeicherten API Keys wird nur noch maskiert () angezeigt.

Voraussetzungen

Um API Keys verwalten zu können, müssen folgende Voraussetzungen erfüllt sein:

Sie verfügen über die Rolle bpcadmin.
Sie haben Zugriff auf den Administrationsbereich.

API Key anlegen

In diesem Abschnitt wird beschrieben, wie Sie einen neuen API Key erstellen. Der Schlüssel und die ID werden dabei automatisch vom BPC erzeugt.

Navigieren Sie im Administrationsbereich zum Reiter API Keys.
Klicken Sie auf das Plus-Icon, um eine neue Komponente hinzuzufügen.

Das Fenster "Editor" öffnet sich mit einem neu erzeugten API Key.
Geben Sie unter Name einen Namen ein, der den Verwendungszweck beschreibt.
Kopieren Sie den API Key über das Kopieren-Icon rechts im Feld API-Key.
Hinterlegen Sie den API Key an einem sicheren Ort, z. B. in einem Passwort-Manager.
Prüfen Sie unter Ausstellungsdetails die Felder Ausgestellt am und Gültig bis.

Beide Felder sind vorbelegt: Der API Key ist ab sofort und für ein Jahr gültig.
Legen Sie unter Zuordnungen die Organisationen, Rollen und Rechte des API Keys fest.
Klicken Sie auf Speichern.

Der API Key wurde angelegt und erscheint in der Komponenten-Übersicht.

Der API Key kann nach dem Speichern nicht mehr eingesehen oder kopiert werden. Wenn Sie den Schlüssel nicht gesichert haben, legen Sie einen neuen API Key an und löschen Sie den alten.

API Key kopieren

Um einen API Key mit denselben Zuordnungen für ein weiteres System anzulegen, können Sie einen vorhandenen API Key kopieren. Die Kopie erhält einen neuen Schlüssel, eine neue ID und einen neuen Gültigkeitszeitraum.

Klicken Sie in der Komponenten-Übersicht beim gewünschten API Key auf das Kopieren-Icon.

Das Fenster "Editor" öffnet sich mit den Einstellungen des kopierten API Keys und einem neu erzeugten Schlüssel.
Kopieren Sie den neuen API Key und hinterlegen Sie ihn an einem sicheren Ort.
Klicken Sie auf Speichern.

Der neue API Key wurde angelegt und erscheint in der Komponenten-Übersicht.

API Key löschen

Ein gelöschter API Key ist sofort ungültig. Alle Systeme, die diesen API Key verwenden, können danach nicht mehr auf die BPC REST-API zugreifen.

Klicken Sie in der Komponenten-Übersicht beim gewünschten API Key auf das Löschen-Icon ().
Bestätigen Sie das Löschen.

Der API Key wurde gelöscht.

Konfigurationsparameter

Die folgenden Konfigurationsparameter gelten für das gesamte Modul.

Modul

Allgemeine Moduleinstellungen

Name (ID) Beschreibung

Name (`ID`)	Beschreibung
Modul ohne Benutzeroberfläche (`noGui`)	Indikator für das Frontend, dass es für dieses Modul keine Benutzeroberfläche zum Laden gibt. Sollte nicht verändert werden.
Icon (`module_iconCls`)	Individuell auswählbares Icon, das vor dem Titel angezeigt wird. Falls kein Symbol angezeigt werden soll, kann z.B. "none" eingetragen werden. Bei leerem Feld wird ein Standard-Icon gewählt.

Modul ohne Benutzeroberfläche
(noGui)

Indikator für das Frontend, dass es für dieses Modul keine Benutzeroberfläche zum Laden gibt. Sollte nicht verändert werden.

Icon
(module_iconCls)

Individuell auswählbares Icon, das vor dem Titel angezeigt wird.
Falls kein Symbol angezeigt werden soll, kann z.B. "none" eingetragen werden. Bei leerem Feld wird ein Standard-Icon gewählt.

Konfiguration

Name (ID) Beschreibung

Name (`ID`)	Beschreibung
Benachrichtigungen zu API-Keys (`apiKeysNotifications`)	Benachrichtigungen zu ablaufenden API-Keys. Durch diese Konfiguration kann gesteuert werden, wann durch Benachrichtigungen auf ablaufende API-Schlüssel hingewiesen wird.

Benachrichtigungen zu API-Keys
(apiKeysNotifications)

Benachrichtigungen zu ablaufenden API-Keys. Durch diese Konfiguration kann gesteuert werden, wann durch Benachrichtigungen auf ablaufende API-Schlüssel hingewiesen wird.

Zusätzlich werden je API Key folgende Einstellungen vorgenommen:

Modul

Allgemeine Moduleinstellungen

Name (ID) Beschreibung

Name (`ID`)	Beschreibung
Icon (`module_iconCls`)	Individuell auswählbares Icon, das vor dem Titel angezeigt wird. Falls kein Symbol angezeigt werden soll, kann z.B. "none" eingetragen werden. Bei leerem Feld wird ein Standard-Icon gewählt.
API-Key (`apiKey`)	Ein API-Key wird für die Authentifizierung und Autorisierung gegenüber der BPC REST-API verwendet. Dieser kann nach dem Speichern nicht mehr eingesehen werden.

Icon
(module_iconCls)

Individuell auswählbares Icon, das vor dem Titel angezeigt wird.
Falls kein Symbol angezeigt werden soll, kann z.B. "none" eingetragen werden. Bei leerem Feld wird ein Standard-Icon gewählt.

API-Key
(apiKey)

Ein API-Key wird für die Authentifizierung und Autorisierung gegenüber der BPC REST-API verwendet. Dieser kann nach dem Speichern nicht mehr eingesehen werden.

Ausstellungsdetails

Die Ausstellungsdetails des API-Keys.

Name (ID) Beschreibung

Name (`ID`)	Beschreibung
Ausgestellt von (`issuedBy`)	Der Benutzer, der den API-Key ausgestellt hat.
Ausgestellt für (`issuedFor`)	Der Benutzer, für den der API-Key ausgestellt wurde.
Ausgestellt am (`issuedOn`)	Das Datum, an dem der API-Key ausgestellt wurde.
Gültig bis (`expiresOn`)	Das Datum, bis zu dem der API-Key gültig ist.

Ausgestellt von
(issuedBy)

Der Benutzer, der den API-Key ausgestellt hat.

Ausgestellt für
(issuedFor)

Der Benutzer, für den der API-Key ausgestellt wurde.

Ausgestellt am
(issuedOn)

Das Datum, an dem der API-Key ausgestellt wurde.

Gültig bis
(expiresOn)

Das Datum, bis zu dem der API-Key gültig ist.

Zuordnungen

Dem API-Key zugeordnete Organisationen, Rollen und Rechte.

Name (ID) Beschreibung

Name (`ID`)	Beschreibung
Organisationen (`assignedOrganisations`)	Organisationen, die diesem API-Key zugewiesen sind.
Rollen (`assignedRoles`)	Rollen, die diesem API-Key zugewiesen sind.
Rechte (`assignedRights`)	Rechte, die diesem API-Key zugewiesen sind.

Organisationen
(assignedOrganisations)

Organisationen, die diesem API-Key zugewiesen sind.

Rollen
(assignedRoles)

Rollen, die diesem API-Key zugewiesen sind.

Rechte
(assignedRights)

Rechte, die diesem API-Key zugewiesen sind.

Nach Ablauf des unter Gültig bis angegebenen Datums verliert der API Key sofort seine Gültigkeit. Dies führt dazu, dass Aufrufe von API-Endpunkten und Deployment-Prozesse fehlschlagen, bis ein neuer Key hinterlegt bzw. das Gültigkeitsdatum angepasst wird.

Zuordnungen

Über die Zuordnungen assignedOrganisations, assignedRoles und assignedRights können für die API Keys feingranulare Aufrufsrechte vergeben werden.

Zum Beispiel sind für den Aufruf dieses Backup API-Endpunktes laut API-Dokumentation entweder die Rolle BACKUPS_ADMIN oder das Recht BACKUPS_CREATE notwendig. Soll der Verwender des API Keys nun nur diesen einzelnen API-Endpunkt aufrufen können, setzen Sie unter assignedRights nur das Recht BACKUPS_CREATE. Sollen stattdessen alle Backup-Endpunkte aufrufbar sein, dann setzen Sie bei assignedRoles die Rolle BACKUPS_ADMIN.

Migration aus der Core-Einstellung API_Keys

Bis zur Konfigurationsmodell-Version 36 wurden alle API Keys gemeinsam in der Core-Einstellung API_Keys gespeichert. Beim Update auf Version 37 wird jeder Eintrag dieser Einstellung automatisch in eine eigene Komponente des Moduls "API Keys" übernommen. Aus name wird dabei der Name und aus description die Beschreibung der Komponente. Die Einstellung apiKeysNotifications wird unverändert in das Modul "API Keys" verschoben.

Keywords: