Die Vault wird verwendet um wiederverwertbare Daten, häufig sensible Daten wie Zertifikate, Public Keys und Benutzername-Password-Kombinationen, zu speichern Alle in der Vault gespeicherten Elemente werden Vault Item genannt. Vault Items sind in Vault Bereiche organisiert. Die Organisation von Elementen bzw. Items in unterschiedliche Bereiche ist auch hilfreich bei der Zugriffsbeschränkung für bestimmte Operator und Gruppen. Hier beschreiben wir die verfügbaren API-Methoden für die Verwaltung von Vault Items, Vault Bereichen und Autorisierungen für Vault Bereiche.

Für eine Beschreibung der Nutzungsszenarien der Vault lies bitte die Vault-Einführung. Bitte lies die Einführung in API v4, um zu erfahren, wie Du Zugriff auf die API erhältst.

Vault Items

Dieses Endpunkteset lässt Dich einzelne Vault Items abrufen, erstellen, aktualisieren und löschen. Aufgrund der Sensibilität einiger Vault-Item-Typen werden die sensiblen Daten selbst nie zurückgegeben.

Beschreibung des Vault Item-Objekts

Die folgenden VaultItem-Objekte werden in den nachfolgend beschriebenen API-Methoden verwendet:

Name Beschreibung
VaultItemGuid Die einzigartige Kennung des Vault Items.
Name Der angezeigte Name des Vault Items.
VaultSectionGuid Die einzigartige Kennung des Vault Bereichs, in dem das Vault Item gespeichert ist.
VaultItemType

Definiert den Typ des Vault Items.
Die derzeit unterstützten Typen sind:

  • CertificateArchive: Für Zertifikats-Archive (d. h. .pfx-Dateien), für Client-Zertifikate bei Multi-step API-Prüfobjekten verwendet.
  • Certificate: Für öffentliche Schlüssel (Public Keys), für Single-Sign-On-Konfigurationen genutzt.
  • CredentialSet:  Benutzername-Password-Kombinationen, für Authentifizierungseinstellungen bei Prüfobjekten genutzt.
Value

Der Wert, der im Vault Item gespeichert wird. Der Inhalt dieses Felds hängt vom Typ des Vault Items ab.

  • Für den Typ CertificateArchive: Spezifiziere eine Base-64-Verschlüsselung für Deine binäre .pfx-Datei, wenn Du ein Vault Item dieses Typs erstellst oder aktualisierst. Wenn Du das Element wieder abrufst, ist das Wert-Feld immer leer (da es sensible Informationen sind).
  • Für Typ Certificate: Spezifiziere den Textinhalt Deines Public Keys, wenn Du ein Vault Item dieses Typs erstellst oder aktualisierst. Wenn Du das Element wieder abrufst, enthält das Wert-Feld die Originaldaten des Public Keys.
  • Für Typ CredentialSet: Dieses Feld ist unbenutzt. Verwende stattdessen die Benutzername- und Passwort-Felder.
IsSensitive Gibt an, ob der Wert, der im Vault Item gespeichert wird, verschlüsselt ist. Wenn dies bei einem Vault Item auf wahr eingestellt ist, werden die gespeicherten Werte nicht in der Webanwendung oder in der API angezeigt. Dieser Wert sollte nicht angegeben werden, wenn Du ein neues Element erstellst: Die Elemente CertificateArchive und CredentialSet sind immer verschlüsselt (da sie per Definition sensible Daten enthalten), während ein Certificate Public Key von seinem Wesen eine öffentliche Information ist und als reiner Text gespeichert werden kann.
Notes Anmerkungen oder Beschreibungen für das Vault Item.
UserName Der Benutzername des CredentialSet.
Password Das Passwort des CredentialSet.

Vault-Item-Endpunkte

Es gibt die folgenden API-Methoden:

