Spécification d’émission de l’API REST du service de requête

Article
03/04/2024

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 d’émission. Un autre article explique comment appeler l’API REST du service de requête.

Demande HTTP

La demande d’émission 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 d’émission de l’API REST du service de demande nécessite les en-têtes HTTP suivants :

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

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

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

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

{
    "includeQRCode": true,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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 d’émission

La charge utile de la demande d’émission contient des informations sur votre demande d’émission de justificatifs vérifiables. L’exemple suivant montre une demande d’émission effectuée en utilisant un flux de code confidentiel avec des revendications d’utilisateur, telles que le prénom et le nom. Le résultat de cette requête renvoie un code QR avec un lien pour démarrer le processus d’émission.

{
  "includeQRCode": false,
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

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

Paramètre	Type	Description
`includeQRCode`	Boolean	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. Le scan du code QR lance l’application d’authentification avec cette demande d’émission. 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.
`callback`	Callback	Mandatory. Permet au développeur d’obtenir de façon asynchrone des informations sur le flux pendant le processus d’émission de justificatifs vérifiables. Par exemple, le développeur peut souhaiter un appel si l’utilisateur a scanné le code QR, ou si la demande d’émission a réussi ou échoué.
`authority`	chaîne	Identificateur décentralisé de l’émetteur (DID). Pour plus d’informations, consultez Collecter les informations d’identification et les détails de l’environnement pour configurer votre exemple d’application.
`registration`	RequestRegistration	Fournit des informations sur l’émetteur qui peuvent être affichées dans l’application d’authentification.
`type`	string	Type de justificatifs vérifiables. Doit correspondre au type défini dans le manifeste des justificatifs vérifiables. Par exemple : `VerifiedCredentialExpert`. Pour plus d’informations, consultez Créer la carte d’expert en justificatifs vérifiés dans Azure.
`manifest`	string	URL du document manifeste des justificatifs vérifiables. Pour plus d’informations, consultez Collecter les informations d’identification et les détails de l’environnement pour configurer votre exemple d’application.
`claims`	string	facultatif. Peut uniquement être utilisé pour le flux d’attestation d’indicateur de jeton d’ID afin d’inclure une collection d’assertions effectuées sur le sujet dans les justificatifs vérifiables.
`pin`	PIN	facultatif. Le code PIN ne peut servir qu’avec le flux d’attestation de l’indicateur de jeton d’ID. Numéro de code confidentiel pour fournir une sécurité supplémentaire lors de l’émission. Vous générez un code confidentiel et le présentez à l’utilisateur dans votre application. L’utilisateur doit fournir le code confidentiel que vous avez généré.
`expirationDate`	string	facultatif. L’expirationDate ne peut servir qu’avec le flux d’attestation de l’indicateur de jeton d’ID. Si elle est spécifiée, la valeur doit être une date exprimée au format ISO8601. La date remplace la validitéInterval dans la définition des règles d’identification pour cette demande d’émission. Utilisez ce paramètre pour contrôler explicitement lorsque des informations d’identification expirent, telles que la fin du jour, la fin du mois ou la fin de l’année, quel que soit le moment où elles sont émises. Notez que la date est exprimée au format UTC. Si vous spécifiez la fin de l’année, avec l’heure définie sur `23:59:59`, soit 1 seconde à minuit en heure UTC. Tout utilisateur d’un fuseau horaire différent obtient la date d’expiration présentée dans le fuseau horaire local dans Microsoft Authenticator. Cela signifie que si vous êtes dans le fuseau horaire CET, il sera présenté comme 1er janvier 1h00. Le contrat d’informations d’identification doit avoir l’indicateur allowOverrideValidityOnIssuance défini sur true.

Il existe actuellement quatre types d’attestations de revendications que vous pouvez envoyer dans la charge utile. La vérification de l'identité Microsoft Entra utilise quatre façons d’insérer des revendications dans des justificatifs vérifiables et d’attester de ces informations avec le DID de l’émetteur. Les quatre types sont les suivants :

Jeton d’ID
Indicateur de jeton d’ID
Informations d’identification vérifiables via une présentation vérifiable.
Revendications attestées automatiquement

Pour des informations détaillées sur les types d’entrée, consultez Personnalisation de vos justificatifs vérifiables.

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 de l’émetteur des justificatifs vérifiables.
`logoUrl`	string	facultatif. URL du logo de l’émetteur.
`termsOfServiceUrl`	string	facultatif. URL des Conditions d’utilisation des justificatifs vérifiables que vous émettez.

Notes

À ce stade, les informations RequestRegistration ne sont pas présentées lors de l’émission de l’application Microsoft Authenticator. Toutefois, ces informations peuvent être utilisées dans la charge utile.

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. Formats acceptés : IPv4, IPv6 ou nom d’hôte résolvable DNS.
`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 `Authorization`. Tout autre en-tête générera une erreur d’en-tête de rappel non valide

Épingler un type

Le pin type définit un code confidentiel qui peut être affiché dans le cadre de l’émission. pin est facultatif et, s’il est utilisé, doit toujours être envoyé hors bande. Lorsque vous utilisez un code confidentiel de hachage, vous devez définir les propriétés salt, alg et iterations. pin contient les propriétés suivantes :

Propriété	Type	Description
`value`	string	Contient la valeur de code confidentiel en texte brut. Lors de l’utilisation d’un code confidentiel haché, la propriété value contient le code de hachage salé, codé en base64.
`type`	chaîne	Type du code confidentiel. Valeur possible : `numeric` (par défaut).
`length`	entier	Longueur du code confidentiel. La longueur par défaut est 6, la longueur minimale est 4 et la longueur maximale est 16.
`salt`	chaîne	Sel du code confidentiel haché. Le sel est ajouté au début du calcul du code de hachage. Encodage : UTF-8.
`alg`	string	Algorithme de hachage pour le code confidentiel haché. Algorithme pris en charge : `sha256`.
`iterations`	entier	Nombre d’itérations de hachage. Valeur possible : `1`.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 d’émission et de ses rappels.
`url`	string	URL qui lance l’application d’authentification et démarre le processus d’émission. 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 processus d’émission.

Lorsque votre application reçoit la réponse, l’application doit présenter le code QR à l’utilisateur. L’utilisateur scanne le code QR, ce qui a pour effet d’ouvrir l’application d’authentification et de démarrer le processus d’émission.

Réponse d’erreur

S’il existe une erreur de requête, une réponse à l’erreur est retournée et 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 l’application d’authentification ou termine le processus d’émission.

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 retourné pour la requête. Valeurs possibles : `request_retrieved` : l’utilisateur a scanné le code QR ou sélectionné le lien qui démarre le flux d’émission. `issuance_successful` : l’émission des justificatifs vérifiables a réussi. `issuance_error` : une erreur s’est produite pendant l’émission. Pour plus d'informations, consultez la propriété `error`.
`state`	chaîne	Renvoie la valeur d’état que vous avez transmise dans la charge utile d’origine.
`error`	error	Lorsque la valeur de la propriété `code` est `issuance_error`, cette propriété contient des informations sur l’erreur.
`error.code`	string	Code d’erreur de retour.
`error.message`	string	Message d’erreur.

L’exemple suivant illustre une charge utile de rappel quand l’application d’authentification démarre la demande d’émission :

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

L’exemple suivant illustre une charge utile de rappel une fois que l’utilisateur a terminé le processus d’émission :

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Erreurs de rappel

Le point de terminaison de rappel peut être appelé avec un message d’erreur. Le tableau suivant répertorie les codes d’erreur :

Message	Définition
`fetch_contract_error`	Impossible de récupérer le contrat de justificatifs vérifiables. Cette erreur se produit généralement lorsque l’API ne parvient pas à extraire le manifeste que vous spécifiez dans l’objet RequestIssuance de la charge utile de la demande.
`issuance_service_error`	Le service des informations d’identification vérifiables n’est pas en mesure de valider les exigences, ou une erreur s’est produite dans les informations d’identification vérifiables.
`unspecified_error`	Cette erreur est rare mais mérite une investigation.

L’exemple suivant illustre une charge utile de rappel lorsqu’une erreur s’est produite :

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
}

Étapes suivantes

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