Spécification de la présentation de l’API REST du service de requête

Article
11/30/2023

Vérification d’identité Microsoft Entra inclut l’API REST du service de requête. Cette API vous permet d’émettre et de vérifier des informations d’identification. Cet article spécifie l’API REST du service de demande pour une demande de présentation. La demande de présentation invite l’utilisateur à présenter des justificatifs vérifiables, puis à vérifier les informations d'identification. Un autre article explique comment appeler l’API REST du service de requête.

Demande HTTP

La demande de présentation de l’API REST du service de demande prend en charge la méthode HTTP suivante :

Méthode	Notes
POST	Avec la charge utile JSON spécifiée dans cet article.

La demande de présentation de l’API REST du service de demande requiert les en-têtes HTTP suivants :

Méthode	Valeur
`Authorization`	Attachez le jeton d’accès comme jeton du porteur à l’en-tête d’autorisation dans une requête HTTP. Par exemple : `Authorization: Bearer <token>`.
`Content-Type`	`Application/json`

Construisez une requête HTTP POST adressée à l’API REST du service de demande. Le tenantId n’est plus nécessaire dans l’URL, car il est présent sous la forme d’une revendication dans le access_token.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

La requête HTTP suivante montre une demande de présentation adressée à l’API REST du service de demande :

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "includeQRCode": true,
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

L’autorisation suivante est requise pour appeler l’API REST du service de demande. Pour plus d’informations, consultez Accorder des autorisations pour obtenir des jetons d’accès.

Type d'autorisation	Autorisation
Application	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Charge utile de la demande de présentation

La charge utile de la demande de présentation contient des informations sur votre demande de présentation de justificatifs vérifiables. L’exemple suivant montre une demande de présentation d’un émetteur spécifique. Le résultat de cette demande retourne un code QR avec un lien pour démarrer le processus de présentation.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

La charge utile contient les propriétés suivantes.

Paramètre	Type	Description
`includeQRCode`	Boolean	Optionnel. Détermine si un code QR est inclus dans la réponse de cette demande. Présentez le code QR et demandez à l’utilisateur de le scanner. L’analyse du code QR lance l’application d’authentification avec cette demande de présentation. Les valeurs possibles sont `true` (par défaut) ou `false`. Lorsque vous définissez la valeur sur `false`, utilisez la propriété `url` de retour pour afficher un lien profond.
`includeReceipt`	Boolean	Optionnel. Détermine si un accusé de réception doit être inclus dans la réponse de cette demande. Les valeurs possibles sont `true` ou `false`(par défaut). L’accusé de réception contient la charge utile d’origine envoyée de l’authentificateur au service des justificatifs vérifiables. Le reçu est utile pour la résolution des problèmes ou si vous avez besoin d’obtenir les détails complets de la charge utile. Autrement il n’est pas nécessaire de définir cette valeur `true` par défaut. Dans la demande `OpenId Connect SIOP`, l’accusé de réception contient le jeton d’ID de la demande d’origine.
`authority`	string	Votre identifiant décentralisé (DID) de votre locataire Microsoft Entra vérificateur. Pour plus d’informations, consultez Rassembler les détails du locataire pour configurer votre exemple d’application.
`registration`	RequestRegistration	Fournit des informations sur le vérificateur.
`callback`	Callback	Mandatory. Permet au développeur de mettre à jour l’interface utilisateur pendant le processus de présentation des justificatifs vérifiables. Quand l’utilisateur termine le processus, poursuivez le processus une fois les résultats retournés à l’application.
`requestedCredentials`	collection	Collection d’objets RequestCredential.

Type RequestRegistration

Le type RequestRegistration fournit l’inscription des informations pour l’émetteur. Le type RequestRegistration contient les propriétés suivantes :

Propriété	Type	Description
`clientName`	string	Nom complet du vérificateur des justificatifs vérifiables. Ce nom sera présenté à l’utilisateur dans l’application d’authentification.
`purpose`	string	facultatif. Chaîne affichée pour informer l’utilisateur de la raison pour laquelle des informations d’identification vérifiables sont demandées.
`logoUrl`	URL	Optionnel. URL d’un logotype du vérificateur. Il n’est pas utilisé par l’application Authenticator.
`termsOfServiceUrl`	URL	Optionnel. URL des conditions d’utilisation du vérificateur. Il n’est pas utilisé par l’application Authenticator.

La capture d’écran suivante montre la propriété clientName et le nom d’affichage de l’authority (le vérificateur) dans la demande de présentation.

