Le coffre-fort est utilisé pour stocker des données réutilisables, souvent des données sensibles telles que des certificats, des clés publiques et des combinaisons nom d'utilisateur/mot de passe. Chaque entrée dans le coffre-fort est appelé un élément de coffre-fort, et les éléments de coffre-fort sont organisés en Sections de coffre-fort. L'organisation d'éléments dans des sections différentes est également utile pour restreindre l'accès à des opérateurs et des groupes particuliers. Cet article décrit les méthodes API disponibles pour la gestion des éléments, des sections et des autorisations de section pour les coffre-forts.

Pour une discussion des scénarios d’utilisation des coffre-forts, veuillez lire l'Introduction aux coffre-forts. Vous devriez lire l'Introduction à l'API v4 pour apprendre comment accéder à l’API.

Eléments du coffre-fort

Cet ensemble d'endpoints vous permet de récupérer, créer, mettre à jour et supprimer des éléments individuels du coffre-fort. En raison de la nature sensible de certains types d’éléments de coffre-fort, les données sensibles elles-mêmes ne sont jamais retournées.

Description de l'élément de coffre-fort en tant qu'objet

L'objet VaultItem suivant est utilisé dans les méthodes API décrites ci-dessous :

Nom Description
VaultItemGuid L'identifiant unique de l'élément de coffre-fort
Name Le nom d'affichage de l'élément de coffre-fort
VaultSectionGuid L'Identifiant unique de la section de coffre-fort dans laquelle cet élément de coffre-fort est stocké.
VaultItemType Définit le type d'élément du coffre-fort.
Actuellement, les types pris en charge sont les suivants :
•    CertificateArchive : pour les fichiers d’archivage de certificats (c.-à-d. fichiers pfx ), utilisés pour les certificats clients dans les moniteurs d’API multi-étapes.
•    Certificat : pour les clés publiques, utilisé pour la configuration Single Sign-On.
•    CredentialSet : des combinaisons nom d'utilisateur/mot de passe, utilisées pour les paramètres d'authentification dans les moniteurs.
Value La valeur stockée dans l'élément de coffre-fort. Le contenu de ce champ dépend du type d'élément de coffre-fort :
•    Pour le type CertificateArchive : spécifiez un encodage Base-64 de votre fichier binaire .pfx lorsque vous créez ou mettez à jour un élément de coffre-fort de ce type. Lorsque vous récupérez l'élément à nouveau, le champ Value sera toujours vide (car il s'agit d'informations sensibles).
•    Pour le type Certificat : spécifiez le contenu texte de votre clé publique lorsque vous créez ou mettez à jour un élément de coffre-fort de ce type. Lorsque vous récupérez l'élément à nouveau, le champ Value contient les données de clé publique d'origine.
•    Pour le type CredentialSet : ce champ est inutilisé. À la place, utilisez les champs UserName et Password.
IsSensitive Indique si la valeur stockée dans l'élément de coffre-fort est chiffrée. Lorsque cet attribut est égal à vrai, la ou les valeurs stockées ne seront pas visibles par l'application web ou par l'API. Cette valeur ne doit pas être spécifiée lors de la création d'un nouvel élément : les éléments CertificateArchive et CredentialSet sont toujours chiffrés (car ils contiennent des données sensibles par définition) alors que Certificat pour les clés publiques est par nature une information publique et peut être stockée comme du texte en clair.
Notes Une note ou une description se rapportant à cet élément de coffre-fort
UserName La partie nom d'utilisateur d'un credentialset.
Password Le mot de passe d'un credentialset.

Vault item endpoints

Les méthodes API suivantes sont disponibles :

Type de requête Endpoint Utilisation
GET VaultItem/GetAll Retourne tous les éléments du coffre-fort dans les sections auxquelles l'utilisateur a accès.
GET VaultItem/{VaultItemGuid} Renvoie l'élément de coffre-fort spécifié.
POST VaultItem Crée un nouvel élément de coffre-fort avec les valeurs spécifiées.
PUT VaultItem/{VaultItemGuid} Met à jour l'élément de coffre-fort spécifié.
DELETE VaultItem/{VaultItemGuid} Supprime l'élément de coffre-fort spécifié.

GET VaultItem/GetAll

La requête GET VaultItem/GetAll n'a pas de paramètres. Il retournera une liste contenant tous les éléments de coffre-fort des sections auxquelles vous avez un accès de consultation.

Exemple de contenu :

[
  {
    "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}

La requête GET VaultItem/ {VaultItemGuid} retournera l'élément coffre-fort identifié par son Guid.

Exemple d'un élément de coffre-fort retourné dans le contenu d'une réponse 200 :

{
  "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": ""
  }
}

Remarquez que les valeurs qui contiennent des informations sensibles sont renvoyées sous forme de chaîne vide.

PUT VaultItem/{VaultItemGuid}

La requête PUT pour l'endpoint VaultItem/{VaultItemGuid}mettra à jour l'élément du coffre-fort identifié par son guid. Dès que vous mettez à jour un élément de coffre-fort, tout moniteur qui contient une référence à cet élément de coffre-fort sera également mis à jour, et donc votre modification est prise en compte immédiatement.

Cette demande nécessite une autorisation ChangeVaultSection.

Une requête PUT exige la structure d'objet suivante :

{
  "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]"
  }
}

