API du coffre-fort

Le coffre-fort est utilisé pour stocker des données réutilisables, qui sont souvent des données sensibles telles que des certificats, des clés publiques et des combinaisons de nom d’utilisateur et mot de passe. Chaque élément enregistré 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. Organiser les éléments dans des sections différentes permet aussi d’en réserver l’accès à des opérateurs et à des groupes particuliers.

Cet article décrit les méthodes API disponibles pour gérer les éléments, les sections et les autorisations liées aux sections de coffre-fort. Pour connaître les scénarios d’usage du coffre-fort, veuillez lire notre introduction sur les coffres-forts . Pour savoir comment accéder à l’API, consultez notre introduction sur l’API v4 .

Éléments de 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 renvoyées.

Description de l’objet Élément de coffre-fort

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

Endpoints des éléments de coffre-fort

Les méthodes API suivantes sont disponibles :

GET /VaultItem

La requête GET VaultItem n’est pas paramétrable. Elle renvoie une liste contenant tous les éléments de coffre-fort des sections que vous pouvez consulter.

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": ""
    },
    "VaultItemUsedBy": "1 monitor"
  },
  {
    "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": ""
    },
  "VaultItemUsedBy": "-"
  }
]

GET /VaultItem/{VaultItemGuid}

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

Exemple d’un élément de coffre-fort renvoyé 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": ""
  },
  "VaultItemUsedBy": "1 monitor"
}

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} met à 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 est également mis à jour pour que votre modification soit prise en compte immédiatement.

Cette requête 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 original, le champ Notes aurait été vide. Si vous omettez un paramètre, il ne restera pas inchangé, mais sera considéré comme vide. 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} efface l’élément indiqué.

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

POST /VaultItem

La requête POST pour l’endpoint VaultItem créera un nouvel objet VaultItem. Lorsque vous indiquez les données pour le VaultItem, omettez le VaultItemGuid : le nouveau GUID pour cet article sera renvoyé dans la réponse. Cette requête 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

Cette API fournit plusieurs endpoints pour 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 pour tout votre compte, vous pouvez simplement les conserver dans une seule section de coffre-fort. En revanche, si le nombre d’éléments de coffre-fort liés à votre compte commence à augmenter, il peut être judicieux de commencer à les organiser en sections distinctes.

Par défaut, chaque compte Uptrends compte une seule section de coffre-fort. Le groupe Administrateurs dispose d’un accès complet à cette section, ce qui signifie que les administrateurs 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 n’est créée.

Description de l’objet Section de coffre-fort

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

Endpoints des sections de coffre-fort

GET /VaultSection

La requête GET VaultSection n’est pas paramétrable. Elle renvoie une liste contenant toutes les sections de coffre-fort que vous pouvez consulter.

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} renvoie la section de coffre-fort identifiée par son GUID.

Exemple de contenu :

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

POST /VaultSection

La requête POST pour l’endpoint VaultSection crée un nouvel objet VaultSection. L’opérateur dans le contexte duquel la requête a été émise recevra les autorisations ViewVaultSection et ChangeVaultSection pour cette nouvelle section. Aucune autre autorisation n’est créée. Lorsque vous fournissez les données pour l’objet VaultSection, omettez le VaultSectionGuid : le nouveau GUID pour cette section sera renvoyé dans la réponse.

{
  "Name": "Development vault items"
}

PUT /VaultSection/{VaultSectionGuid}

La requête PUT pour l’endpoint VaultSection/{VaultSectionGuid} met à jour la section de coffre-fort identifiée par le GUID de l’élément de coffre-fort. 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 requête nécessite une 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} supprime la section de coffre-fort demandée.

Si la section de coffre-fort est en cours d’utilisation (par exemple, des éléments de coffre-fort y sont stockés), alors 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 utilisé (par exemple, lorsqu’un moniteur est configuré pour utiliser cet élément de coffre-fort). Cette requête nécessite une autorisation ChangeVaultSection.

Autorisations liées aux sections de coffre-fort

En plus de séparer les éléments du coffre-fort, les sections du coffre-fort vous permettent de contrôler qui a accès à quoi. Si vous souhaitez qu’un groupe d’opérateurs spécifique dispose d’un accès réservé à 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.

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. Pour cela, vous pouvez utiliser 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 Authorization est utilisé dans les méthodes API décrites ci-dessous :

Endpoints pour les autorisations liées aux sections de coffre-fort

GET /VaultSection/{VaultSectionGuid}/Authorization

La requête GET pour l’endpoint VaultSection/{VaultSectionGuid}/Authorization renvoie 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. L’autorisation pour un opérateur fournit une valeur pour l’OperatorGuid et aucune valeur pour l’OperatorGroupID. Dans le cas de l’autorisation pour un groupe d’opérateurs, c’est le contraire qui s’applique.

POST /VaultSection/{VaultSectionGuid}/Authorization

La requête POST pour l’endpoint VaultSection/{VaultSectionGuid}/Authorization crée une nouvelle autorisation pour la section de coffre-fort indiqué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 est ajoutée automatiquement. Si un opérateur ou un groupe d’opérateurs dispose des autorisations “Changer + Voir”, l’autorisation affichera Contrôle complet dans l’application Uptrends.

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

La requête DELETE pour l’endpoint VaultSection/{VaultSectionGuid}/ Authorization/AuthorizationGuid supprime l’autorisation existante.