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

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.blob.core.windows.net/public/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

Étapes suivantes

• Spécifier la requête d’émission de l’API REST du service de requête
• API Réseau de vérification d’identité Microsoft Entra