API d’administration de vérification d’identité

Article
01/11/2024

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

URL de base

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.

Authentification

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.

Jetons du porteur d’utilisateur

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.

Jetons du porteur d’application

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.

Intégration

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.

Demande HTTP

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êtes de requête

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de retour

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.

Autorités

Ce point de terminaison peut être utilisé pour créer ou mettre à jour une instance du service Vérification d’identité.

Méthodes

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

Obtenir l’autorité

Récupérer les propriétés d’une autorité configurée ou d’une instance du service Vérification d’identité.

Demande HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId

Remplacez :authorityId par la valeur de l’une des autorités configurées.

En-têtes de requête

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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.

Type d’autorité

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é

Type de didModel

web

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

Type de keyVaultMetadata

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

Lister les autorités

Obtenir toutes les autorités ou tous les services Vérification d’identité configuré(e)s pour ce locataire

Demande HTTP

GET /v1.0/verifiableCredentials/authorities

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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

Créer une autorité

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.

Requête HTTP

POST /v1.0/verifiableCredentials/authorities

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

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/"
  }
}

Message de réponse

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/"
    }
}

Remarques

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.

Mettre à jour une autorité

Cette méthode peut être utilisée pour mettre à jour le nom complet de cette instance spécifique du service Vérification d’identité.

Demande HTTP

PATCH /v1.0/verifiableCredentials/authorities/:authorityId

Remplacez la valeur de :authorityId par la valeur de l’ID d’autorité à mettre à jour.

En-têtes de requête

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

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

Supprimer l’autorité

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.

Requête HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

Remplacez la valeur de :authorityId par la valeur de l’ID d’autorité à supprimer.

En-têtes de requête

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Aucun corps de la demande

Message de réponse

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

Configuration DID connue

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.

Demande HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Vous devez spécifier l’un des domaines dans les linkedDomains de l’autorité spécifiée.

{
    "domainUrl":"https://atest/"
}

Message de réponse

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/"
  }
}

Remarques

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

Générer un document de DID

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.

Demande HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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

Remarque

Nécessite que l’appelant dispose des autorisations Lister les clés sur le coffre de clés cible.

Valider une configuration DID connue

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.

Demande HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

HTTP/1.1 204 No Content
Content-type: application/json

Rotation de la clé de signature

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.

Requête HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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
}

Synchroniser avec le document DID

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.

Requête HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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
}

Contrats

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

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

Obtenir un contrat

Demande HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

Remplacez :authorityId et :contractId par la valeur correcte de l’autorité et du contrat.

En-têtes de requête

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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 :

Type de contrat

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.

type rulesModel

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é.

type d’attestations

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

type idTokenAttestation

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

idTokenHintAttestation type

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.

type vérifiablePresentationAttestation

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.

type selfIssuedAttestation

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

Type d’accessTokenAttestation

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, mail, jobTitle, photo.

type claimMapping

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

Type de customStatusEndpoint

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

type displayModel

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

type displayCredential

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

type displayCredentialLogo

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

Type displayConsent

Propriété	Type	Description
`title`	string	titre du consentement
`instructions`	string	texte supplémentaire à utiliser lors de l’affichage du consentement

Type DisplayClaims

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

Lister les contrats

Cette API liste tous les contrats configurés dans le locataire actuel pour l’autorité spécifiée.

Demande HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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

Créer un contrat

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.

Demande HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Exemple de requête

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

Message de réponse

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://..."
}

Mettre à jour un contrat

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
}

Message de réponse

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
}

Informations d'identification

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

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

Obtenir des informations d’identification

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.

Demande HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Message de réponse

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

Rechercher des informations d’identification

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.

Demande HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

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

Révoquer des informations d’identification

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.

Demande HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

HTTP/1.1 204 No Content
Content-type: application/json

Annulation

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.

Demande HTTP

POST /v1.0/verifiableCredentials/optout

En-têtes de demande

En-tête	Valeur
Autorisation	Porteur (jeton). Obligatoire
Content-Type	application/json

Corps de la demande

Ne fournissez pas de corps de requête pour cette méthode.

Message de réponse

Exemple de message de réponse

HTTP/1.1 200 OK
Content-type: application/json

OK

Remarque

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

Partager via

API d’administration de vérification d’identité

URL de base

Authentification

Jetons du porteur d’utilisateur

Jetons du porteur d’application

Intégration

Demande HTTP

En-têtes de requête

Corps de la demande

Message de retour

Autorités

Méthodes

Obtenir l’autorité

Demande HTTP

En-têtes de requête

Corps de la demande

Message de réponse

Type d’autorité

Type de didModel

web

Type de keyVaultMetadata

Lister les autorités

Demande HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Créer une autorité

Requête HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Remarques

Mettre à jour une autorité

Demande HTTP

En-têtes de requête

Corps de la demande

Supprimer l’autorité

Requête HTTP

En-têtes de requête

Corps de la demande

Message de réponse

Configuration DID connue

Demande HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Remarques

Générer un document de DID

Demande HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Remarque

Valider une configuration DID connue

Demande HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Rotation de la clé de signature

Requête HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Synchroniser avec le document DID

Requête HTTP

En-têtes de demande

Corps de la demande

Message de réponse

Contrats

Méthodes

Obtenir un contrat

Demande HTTP

En-têtes de requête

Corps de la demande

Message de réponse

Type de contrat

type rulesModel

type d’attestations

type idTokenAttestation