Anfragetyp Endpunkt Einsatz
GET VaultItem/GetAll Gibt alle in Bereichen gespeicherten Vault Items aus, auf die der Nutzer Zugriff hat.
GET VaultItem/{VaultItemGuid} Gibt das angegebene Vault Item aus.
POST VaultItem Erstellt ein neues Vault Item mit den angegebenen Werten.
PUT VaultItem/{VaultItemGuid} Aktualisiert das angegebene Vault Item.
DELETE VaultItem/{VaultItemGuid} Löscht das angegebene Vault Item.

GET VaultItem/GetAll

Die GET-Anfrage VaultItem/GetAll hat keine Parameter. Es gibt eine Liste der Vault Items aus, die in Bereichen gespeichert sind, auf die der Nutzer Anzeigezugriff hat.

Beispiel:

[
  {
    "VaultItemGuid": " FE1656C1-A606-43BB-BD61-1EEE9715EE9E ", 
    "Name": "Web shop test login",
    "Value": "",
    "VaultSectionGuid": "8D4BAED2-56C2-4220-B36D-00013511D234",
    "VaultItemType": "CredentialSet",
    "IsSensitive": true,
    "Notes": "This is not a real account",
    "UserName": "test@acme.com",
    "Password": "",
    "CertificateArchive":
    {
      "Issuer": "",
      "NotBefore": "",
      "NotAfter": "",
      "Password": "",
      "ArchiveData": ""
    }
  },
  {
    "VaultItemGuid": "A9CB1BE3-1715-4C31-9040-51CBBFAE23CB",
    "Name": "Marketing web site login",
    "Value": "",
    "VaultSectionGuid": "3A3C0CE8-9931-4312-8A15-00017CBB615F ",
    "VaultItemType": "CredentialSet",
    "IsSensitive": true,
    "Notes": "This is not a real account",
    "UserName": "testmarketing@acme.com",
    "Password": "",
    "CertificateArchive":
    {
      "Issuer": "",
      "NotBefore": "",
      "NotAfter": "",
      "Password": "",
      "ArchiveData": ""
    }
  }
]

GET VaultItem/{VaultItemGuid}

Die GET-Anfrage VaultItem/{VaultItemGuid} wird das Vault Item ausgeben, das durch die Vault-Item-Guid identifiziert wird.

Beispiel eines Vault Items, das im Inhalt einer 200-Antwort zurückgegeben wird:

{
  "VaultItemGuid": "FE1656C1-A606-43BB-BD61-1EEE9715EE9E",
  "Name": "Test certificate archive",
  "Value": "",
  "VaultSectionGuid": "141D9649-0CE7-4748-AA0D-D3021D0D5A47",
  "VaultItemType": "CertificateArchive",
  "IsSensitive": true,
  "Notes": "Certificate archive test",
  "UserName": "",
  "Password": "",
  "CertificateArchive": {
    "Issuer": "Acme Corp, Inc.",
    "NotBefore": "2018-06-12T14:10:50.489Z",
    "NotAfter": "2020-06-12T14:10:50.489Z",
    "Password": "",
    "ArchiveData": ""
  }
}

Bitte beachte, dass Werte, die sensible Informationen enthalten, als leerer String ausgegeben werden.

PUT VaultItem/{VaultItemGuid}

Die PUT-Anfrage an Endpunkt VaultItem/{VaultItemGuid} wird das Vault Item, das durch die Vault-Item-Guid identifiziert wird, aktualisieren. Sobald Du ein Vault Item aktualisierst, wird jedes Prüfobjekt, das eine Referenz zu diesem Vault Item enthält, auch aktualisiert, sodass Deine Änderungen sofort in Kraft treten.

Diese Anfrage erfordert eine ChangeVaultSection-Autorisierung.

Eine PUT-Anfrage erwartet die folgende Objektstruktur:

{
  "VaultItemGuid": "FE1656C1-A606-43BB-BD61-1EEE9715EE9E",
  "Name": "Test certificate archive",
  "VaultSectionGuid": "141D9649-0CE7-4748-AA0D-D3021D0D5A47",
  "VaultItemType": "CredentialSet",
  "IsSensitive": true,
  "UserName": "",
  "Password": "",
  "CertificateArchive": {
    "Password": "TheOtherPassword",
    "ArchiveData": "[your base64-encoded private certificate]"
  }
}

