Lire en anglais

Partager via


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

Étapes suivantes