API d’administration de vérification d’identité
L’API Administration de Vérification d’identité Microsoft Entra vous permet de gérer tous les aspects du service Justificatifs vérifiables. Elle offre un moyen de configurer un tout nouveau service, de gérer et de créer des contrats Vérification d’identité, de révoquer des informations d’identification vérifiables et de désactiver complètement le service.
L’API est destinée aux développeurs qui sont à l’aise avec les API RESTful et qui disposent de suffisamment d’autorisations sur le tenant Microsoft Entra pour activer le service
L’API Administration est accessible via HTTPS. Toutes les URL référencées dans la documentation ont la base suivante : https://verifiedid.did.msidentity.com
.
L’API est protégée via Microsoft Entra ID et utilise des jetons du porteur OAuth2. Le jeton d’accès peut être destiné à un utilisateur ou à une application.
L’inscription de l’application doit avoir l’autorisation d’API pour Verifiable Credentials Service Admin
puis, lors de l’acquisition du jeton d’accès, l’application doit utiliser l’étendue 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
. Le jeton d’accès doit être destiné à un utilisateur ayant le rôle Administrateur général ou Administrateur de stratégie d’authentification. Un utilisateur disposant du rôle Lecteur général peut effectuer des appels d’API en lecture seule.
Le service Verifiable Credentials Service Admin
prend en charge les autorisations d’application suivantes.
Autorisation | Description |
---|---|
VerifiableCredential.Authority.ReadWrite | Autorisation de lire/écrire les objets Autorité |
VerifiableCredential.Contract.ReadWrite | Autorisation de lire/écrire les objets Contrat |
VerifiableCredential.Credential.Search | Autorisation de rechercher des informations d’identification à révoquer |
VerifiableCredential.Credential.Revoke | Autorisation de révoquer des informations d’identification précédemment émises |
VerifiableCredential.Network.Read | Autorisation de lire les entrées du réseau de vérification d’identité |
L’inscription d’application doit avoir l’autorisation d’API pour Verifiable Credentials Service Admin
et les autorisations requises dans le tableau ci-dessus. Lors de l’acquisition du jeton d’accès, via le flux d’informations d’identification du client, l’application doit utiliser l’étendue 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
.
Si l’application a l’intention de créer une autorité, elle a besoin de deux choses. Tout d’abord, l’inscription de l’application a besoin de l’autorisation VerifiableCredential.Authority.ReadWrite
. Deuxièmement, l’application doit disposer des autorisations Create Key
dans les stratégies d’accès key Vaults. Si l’application lit/écrit uniquement les autorités existantes, elle n’a pas besoin de l’autorisation Key Vault.
Cette API permet de créer un environnement afin que de nouvelles autorités puissent être configurées. Cela peut être déclenché manuellement en accédant à la page Informations d’identification vérifiables du portail Azure. Vous n’avez besoin d’appeler cette API qu’une seule fois, et seulement si vous souhaitez configurer un nouvel environnement juste avec l’API.
POST /v1.0/verifiableCredentials/onboard
Utilisez ce point de terminaison pour terminer le provisionnement du service Vérification d’identité dans votre locataire. Le système crée le reste des principaux de service si ceux-ci ne sont pas encore provisionnés.
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
"verifiableCredentialServicePrincipalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
"verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
"status": "Enabled"
}
L’appel répété de cette API génère exactement le même message de retour.
Ce point de terminaison peut être utilisé pour créer ou mettre à jour une instance du service Vérification d’identité.
Méthodes | Type de retour | Description |
---|---|---|
Obtenir l’autorité | Authority | Lire les propriétés d’une autorité |
Lister les autorités | Tableau d’autorités | Obtenir une liste de tous les services Vérification d’identité/autorités configuré(e)s |
Créer une autorité | Authority | Créer une autorité |
Mettre à jour une autorité | Authority | Mettre à jour une autorité |
Supprimer l’autorité | Autorité | Supprimer l’autorité |
Générer une configuration DID connue | ||
Générer un document DID | ||
Valider une configuration DID connue | ||
Permuter la clé de signature | Autorité | Rotation de la clé de signature |
Synchroniser avec le document DID | Autorité | Synchroniser le document DID avec la nouvelle clé de signature |
Récupérer les propriétés d’une autorité configurée ou d’une instance du service Vérification d’identité.
GET /v1.0/verifiableCredentials/authorities/:authorityId
Remplacez :authorityId
par la valeur de l’une des autorités configurées.
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
La réponse contient les propriétés suivantes.
Propriété | Type | Description |
---|---|---|
Id |
string | ID unique généré automatiquement, qui peut être utilisé pour récupérer ou mettre à jour l’instance spécifique du service Vérification d’identité |
name |
string | Nom convivial de cette instance du service Vérification d’identité |
status |
string | État du service ; cette valeur sera toujours enabled |
didModel | didModel | Informations sur le DID et les clés |
keyVaultMetadata | Données keyVaultMeta | Informations sur le coffre de clés utilisé |
Propriété | Type | Description |
---|---|---|
did |
string | DID pour cette instance du service Vérification d’identité |
signingKeys |
tableau de chaînes | URL de la clé de signature |
linkedDomainUrls |
tableau de chaînes | Domaines liés à ce DID ; une seule entrée attendue |
didModel | didModel | Informations sur le DID et les clés |
didDocumentStatus |
string | État du DID ; la valeur est toujours published pour cette méthode |
Propriété | Type | Description |
---|---|---|
subscriptionId |
string | Abonnement Azure où réside ce coffre de clés |
resourceGroup |
string | Nom du groupe de ressources de ce coffre de clés |
resourceName |
string | Nom du coffre de clés |
resourceUrl |
string | URL de ce coffre de clés |
Obtenir toutes les autorités ou tous les services Vérification d’identité configuré(e)s pour ce locataire
GET /v1.0/verifiableCredentials/authorities
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
Le message de réponse est un tableau d’autorités
Exemple :
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName2",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid2.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
Cet appel crée une clé privée, une clé de récupération et une clé de mise à jour, stocke ces clés dans le coffre de clés Azure spécifié, définit les autorisations sur ce coffre de clés pour le service de justificatifs vérifiables, crée un DID avec le document DID correspondant.
POST /v1.0/verifiableCredentials/authorities
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Dans le corps de la requête, fournissez une représentation JSON des éléments suivants :
Propriété | Type | Description |
---|---|---|
name |
string | Nom complet de cette instance du service |
linkedDomainUrl |
string | Domaine lié à ce DID |
didMethod |
string | Doit être web |
keyVaultMetadata |
keyVaultMetadata | Métadonnées pour un coffre de clés spécifique |
Exemple de message :
{
"name":"ExampleName",
"linkedDomainUrl":"https://verifiedid.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
En cas de réussite, le message de réponse contient le nom de l’autorité
Exemple de message pour did:web :
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Exemple de message pour did:ion :
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Vous pouvez créer plusieurs autorités avec leurs propres clés privées et DID. Ils ne vont pas être visibles dans l’interface utilisateur du Portail Azure. Actuellement, nous ne prenons en charge qu’une seule autorité. Nous n’avons pas entièrement testé tous les scénarios avec plusieurs autorités créées. Si vous essayez cela, veuillez nous faire part de votre expérience.
Cette méthode peut être utilisée pour mettre à jour le nom complet de cette instance spécifique du service Vérification d’identité.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Remplacez la valeur de :authorityId
par la valeur de l’ID d’autorité à mettre à jour.
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Dans le corps de la requête, fournissez une représentation JSON des éléments suivants :
Propriété | Type | Description |
---|---|---|
name |
string | Nom complet de cette instance du service |
Exemple de message
{
"name":"ExampleIssuerName"
}
Cette méthode peut être utilisée pour supprimer une autorité. Actuellement, seules les autorités did:ion
peuvent être supprimées. Lorsque vous supprimez une autorité, toutes les identifiants de la Vérification d’identité émises ne sont plus valides et ne peuvent plus être vérifiées car l’autorité émettrice est passée.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Remplacez la valeur de :authorityId
par la valeur de l’ID d’autorité à supprimer.
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Aucun corps de la demande
Exemple de message de réponse :
Réponse de l’autorité de suppression réussie.
HTTP/1.1 200 OK
Si la suppression de l’autorité a réussi, mais que propre up des clés Azure Key Vault a échoué, vous obtenez la réponse ci-dessous.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "deleteIssuerSuccessfulButKeyDeletionFailed",
"message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
}
}
La méthode generateWellknownDidConfiguration
génère le fichier did-configuration.json signé. Le fichier doit être chargé dans le dossier .well-known
à la racine du site web hébergé pour le domaine dans le domaine lié de cette instance de Vérification d’identité. Vous trouverez des instructions ici.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Vous devez spécifier l’un des domaines dans les linkedDomains de l’autorité spécifiée.
{
"domainUrl":"https://atest/"
}
Exemple de message de réponse :
HTTP/1.1 200 OK
Content-type: application/json
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbGciOiJFUzI1NksiL...<SNIP>..."
]
}
Enregistrez ce résultat avec le nom de fichier did-configuration.json, et chargez ce fichier vers le dossier et le site web appropriés. Si vous spécifiez un domaine non lié à ce DID/document DID, vous recevez une erreur :
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"079192a95fbf56a661c1b2dd0e012af5",
"date":"Mon, 07 Feb 2022 18:55:53 GMT",
"mscv":"AVQh55YiU3FxMipB.0",
"error":
{
"code":"wellKnownConfigDomainDoesNotExistInIssuer",
"message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
}
}
Vous pouvez faire pointer plusieurs DID vers le même domaine. Si vous choisissez cette configuration, vous devez combiner des jetons générés et les placer dans le même fichier did-configuration.json. Le fichier contient un tableau de ces jetons.
Par exemple :
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Cet appel génère le document de DID utilisé pour les identificateurs DID:WEB. Après avoir généré ce document de DID, l’administrateur doit placer le fichier à l’emplacement https://domain/.well-known/did.json.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "did:web:verifiedid.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:verifiedid.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://verifiedid.contoso.com/"
]
}
},
{
"id": "#hub",
"type": "IdentityHub",
"serviceEndpoint": {
"instances": [
"https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
]
}
}
],
"verificationMethod": [
{
"id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
"controller": "did:web:verifiedid.contoso.com",
"type": "EcdsaSecp256k1VerificationKey2019",
"publicKeyJwk": {
"crv": "secp256k1",
"kty": "EC",
"x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
"y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
}
}
],
"authentication": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
],
"assertionMethod": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
]
}
Nécessite que l’appelant dispose des autorisations Lister les clés sur le coffre de clés cible.
Cet appel vérifie votre configuration DID. Il télécharge la configuration DID connue, et vérifie si le DID correct est utilisé et si la signature est correcte.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
HTTP/1.1 204 No Content
Content-type: application/json
La rotation de la clé de signature crée une clé privée pour l’autorité did:web. Le document DID doit être réinscrit pour refléter la mise à jour. Une fois cette opération effectuée, synchronizeWithDidDocument indique au système de commencer à utiliser la nouvelle clé pour la signature.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
didDocumentStatus
passe à outOfSync
.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Après la rotation de la clé de signature, le document DID doit être réinscrit pour refléter la mise à jour. Une fois cette opération effectuée, synchronizeWithDidDocument indique au système de commencer à utiliser la nouvelle clé pour la signature.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
didDocumentStatus
passe de outOfSync
à published
en cas d’appel réussi.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Ce point de terminaison vous permet de créer de nouveaux contrats et de mettre à jour les contrats existants. Les contrats se composent de deux parties représentées par deux définitions JSON. Vous trouverez des informations sur la conception et la création manuelle d’un contrat ici.
- La définition d’affichage est utilisée par les administrateurs pour contrôler l’apparence des informations d’identification vérifiables, par exemple la couleur d’arrière-plan, le logo et le titre. Ce fichier contient également les revendications qui doivent être stockées dans les informations d’identification vérifiables.
- La définition de règles contient les informations sur la manière de collecter des attestations telles que les revendications auto-attestées, d’autres informations d’identification vérifiables comme entrée, ou éventuellement un jeton d’ID reçu une fois qu’un utilisateur s’est connecté à un fournisseur d’identité compatible OIDC.
Méthodes | Type de retour | Description |
---|---|---|
Obtenir un contrat | Contrat | Lire les propriétés d’un contrat |
Lister les contrats | Collection de contrats | Obtenir une liste de tous les contrats configurés |
Créer un contrat | Contrat | Créer un contrat |
Mettre à jour une contrat | Contrat | Mettre à jour un contrat |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Remplacez :authorityId
et :contractId
par la valeur correcte de l’autorité et du contrat.
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
Exemple de message :
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": <rulesModel>,
"displays": <displayModel[]>,
"allowOverrideValidityIntervalOnIssuance": false
}
La réponse contient les propriétés suivantes :
Propriété | Type | Description |
---|---|---|
Id |
string | ID de contrat |
name |
string | Nom convivial de ce contrat |
status |
string | Toujours Enabled |
manifestUrl |
string | URL du contrat utilisé dans la requête d’émission |
issueNotificationEnabled |
boolean | Défini sur true si les utilisateurs seront avertis que ces informations d’identification vérifiables sont prêtes à être émises pour eux |
issueNotificationAllowedToGroupOids |
Tableau de chaînes groupId | Tableau d’ID de groupes auxquels ces informations d’identification seront proposées |
availableInVcDirectory |
boolean | Indique si ce contrat est publié dans le réseau Vérification d’identité |
rules | rulesModel | Définition de règles |
displays | Tableau displayModel | Définitions d’affichage |
allowOverrideValidityIntervalOnIssuance |
booléen | Si l’appel d’API createIssuanceRequest est autorisé à remplacer l’expiration des informations d’identification. Cela n’est valide que pour les flux idTokenHint. |
Propriété | Type | Description |
---|---|---|
attestations |
attestations | Description des entrées prises en charge pour les règles |
validityInterval |
nombre | Cette valeur indique la durée de vie des informations d’identification |
vc |
tableau vcType | types pour ce contrat |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-type) (facultatif) | Point de terminaison d’état à inclure dans les informations d’identification vérifiables pour ce contrat |
Si la propriété customStatusEndpoint
n’est pas spécifiée, le point de terminaison d’état anonymous
est utilisé.
Propriété | Type | Description |
---|---|---|
idTokens |
idTokenAttestation (tableau) (facultatif) | décrit les entrées de jeton d’ID |
idTokenHints |
idTokenHintAttestation (tableau) (facultatif) | décrit les entrées d’indicateur de jeton d’ID |
presentations |
verifiablePresentationAttestation (tableau) (facultatif) | décrit les entrées de présentations vérifiables |
selfIssued |
selfIssuedAttestation (tableau) (facultatif) | décrit les entrées auto-émises |
accessTokens |
accessTokenAttestation (tableau) (facultatif) | décrit les entrées de jeton d’accès |
Propriété | Type | Description |
---|---|---|
mapping |
claimMapping (facultatif) | règles pour mapper les revendications d’entrée en revendications de sortie dans les justificatifs vérifiables |
configuration |
string (url) | Emplacement du document de configuration de votre fournisseur d’identité |
clientId |
string | ID client à utiliser lors de l’obtention du jeton d’ID |
redirectUri |
string | L’URI de redirection à utiliser lors de l’obtention du jeton d’ID DOIT ÊTRE vcclient://openid/ |
scope |
string | liste délimitée d’espaces d’étendues à utiliser lors de l’obtention du jeton d’ID |
required |
booléenne (false par défaut) | indiquant si cette attestation est requise ou non |
Propriété | Type | Description |
---|---|---|
mapping |
claimMapping (facultatif) | règles pour mapper les revendications d’entrée en revendications de sortie dans les justificatifs vérifiables |
required |
booléenne (false par défaut) | indiquant si cette attestation est requise ou non |
trustedIssuers |
chaîne (tableau) | Liste des DID autorisés à émettre les informations d’identification vérifiables pour ce contrat. |
Propriété | Type | Description |
---|---|---|
mapping |
claimMapping (facultatif) | règles pour mapper les revendications d’entrée en revendications de sortie dans les justificatifs vérifiables |
credentialType |
chaîne (facultatif) | type d’informations d’identification requis de l’entrée |
required |
booléenne (false par défaut) | indiquant si cette attestation est requise ou non |
trustedIssuers |
chaîne (tableau) | Liste des DID autorisés à émettre les informations d’identification vérifiables pour ce contrat. |
Propriété | Type | Description |
---|---|---|
mapping |
claimMapping (facultatif) | règles pour mapper les revendications d’entrée en revendications de sortie dans les justificatifs vérifiables |
required |
booléenne (false par défaut) | indiquant si cette attestation est requise ou non |
Propriété | Type | Description |
---|---|---|
mapping |
claimMapping (facultatif) | règles pour mapper les revendications d’entrée en revendications de sortie dans les justificatifs vérifiables |
required |
booléenne (false par défaut) | indiquant si cette attestation est requise ou non |
Les valeurs
inputClaim
prises en charge pour la propriétémappings
sont les suivantes :givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
,photo
.
Propriété | Type | Description |
---|---|---|
inputClaim |
string | nom de la revendication à utiliser à partir de l’entrée |
outputClaim |
string | nom de la revendication dans les justificatifs vérifiables |
indexed |
booléenne (false par défaut) | Indique si la valeur de cette revendication est utilisée pour la recherche ; un seul objet clientMapping peut être indexé pour un contrat donné |
required |
booléenne (false par défaut) | indiquant si ce mappage est obligatoire ou non |
type |
chaîne (facultatif) | type de revendication |
Propriété | Type | Description |
---|---|---|
url |
string (url) | URL du point de terminaison à l’état personnalisé |
type |
string | Type du point de terminaison |
exemple :
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
"redirectUri": "vcclient://openid/",
"scope": "openid",
"mapping": [
{
"outputClaim": "givenName",
"required": false,
"inputClaim": "given_name",
"indexed": false
},
{
"outputClaim": "familyName",
"required": false,
"inputClaim": "family_name",
"indexed": true
}
],
"required": false
}
]
},
"validityInterval": 2592000,
"vc": {
"type": [
"BankofWoodgroveIdentity"
]
}
}
Propriété | Type | Description |
---|---|---|
locale |
string | paramètres régionaux de cet affichage |
credential |
displayCredential | les propriétés d’affichage des justificatifs vérifiables |
consent |
displayConsent | données supplémentaires lorsque les justificatifs vérifiables sont émis |
claims |
tableau displayClaims | étiquettes pour les revendications incluses dans les justificatifs vérifiables |
Propriété | Type | Description |
---|---|---|
title |
string | titre des informations d'identification |
issuedBy |
string | Le nom de l’émetteur des informations d'identification |
backgroundColor |
nombre (hexadécimal) | Couleur d’arrière-plan des informations d’identification au format hex, par exemple #FFAABB |
textColor |
nombre (hexadécimal) | Couleur du texte des informations d’identification au format hex, par exemple #FFAABB |
description |
string | Texte supplémentaire affiché à côté de chaque informations de connexion |
logo |
displayCredentialLogo | logo à utiliser pour les informations d’identification |
Propriété | Type | Description |
---|---|---|
uri |
chaîne (uri) | URI du logo. S’il s’agit d’une URL, elle doit être accessible de manière anonyme sur l’Internet public. |
description |
string | Description de logo |
Propriété | Type | Description |
---|---|---|
title |
string | titre du consentement |
instructions |
string | texte supplémentaire à utiliser lors de l’affichage du consentement |
Propriété | Type | Description |
---|---|---|
label |
string | étiquette de la revendication en affichage |
claim |
string | nom de la revendication à laquelle l’étiquette s’applique |
type |
string | type de la revendication |
description |
chaîne (facultatif) | description de la revendication |
Exemple :
{
"displays": [
{
"locale": "en-US",
"card": {
"backgroundColor": "#FFA500",
"description": "ThisisyourBankofWoodgroveIdentity",
"issuedBy": "BankofWoodgrove",
"textColor": "#FFFF00",
"title": "BankofWoodgroveIdentity",
"logo": {
"description": "Defaultbankofwoodgrovelogo",
"uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
Cette API liste tous les contrats configurés dans le locataire actuel pour l’autorité spécifiée.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
Exemple de message :
{
"value":
[
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "test1",
"authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
"name": "test2",
"authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
}
]
}
Lors de la création d’un contrat, le nom doit être unique dans le locataire. Si vous avez créé plusieurs autorités, le nom du contrat doit être unique parmi toutes les autorités. Le nom du contrat fera partie de l’URL du contrat utilisée dans les requêtes d’émission.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Exemple de requête
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Exemple de message :
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "GUID",
"name": "ExampleContractName1",
"issuerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"rules": "<rules JSON>",
"displays": [{<display JSON}],
"manifestUrl": "https://..."
}
Cette API vous permet de mettre à jour le contrat.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Exemple de requête :
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Exemple de message :
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": true,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[],
"allowOverrideValidityIntervalOnIssuance": true
}
Ce point de terminaison vous permet de rechercher des informations d’identification vérifiables émises, de vérifier l’état de révocation et de révoquer des informations d’identification.
Méthodes | Type de retour | Description |
---|---|---|
Obtenir des informations d’identification | Informations d'identification | Lire les propriétés d’informations d’identification |
Rechercher des informations d’identification | Collection d’informations d’identification | Rechercher une liste d’informations d’identification avec une valeur de revendication spécifique |
Révoquer des informations d’identification | Révoquer des informations d’identification spécifiques |
Cette API vous permet de récupérer des informations d’identification spécifiques et de vérifier leur état afin de savoir si elles sont révoquées ou non.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Exemple de message
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Vous pouvez rechercher des informations d’identification vérifiables avec des revendications d’index spécifiques. Étant donné que seul un hachage est stocké, vous devez rechercher la valeur calculée spécifique. L’algorithme que vous devez utiliser est : Base64Encode(SHA256(ID de contrat + valeur de revendication)) Voici un exemple en C# :
string claimvalue = "Bowen";
string contractid = "<...your-contract-id-value...>";
string output;
using (var sha256 = SHA256.Create())
{
var input = contractid + claimvalue;
byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
}
La requête suivante montre comment ajouter la valeur calculée au paramètre de filtre de la requête. À l’heure actuelle, seul le format filter=indexclaimhash eq est pris en charge.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
Exemple de message
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"status": "valid",
"issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
}
]
}
Cette API vous permet de révoquer des informations d’identification spécifiques une fois que vous les avez recherchées à l’aide de l’API de recherche. Les informations d’identification peuvent être révoquées en spécifiant l’ID d’informations d’identification spécifique.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
HTTP/1.1 204 No Content
Content-type: application/json
Cette méthode supprime complètement toutes les instances du service Vérification d’identité dans ce locataire. Elle supprime tous les contrats configurés. Les informations d’identification vérifiables émises ne peuvent pas toutes être vérifiées pour la révocation. Cette action ne peut pas être annulée.
Avertissement
Cette action ne peut pas être annulée, et elle invalidera toutes les informations d’identification vérifiables émises et les contrats créés.
POST /v1.0/verifiableCredentials/optout
En-tête | Valeur |
---|---|
Autorisation | Porteur (jeton). Obligatoire |
Content-Type | application/json |
Ne fournissez pas de corps de requête pour cette méthode.
Exemple de message de réponse
HTTP/1.1 200 OK
Content-type: application/json
OK
Notes
Si vous n’avez pas d’autorisations de suppression sur Key Vault, nous retournerons un message d’erreur et procéderons quand même à la désactivation