Bei dem obigen Beispiel würde das Anmerkungsfeld geleert, wenn im Original-Anmerkungsfeld des Vault Items ein Wert vorhanden gewesen wäre. Wenn Du einen Parameter auslässt, bleibt er nicht unverändert, sondern wird als leer betrachtet. Die einzigen Werte, die nicht angegeben werden müssen, sind die sensiblen Werte. Wenn Du zum Beispiel den Wert im Password-Feld oder das gesamte CertificateArchive-Objekt auslässt, bleiben diese unverändert. Darüber hinaus können die Attribute IsSensitive und VaultSectionGuid nicht geändert werden.

DELETE VaultItem/{VaultItemGuid}

Die DELETE-Anfrage an den Endpunkt VaultItem/{VaultItemGuid} löscht das angefragte Vault Item.

Wenn das angegebene Vault Item noch genutzt wird (zum Beispiel, wenn ein Prüfobjekt sich auf dieses spezielle Vault Item bezieht), gibt der Service den Statuscode 400 aus, einschließlich entsprechender Nachricht. Diese Anfrage erfordert eine ChangeVaultSection-Autorisierung.

POST VaultItem

Die POST-Anfrage an den Endpunkt VaultItem erzeugt ein neues VaultItem-Objekt. Lasse bei der Angabe der VaultItem-Daten die VaultItemGuid aus: Die neue GUID für dieses Element wird als Teil der Antwort zurückgegeben. Diese Anfrage erfordert eine ChangeVaultSection-Autorisierung. 

Beispiel:

{
 "Name": "Test certificate archive",
 "Value": "",
 "VaultSectionGuid": "141D9649-0CE7-4748-AA0D-D3021D0D5A47",
 "VaultItemType": "CertificateArchive",
 "Notes": "Certificate archive test",
 "CertificateArchive": {
  "Password": "TheOtherPassword",
  "ArchiveData": "[your base64-encoded private certificate]"
 }
}

Vault Bereiche

Es gibt bei dieser API mehrere Endpunkte, anhand derer Du die Vault Bereiche verwalten kannst. Jedes Vault Item gehört exakt zu einem Bereich. Werden nur wenige Vault Items für deinen gesamten Account benötigt, kannst Du sie einfach in einem einzigen Vault Bereich speichern. Steigt jedoch die Anzahl der Vault Item in deinem Account, kann es gut sein, sie in getrennte Bereiche zu organisieren.

Bei jedem Uptrends Account gibt es zu Beginn standardmäßig einen Vault Bereich. Die Gruppe der Administratoren hat auf diesen Bereich Vollzugriff, das heißt, sie können den Bereich und alle in ihm enthaltenen Vault Items bearbeiten. 

Wenn ein neuer Vault Bereich erstellt wird, erhält der Nutzer (Operator), der mit dem API-Account verknüpft ist, von dem der Vault Bereich erstellt wird, automatisch die ChangeVaultSection-Autorisierung für den neuen Bereich. Es werden keine weiteren Autorisierungen erstellt.

Beschreibung des Vault Bereich-Objekts

Das folgende VaultSection-Objekt wird in den nachfolgend beschriebenen API-Methoden verwendet:


Name Beschreibung
VaultSectionGuid Die einzigartige Kennung des Vault Bereichs.
Name Der einzigartige Name des Vault Bereichs.

Vault section endpoints

Anfragetyp Endpunkt Einsatz
GET VaultSection/GetAll Gibt alle Bereiche aus, auf die der Nutzerkontext Zugriff hat.
GET VaultSection/{VaultSectionGuid} Gibt den angegebenen Vault Bereich aus.
POST VaultSection Erstellt einen neuen Vault Bereich mit dem angegebenen Namen.
PUT VaultSection/{VaultSectionGuid} Aktualisiert den angegebenen Vault Bereich.
DELETE VaultSection/{VaultSectionGuid} Löscht den angegebenen Vault Bereich.

GET VaultSection/GetAll

