Partage via


Appeler l’API REST du service de requête

L’ID vérifié Microsoft Entra inclut l’API REST du service de requête. Cette API vous permet de émettre et de vérifier les informations d’identification. Cet article explique comment commencer à utiliser l’API REST du service de requête.

Jeton d’accès à l’API

Votre application doit inclure un jeton d’accès valide avec les autorisations requises afin qu’elle puisse accéder à l’API REST du service de requête. Les jetons d’accès émis par la plateforme d’identités Microsoft contiennent des informations (autorisations) que l’API REST de Request Service utilise pour valider la requête de l’appelant. Un jeton d’accès garantit que l’appelant dispose des autorisations appropriées pour effectuer l’opération qu’il demande.

Pour obtenir un jeton d’accès, votre application doit être inscrite auprès de la plateforme d’identités Microsoft et être autorisée par un administrateur pour accéder à l’API REST du service de requête. Si vous n’avez pas inscrit l’application verifiable-credentials-app, consultez comment inscrire l’application puis générer un secret d’application.

Obtenir un jeton d’accès

Utilisez le flux d’octroi des informations d'identification du client OAuth 2.0 pour acquérir le jeton d’accès à l’aide de la plateforme d'identités Microsoft. Utilisez une bibliothèque approuvée à cet effet. Dans ce tutoriel, nous utilisons la bibliothèque d’authentification Microsoft (MSAL). MSAL simplifie l’ajout d’authentification et d’autorisation à une application qui peut appeler une API web sécurisée.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Dans le code précédent, fournissez les paramètres suivants :

Paramètre Condition Description
Autorité Obligatoire Le locataire de l’annuaire sur lequel les plans d’application opèrent. Par exemple : https://login.microsoftonline.com/{your-tenant}. (Remplacez your-tenant par votre ID de locataire ou le nom.)
ID client Obligatoire ID d’application affecté à votre application. Vous trouverez ces informations dans le portail Azure, où vous avez inscrit votre application.
Clé secrète client Obligatoire Clé secrète client que vous avez générée pour votre application.
Étendues Obligatoire Cette propriété doit être définie sur 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Ce paramètre génère un jeton d’accès avec une revendication de rôle de VerifiableCredential.Create.All.

Pour plus d’informations sur l’obtention d’un jeton d’accès à l’aide de l’identité d’une application console, consultez l’un des articles suivants :

Vous pouvez également accéder à une requête de jeton avec un certificat au lieu d'une clé secrète client.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Appeler l’API

Pour émettre ou vérifier les justificatifs vérifiables :

  1. Créez une requête HTTP POST sur l’API REST du service de requête. L’ID de locataire n’est plus nécessaire dans l’URL, car il est présent sous la forme d’une revendication dans le jeton d’accès.

    Problème

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

    Vérifier

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Attachez le jeton d’accès en tant que jeton du porteur à l’en-tête d’autorisation dans une requête HTTP.

    Authorization: Bearer <token>
    
  3. Attribuez à l’en-tête Content-Type la valeur Application/json.

  4. Préparez et attachez la charge utile de requête Émissionou Présentation au corps de la demande.

  5. Envoyez la demande à l’API REST du service de requête.

L’API de service de requête retourne un code d’état HTTP 201 Created lors d’un appel réussi. Si l’appel d’API retourne une erreur, consultez la documentation de référence des erreurs .

Exemple de demande d’émission

L’exemple suivant illustre une demande d’émission de justificatifs vérifiables. Pour plus d’informations sur la charge utile, consultez Spécification de l’émission de l’API REST du service de requête.

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

{...JSON payload...}

Demande d’émission à l’aide du flux d’attestation idTokenHint :

{
    "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",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Pour obtenir le code complet, consultez l’un des exemples de code suivants :

Exemple de demande de présentation

L’exemple suivant illustre une demande de présentation de justificatifs vérifiables. Pour plus d’informations sur la charge utile, consultez Spécification de la présentation de l’API REST de Request Service.

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

{...JSON payload...}

Demande de présentation de données d'identification d'un certain type et émetteur :

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

Pour obtenir le code complet, consultez l’un des exemples de code suivants :

Événements de rappel

La charge utile de la demande contient le point de terminaison de rappel d’émission et de présentation. Le point de terminaison fait partie de votre application web et doit être disponible publiquement via le protocole HTTPS. L’API Request Service appelle votre point de terminaison pour informer votre application sur certains événements. Par exemple, de tels événements peuvent être lorsqu’un utilisateur analyse le code QR, utilise le lien profond vers l’application d’authentificateur ou termine le processus de présentation.

Le diagramme suivant décrit l’appel que votre application effectue à l’API REST du service de requête et les rappels à votre application.

Diagramme montrant l’appel à l’API et aux événements de rappel.

Configurez votre point de terminaison pour écouter les requêtes HTTP POST entrantes. L’extrait de code suivant montre comment gérer la requête HTTP de rappel d’émission et comment mettre à jour l’interface utilisateur en conséquence :

Sans objet. Choisissez l’un des autres langages de programmation.

Étapes suivantes

En savoir plus sur ces spécifications :