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

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 :

La demande d’émission de l’API REST du service de demande nécessite les en-têtes HTTP suivants :

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>

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

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.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/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 :

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 :

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 :

É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 :

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/00001111-aaaa-2222-bbbb-3333cccc4444/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 :

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.

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 :

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.