The GET request VaultSection/GetAll has no parameters. It will return a list containing all vault sections you have view access to.

Example content:

[
  {
    "VaultSectionGuid": "8D4BAED2-56C2-4220-B36D-00013511D234",
    "Name": "Vault items"
  }, 
  {
    "VaultSectionGuid": "3A3C0CE8-9931-4312-8A15-00017CBB615F",
    "Name": "Marketing web site vault items"
  }
]

GET VaultSection/{VaultSectionGuid}

Die GET-Anfrage VaultSection/{VaultSectionGuid} wird den Vault Bereich ausgeben, der durch die Vault-Bereich-GUID identifiziert wird.

Beispiel:

{
  "VaultSectionGuid": "8D4BAED2-56C2-4220-B36D-00013511D234",
  "Name": "Vault items"
}

POST VaultSection

Die POST-Anfrage an den Endpunkt VaultSection erzeugt ein neues VaultSection-Objekt. Der Operator, mit dessen Nutzerkontext die Anfrage gestellt wird, erhält ViewVaultSection- und ChangeVaultSection-Autorisierungen für den neuen Bereich. Es werden keine weiteren Autorisierungen erstellt. Lasse bei der Angabe der VaultSection-Daten die VaultSectionGuid aus. Die neue GUID für dieses Element wird als Teil der Antwort zurückgegeben.

{
  "Name": "Development vault items"
}

PUT VaultSection/{VaultSectionGuid}

Die PUT -Anfrage an Endpunkt VaultSection/{VaultSectionGuid} wird den Vault Bereich, der durch die Vault-Bereich-Guid identifiziert wird, aktualisieren. In der Regel ist der einzige Zweck die Änderung des Vault-Bereich-Namens. Diese Anfrage erfordert die ChangeVaultSection-Autorisierung.

{
  "VaultSectionGuid": "8D4BAED2-56C2-4220-B36D-00013511D234",
  "Name": "Web shop vault items"
}

DELETE VaultSection/{VaultSectionGuid}

Die DELETE-Anfrage an den Endpunkt VaultSection/{VaultSectionGuid} löscht den angefragten Vault Bereich.

Wenn der angegebene Vault Bereich noch genutzt wird (zum Beispiel, wenn in dem Vault Bereich noch Vault Items gespeichert sind), gibt der Service den Statuscode 400 aus, einschließlich entsprechender Nachricht. Wenn das der Fall ist, musst Du die Vault Items erst löschen, bevor Du den Vault Bereich löschen kannst. Beachte, dass Du keine Vault Items löschen kannst, die noch in Verwendung sind (z. B. wenn das Vault Item noch von einem Prüfobjekt genutzt wird). Dazu ist eine ChangeVaultSection-Autorisierung erforderlich.

Autorisierungen für Vault Bereiche

Neben der Trennung von Vault Items erlauben Vault Bereiche auch, dass sich steuern lässt, wer Zugriff auf welche Elemente hat. Wenn eine spezielle Operator-Gruppe exklusiven Zugriff auf bestimmte Vault Items haben soll, verschiebe diese Vault Items in einen separaten Bereich. Nur Personen, die Zugriff zu dem Vault Bereich haben, können die Vault Items sehen, die darin enthalten sind.

Sobald Du den neuen Vault Bereich erstellt hast (entweder anhand der API oder der Online-App), ist der Bereich zunächst nur für Dich sichtbar. Wenn Du Vault Items hinzufügst, können andere Operator diese Vault Items nicht bearbeiten oder nutzen.

Damit andere diesen neuen Vault Bereich nutzen, Elemente hinzufügen und/oder diese Vault Items in Prüfobjekteinstellungen auswählen können, musst Du ihnen Zugriff gewähren. Dies erreichst Du anhand der folgenden API-Methoden.

Es gibt zwei Typen der Autorisierung: ViewVaultSection und ChangeVaultSection. Diese Autorisierungstypen können Operator und Operator-Gruppen gewährt werden.

Beschreibung des Autorisierungsobjekts