Capture d’écran montrant comment approuver la demande de présentation.

Type de rappel

L’API REST du service de demande génère plusieurs événements pour le point de terminaison de rappel. Ces événements vous permettent de mettre à jour l’interface utilisateur et de poursuivre le processus une fois que les résultats sont renvoyés à l’application. Le type Callback contient les propriétés suivantes :

Propriété	Type	Description
`url`	string	URI du point de terminaison de rappel de votre application. L’URI doit pointer vers un point de terminaison accessible sur Internet. Sinon, le service déclenchera une erreur d’URL de rappel non lisible. Entrées acceptées IPv4, IPv6 ou nom d’hôte pouvant être résolu.
`state`	string	Met en corrélation l’événement de rappel avec l’état passé dans la charge utile d’origine.
`headers`	string	facultatif. Vous pouvez inclure une collection d’en-têtes HTTP requis par le destinataire du message POST. Les valeurs d'en-tête actuellement prises en charge sont les en-têtes `api-key`ou les `Authorization`en-têtes. Tout autre en-tête génère une erreur d’en-tête de rappel non valide.

Type RequestCredential

RequestCredential fournit des informations sur les informations d’identification demandées que l’utilisateur doit fournir. RequestCredential contient les propriétés suivantes :

Propriété	Type	Description
`type`	string	Type de justificatifs vérifiables. Le `type` doit correspondre au type défini dans le manifeste des justificatifs vérifiables `issuer` (par exemple, `VerifiedCredentialExpert`). Pour obtenir le manifeste de l’émetteur, consultez Collecter les justificatifs et les détails de l’environnement pour configurer votre exemple d’application. Copiez l’URL des informations d’identification du problème, ouvrez-la dans un navigateur web, puis vérifiez la propriété ID.
`purpose`	string	facultatif. Fournissez des informations sur l’objectif de la demande de ces justificatifs vérifiables. Il n’est pas utilisé par l’application Authenticator.
`acceptedIssuers`	collection de chaînes	facultatif. Collection d’identificateurs décentralisés (DID) d’émetteurs qui pourraient émettre le type de justificatifs vérifiables que les sujets peuvent présenter. Pour obtenir votre DID d’émetteur, consultez Collecter les justificatifs et les détails de l’environnement pour configurer votre exemple d’application, puis copiez la valeur du DID. Si la collection `acceptedIssuers` est vide ou absente, la demande de présentation accepte un type d’informations d’identification émis par n’importe quel émetteur.
`configuration.validation`	Configuration.Validation	Paramètres facultatifs pour la validation de présentation.
`constraints`	Contraintes	facultatif. Collection de contraintes de revendications.

Type Configuration.Validation

Configuration.Validation fournit des informations sur les informations d’identification présentées qui doivent être validées. Il contient les propriétés suivantes :

Propriété	Type	Description
`allowRevoked`	Boolean	Optionnel. Détermine si des informations d’identification révoquées doivent être acceptées. La valeur par défaut est `false` (elles ne doivent pas être acceptées).
`validateLinkedDomain`	Boolean	Optionnel. Détermine si le domaine lié doit être validé. La valeur par défaut est `false`. La définition de cet indicateur sur `false` signifie qu’en tant qu’application par partie de confiance, vous acceptez les informations d’identification d’un domaine lié non vérifié. Définir cet indicateur sur `true` signifie que le domaine lié sera validé et que seuls les domaines vérifiés seront acceptés.
`faceCheck`	faceCheck	facultatif. Autorise la demande d’une vérification de liveness pendant la présentation.

Type de contraintes

Le type constraints contient une collection de contraintes de revendications qui doivent être remplies lorsqu’un portefeuille sélectionne les informations d’identification du candidat. Cela permet de demander des informations d’identification avec une valeur de revendication spécifique. Les contraintes spécifiées utilisent la logique ET, ce qui signifie que si vous spécifiez trois contraintes, toutes doivent être remplies. Pour chaque contrainte de la collection, vous devez sélectionner un opérande de valeurs, contains ou startWith. Les valeurs ne peuvent pas être des expressions régulières. Aucune comparaison n’est sensible à la casse.