Dans l'exemple ci-dessus, s'il y avait eu une valeur dans le champ Notes de l'élément de coffre-fort au départ, il aurait été effacé ; le champ Notes après serait vide. Si vous omettez un paramètre, il ne restera pas inchangé, mais sera considéré vide (la valeur sera effacée). Les seules valeurs qui n'ont pas besoin d'être fournies sont les valeurs sensibles. Si, par exemple, vous omettez le champ Value ou Password, ou la totalité de l'objet CertificateArchive, ceux-ci resteront inchangés. De plus, les attributs IsSensitive et VaultSectionGuid ne peuvent pas être modifiés.

DELETE VaultItem/{VaultItemGuid}

La requête DELETE  pour l'endpoint VaultItem/{VaultItemGuid} effacera l'élément concerné.

Si l'élément de coffre-fort spécifié est en cours d'utilisation (par exemple, un moniteur lui fait référence), alors le service renvoie le code d’état 400 avec un message d'explication. Cette demande nécessite une autorisation ChangeVaultSection.

POST VaultItem

La requête POST  pour l'endpoint VaultItem créera un nouvel objet VaultItem. Lorsque vous spécifiez les données pour le VaultItem, omettez le VaultItemGuid : le nouveau GUID pour cet article sera retourné dans la réponse. Cette demande nécessite une autorisation ChangeVaultSection. 

Exemple de contenu :

{
 "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]"
 }
}

Sections du coffre-fort

Il existe plusieurs endpoints (points d’entrée accessibles par une adresse) dans cette API qui vous permettent de gérer vos sections de coffre-fort. Chaque objet de coffre-fort appartient à une seule section de coffre-fort. Si vous n'avez besoin que de quelques éléments de coffre-fort dans l'ensemble de votre compte, vous pouvez simplement les conserver dans une seule section de coffre-fort. Toutefois, si le nombre d'éléments de coffre-fort dans vos comptes commence à augmenter, il pourrait être utile de les organiser en sections distinctes.

Chaque compte Uptrends a par défaut une seule section de coffre-fort. Le groupe Administrateurs a un accès complet à cette section, ce qui signifie qu'ils peuvent modifier la section et tous les éléments de coffre-fort qu'elle contient. 

Lorsqu'une nouvelle section de coffre-fort est créée, l'utilisateur (opérateur) associé au compte API à l'origine de cette création obtient automatiquement l'autorisation ChangeVaultSection pour la nouvelle section. Aucune autre autorisation ne sera créée.

Description de l'objet Section de coffre-fort

L'objet suivant VaultSection est utilisé dans les méthodes API décrites ci-dessous :

Name Description
VaultSectionGuid L'identifiant unique de la section de coffre-fort
Name Le nom de la section de coffre-fort

Endpoints de section de coffre-fort

Type de requête Endpoint Utilisation
GET VaultSection/GetAll Retourne toutes les sections du coffre-fort auxquelles l'utilisateur a accès.
GET VaultSection/{VaultSectionGuid} Retourne la section de coffre-fort spécifiée
POST VaultSection Crée un nouvel élément de coffre-fort avec le nom spécifié
PUT VaultSection/{VaultSectionGuid} Met à jour la section de coffre-fort spécifiée
DELETE VaultSection/{VaultSectionGuid} Supprime la section de coffre-fort spécifiée

GET VaultSection/GetAll

La requête GET VaultSection/GetAll n'a pas de paramètres. Elle retournera une liste contenant toutes les sections de coffre-fort auxquelles vous avez un accès de consultation.

Exemple de contenu :

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

GET VaultSection/{VaultSectionGuid}

La requête GET VaultSection/{VaultSectionGuid} retournera la section de coffre-fort identifiée par le GUID de la section.

Exemple de contenu :

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

POST VaultSection

La requête POST  pour l'endpoint VaultSection créera un nouvel objet VaultSection. L'opérateur qui a émis la requête, en fonction du contexte utilisateur, recevra les autorisations ViewVaultSection et ChangeVaultSection pour cette nouvelle section. Aucune autre autorisation n'est accordée. Lorsque vous spécifiez les données pour la VaultSection, omettez le VaultSectionGuid ; le nouveau Guid pour cette section sera retourné dans la réponse.

{
  "Name": "Development vault items"
}

PUT VaultSection/{VaultSectionGuid}

La requête PUT  pour l'endpoint VaultSection/{VaultSectionGuid} mettra à jour la section de coffre-fort identifiée par l'élément de coffre-fort guid. En règle générale, le seul but de cette opération est de modifier le nom de la section du coffre-fort. Cette demande nécessite l'autorisation ChangeVaultSection.

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

