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 |
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
La requête GET VaultItem 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.