Propriété	Type	Description
`claimName`	string	Obligatoire. Nom de la revendication pour la contrainte. Il s’agit du nom de la revendication dans les justificatifs vérifiables. Consultez outputClaim dans le type claimMapping.
`values`	collection de chaînes	Ensemble de valeurs qui doivent correspondre à la valeur de la revendication. Si vous spécifiez plusieurs valeurs, telles que ["red", "green", "blue"], une correspondance est trouvée si la valeur de la revendication dans les informations d’identification contient l’une des valeurs de la collection.
`contains`	string	La contrainte prend la valeur true si la valeur de la revendication contient la valeur spécifiée.
`startsWith`	string	La contrainte prend la valeur true si la valeur de revendication commence par la valeur spécifiée.

Type faceCheck

Le type faceCheck contient des informations permettant d’effectuer une vérification de liveness pendant la présentation d’informations d’identification. Les informations d’identification demandées doivent contenir une photo du titulaire dans la revendication nommée par sourcePhotoClaimName. La présentation réussit si la vérification de liveness atteint un niveau de confiance égal ou supérieur à ce qui est spécifié dans la propriété matchConfidenceThreshold. Si le seuil n’est pas atteint, la présentation entière échoue.

Propriété	Type	Description
`sourcePhotoClaimName`	string	Mandatory. Nom de la revendication dans les informations d’identification contenant la photo. Consultez outputClaim dans le type claimMapping.
`matchConfidenceThreshold`	entier	facultatif. Seuil de confiance à atteindre pour une vérification réussie entre la photo et les données de liveness. Doit être un entier compris entre 50 et 100. La valeur par défaut est 70.

Réponse correcte

En cas de réussite, cette méthode renvoie un code de réponse (HTTP 201 Créé) et une collection d’objets d’événement dans le corps de la réponse. Le code JSON suivant illustre une réponse réussie :

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

La réponse contient les propriétés suivantes :

Propriété	Type	Description
`requestId`	string	ID de demande généré automatiquement. Le rappel utilisant la même demande, vous pouvez garder une trace de la demande de présentation et de ses rappels.
`url`	string	URL qui lance l’application d’authentification et démarre le processus de présentation. Vous pouvez présenter cette URL à l’utilisateur s’il ne parvient pas à scanner le code QR.
`expiry`	entier	Indique quand la réponse expire.
`qrCode`	string	Code QR que l’utilisateur peut scanner pour démarrer le flux de présentation.

Lorsque votre application reçoit la réponse, l’application doit présenter le code QR à l’utilisateur. L’utilisateur scanne le code QR, qui ouvre l’application d’authentification et démarre le processus de présentation.

Réponse d’erreur

S’il y a une erreur avec la requête, une réponse d’erreur est retournée, et elle doit être gérée de manière appropriée par l’application.

Événements de rappel

Le point de terminaison de rappel est appelé quand un utilisateur scanne le code QR, utilise le lien profond avec son application d’authentification ou termine le processus de présentation.

Propriété	Type	Description
`requestId`	string	Mappé à la demande d’origine lorsque la charge utile a été publiée sur le service Justificatifs vérifiables.
`requestStatus`	string	État renvoyé lorsque la demande a été récupérée par l’application d’authentification. Valeurs possibles : `request_retrieved` : L’utilisateur a scanné le code QR ou sélectionné le lien qui démarre le processus de présentation. `presentation_verified` : La validation des justificatifs vérifiables s’est correctement déroulée. li>`presentation_error` : une erreur s’est produite dans la présentation.
`state`	string	Renvoie la valeur d’état que vous avez transmise dans la charge utile d’origine.
`subject`	string	DID d’utilisateur des justificatifs vérifiables.
`verifiedCredentialsData`	tableau	Retourne un tableau de justificatifs vérifiables demandés. Pour chacun des justificatifs vérifiables, elle fournit les éléments suivants : Les type(s) de justificatifs vérifiables. Le DID de l’émetteur. Revendications récupérées. Le domaine de l’émetteur des justificatifs vérifiables. L’état de validation du domaine de l’émetteur des justificatifs vérifiables.
`receipt`	string	facultatif. L’accusé de réception contient la charge utile d’origine envoyée du portefeuille au service des justificatifs vérifiables. Le reçu doit être utilisé uniquement pour le dépannage et le débogage. Le format du reçu n’est pas fixe et peut changer en fonction du portefeuille et de la version utilisés.

L’exemple suivant illustre une charge utile de rappel lorsque l’application de l’authentificateur démarre la demande de présentation :

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

L’exemple suivant illustre une charge utile de rappel après la réussite de la présentation des justificatifs vérifiables :

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

Étapes suivantes

Découvrez comment appeler de l’API REST du service de demande.