DELETE VaultSection/{VaultSectionGuid}

La requête DELETE  pour l'endpoint VaultSection/ {VaultSectionGuid} supprimera la section de coffre-fort demandée.

Si la section de coffre-fort spécifiée est toujours utilisée (des éléments de coffre sont stockés dans cette section), le service renvoie le code d’état 400, avec un message d'explication. Si tel est le cas, vous devrez supprimer les éléments du coffre-fort avant de pouvoir supprimer la section. Gardez à l'esprit que vous ne pouvez pas supprimer un élément de coffre-fort si celui-ci est toujours utilisé (par exemple, lorsqu'un moniteur est configuré pour utiliser cet élément de coffre-fort). Cette demande nécessite l'autorisation ChangeVaultSection.

Autorisations des Sections de coffre-fort

En plus de séparer les éléments du coffre-fort les uns des autres, les sections du coffre-fort vous permettent également de contrôler qui a accès à quoi. Si vous souhaitez qu'un groupe spécifique d'opérateurs dispose d'un accès exclusif à certains éléments du coffre-fort, placez ces éléments dans une section distincte. Seules les personnes ayant accès à cette section de coffre-fort peuvent voir les éléments de coffre-fort contenus dans cette section.

Lorsque vous créez une nouvelle section de coffre-fort (via l’API ou l’application en ligne), cette section n’est visible que par vous dans un premier temps. Si vous y avez ajouté des éléments de coffre-fort, les autres opérateurs ne peuvent ni modifier ni utiliser ces éléments de coffre-fort.

Afin de permettre aux autres utilisateurs d'utiliser la nouvelle section du coffre-fort, d'y ajouter des éléments et/ou de sélectionner ces éléments dans les paramètres d'un moniteur, vous devez leur en donner l'accès. Cela se fait avec les méthodes API suivantes.

Il existe deux types d’autorisations : ViewVaultSection et ChangeVaultSection. Ces types d'autorisation peuvent être accordés aux opérateurs et aux groupes d'opérateurs.

Description de l'objet Autorisation

L'objet d'autorisation suivant est utilisé dans les méthodes API décrites ci-dessous :
Nom Description
AuthorizationId L'identifiant unique de l'autorisation
ContextId Identificateur unique du contexte pour lequel l'autorisation est créée. Dans le cas d'une autorisation de section de coffre-fort, il s'agit du Guid de la section.
AuthorizationType ViewVaultSection ou ChangeVaultSection
OperatorGuid Si l'autorisation doit être accordée à un seul opérateur, spécifie le Guid de l'opérateur. Mis à null pour les autorisations de groupe d'opérateurs.
OperatorGroupId Si l'autorisation doit être accordée à un groupe d'opérateurs, spécifie l'ID du groupe d'opérateurs. Mis à null pour les autorisations d'opérateur unique.

Les endpoints pour les autorisations de Section de coffre-fort

Type de requête Endpoint Utilisation
GET VaultSection/{VaultSectionGuid}/Authorization Retourne une liste de toutes les autorisations pour la section de coffre-fort spécifiée.
POST VaultSection/{VaultSectionGuid}/Authorization Crée une nouvelle autorisation pour la section de coffre-fort spécifiée, en utilisant les valeurs fournies.
DELETE VaultSection/{VaultSectionGuid}/
Authorization/{AuthorizationGuid}
Supprime l'autorisation spécifiée.

GET VaultSection/{VaultSectionGuid}/Authorization

La requête GET  pour VaultSection/{VaultSectionGuid}/Autorisation retourne une liste de toutes les autorisations pour la section de coffre-fort spécifiée par VaultSectionGuid.

Exemple de contenu  :

[
  {
    "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"
  }
]

Une autorisation s'applique soit à un opérateur, soit à un groupe d'opérateurs. Une autorisation pour un opérateur aura une valeur pour l'OpérateurGuid et un OperatorGroupId vide; une autorisation pour un groupe d'opérateurs aura une valeur pour l'OperatorGroupId et un OpérateurGuid vide.

POST VaultSection/{VaultSectionGuid}/Authorization

La requête POST  pour VaultSection/{VaultSectionGuid}/Autorisation créera une nouvelle autorisation pour la section de coffre spécifiée.

Exemple de contenu :

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

Si vous créez une autorisation de type ChangeVaultSection, l'autorisation supplémentaire de ViewVaultSection pour le même opérateur ou groupe d'opérateurs sera ajoutée automatiquement. Si l'autorisation de section de coffre-fort Change + View existe pour un opérateur ou un groupe d’opérateurs, alors elle apparaîtra comme Full control dans l'application Uptrends.

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

La requête DELETE  pour VaultSection/{VaultSectionGuid} / Autorisation/AuthorizationGuid supprimera une autorisation existante.