Die folgenden Autorisierungsobjekte werden in den nachfolgend beschriebenen API-Methoden verwendet:

Name Beschreibung
AuthorizationId Die einzigartige Kennung der Autorisierung
ContextId Die einzigartige ID des Kontexts, für den die Autorisierung erstellt wurde. Im Falle der Vault Bereich-Autorisierung ist dies die Vault-Bereich-Guid.
AuthorizationType ViewVaultSection oder ChangeVaultSection
OperatorGuid Wenn die Autorisierung für einen einzelnen Operator gilt, ist dies die Operator-Guid. Sie lautet null bei Operator-Gruppen-Autorisierungen.
OperatorGroupId Wenn die Autorisierung für eine Operator-Gruppe gilt, ist dies die Operator-Gruppen-ID. Sie lautet null bei Autorisierungen für einzelne Operator.

Autorisierungsendpunkte für Vault Bereiche

Request type Endpoint Usage
GET VaultSection/{VaultSectionGuid}/Authorization Gibt eine Liste aller Autorisierungen für den angegebenen Vault Bereich aus.
POST VaultSection/{VaultSectionGuid}/Authorization Erstellt eine neue Autorisierung für den angegebenen Vault Bereich mit den angegebenen Werten.
DELETE VaultSection/{VaultSectionGuid}/
Authorization/{AuthorizationGuid}
Löscht die angegebene Autorisierung.

GET VaultSection/{VaultSectionGuid}/Authorization

Die GET-Anfrage an VaultSection/{VaultSectionGuid}/Authorization gibt eine Liste aller Autorisierungen für den Vault Bereich, der in VaultSectionGuid angegeben ist.

Beispiel:

[
  {
    "AuthorizationId": "7210DD2D-3AAE-4F89-A2A8-000060F118F1 ",
    "ContextId": "8D4BAED2-56C2-4220-B36D-00013511D234",
    "AuthorizationType": "ChangeVaultSection",
    "OperatorGuid": "5F71AFD7-8BEE-4C8D-9827-A107308473BE",
    "OperatorGroupId": ""
  }, 
  {
    "AuthorizationId": "0BACEE61-0582-40FD-B1A2-00034401421A",
    "ContextId": "8D4BAED2-56C2-4220-B36D-00013511D234",
    "AuthorizationType": "ViewVaultSection",
    "OperatorGuid": "",
    "OperatorGroupId": "629F7189-6706-4DC2-989E-99DF511B09CB"
  }
]

Die Autorisierung gilt entweder für einen Operator oder eine Operator-Gruppe. Bei einer operatorspezifischen Autorisierung ist die OperatorGuid ausgefüllt und die OperatorGroupId leer. Bei einer Autorisierung für eine Operator-Gruppe wird die OperatorGroupId einen Wert enthalten und die OperatorGuid leer sein.

POST VaultSection/{VaultSectionGuid}/Authorization

Die POST-Anfrage an VaultSection/{VaultSectionGuid}/Authorization wird eine neue Autorisierung für den angegebenen Vault Bereich erstellen.

Beispiel:

{
  "ContextId": "8D4BAED2-56C2-4220-B36D-00013511D234",
  "AuthorizationType": "ViewVaultSection",
  "OperatorGuid": "",
  "OperatorGroupId": "629F7189-6706-4DC2-989E-99DF511B09CB"
}

Wenn Du eine Autorisierung des Typs ChangeVaultSection erstellst, wird automatisch eine zusätzliche ViewVaultSection-Autorisierung für den gleichen Operator oder die gleiche Operator-Gruppe hinzugefügt. Wenn ein Operator oder eine Operator-Gruppe für einen Vault Bereich über die Autorisierung Change + View (Ändern + Anzeigen) verfügt, wird dies als Full control (Vollzugriff) in der Uptrends App angezeigt.

DELETE VaultSection/{VaultSectionGuid}/Authorization/{AuthorizationGuid}

Die DELETE-Anfrage an VaultSection/{VaultSectionGuid}/ Authorization/AuthorizationGuid löscht eine bestehende Autorisierung.