Specificatie van de REST API-presentatie van de service aanvragen

Artikel
02/07/2024

Microsoft Entra geverifieerde ID bevat de REST API van de aanvraagservice. Met deze API kunt u een referentie uitgeven en verifiëren. In dit artikel wordt de REST API van de aanvraagservice voor een presentatieaanvraag opgegeven. De presentatieaanvraag vraagt de gebruiker om een verifieerbare referentie te presenteren en controleer vervolgens de referentie. In een ander artikel wordt beschreven hoe u de REST API van de aanvraagservice aanroept.

HTTP-aanvraag

De request Service REST API-presentatieaanvraag ondersteunt de volgende HTTP-methode:

Methode	Opmerkingen
POSTEN	Met JSON-nettolading zoals opgegeven in dit artikel.

Voor de aanvraag voor de REST API-presentatieaanvraag van de aanvraagservice zijn de volgende HTTP-headers vereist:

Methode	Weergegeven als
`Authorization`	Koppel het toegangstoken als bearer-token aan de autorisatieheader in een HTTP-aanvraag. Bijvoorbeeld: `Authorization: Bearer <token>`.
`Content-Type`	`Application/json`

Maak een HTTP POST-aanvraag naar de REST API van de aanvraagservice. De tenantId is niet meer nodig in de URL omdat deze aanwezig is als een claim in de access_token.

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

De volgende HTTP-aanvraag demonstreert een presentatieaanvraag voor de REST API van de aanvraagservice:

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"
      }
    },
    ...
}

De volgende machtiging is vereist om de REST API van de aanvraagservice aan te roepen. Zie Machtigingen verlenen voor toegangstokens voor meer informatie.

Machtigingstype	Machtiging
Toepassing	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Nettolading van presentatieaanvraag

De nettolading van de presentatieaanvraag bevat informatie over uw verifieerbare referentiepresentatieaanvraag. In het volgende voorbeeld ziet u een presentatieaanvraag van een specifieke verlener. Het resultaat van deze aanvraag retourneert een QR-code met een koppeling om het presentatieproces te starten.

{
  "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
        }
      }
    }
  ]
}

De nettolading bevat de volgende eigenschappen.

Parameter	Type	Beschrijving
`includeQRCode`	Booleaanse waarde	Optioneel. Bepaalt of een QR-code is opgenomen in het antwoord van deze aanvraag. Presenteer de QR-code en vraag de gebruiker deze te scannen. Als u de QR-code scant, wordt de authenticator-app gestart met deze presentatieaanvraag. Mogelijke waarden zijn `true` (standaard) of `false`. Wanneer u de waarde `false`instelt, gebruikt u de eigenschap Return `url` om een dieptekoppeling weer te geven.
`includeReceipt`	Booleaanse waarde	Optioneel. Bepaalt of een ontvangstbewijs moet worden opgenomen in het antwoord van deze aanvraag. Mogelijke waarden zijn `true` of `false` (standaard). Het ontvangstbewijs bevat de oorspronkelijke nettolading die is verzonden van de verificator naar de Verifiable Credentials-service. Het ontvangstbewijs is handig voor het oplossen van problemen of als u de volledige details van de nettolading nodig hebt. U hoeft deze waarde anders niet standaard in te `true` stellen. In de `OpenId Connect SIOP` aanvraag bevat het ontvangstbewijs het id-token van de oorspronkelijke aanvraag.
`authority`	tekenreeks	Uw gedecentraliseerde id (DID) van uw Verifier Microsoft Entra-tenant. Zie Tenantgegevens verzamelen om uw voorbeeldtoepassing in te stellen voor meer informatie.
`registration`	RequestRegistration	Biedt informatie over de verificator.
`callback`	Callback	Verplicht. Hiermee kan de ontwikkelaar de gebruikersinterface bijwerken tijdens het verifieerbare referentiepresentatieproces. Wanneer de gebruiker het proces voltooit, gaat u door met het proces nadat de resultaten zijn geretourneerd naar de toepassing.
`requestedCredentials`	verzameling	Een verzameling RequestCredential-objecten .

Type aanvraagregister

Het RequestRegistration type biedt informatieregistratie voor de verlener. Het RequestRegistration type bevat de volgende eigenschappen:

Eigenschap	Type	Omschrijving
`clientName`	tekenreeks	Een weergavenaam van de verificator van de verifieerbare referentie. Deze naam wordt weergegeven aan de gebruiker in de verificator-app.
`purpose`	tekenreeks	Optioneel. Een tekenreeks die wordt weergegeven om de gebruiker te informeren waarom de verifieerbare referenties worden aangevraagd.
`logoUrl`	URL	Optioneel. Een URL voor een logotype van de verifier. Dit wordt niet gebruikt door de Authenticator-app.
`termsOfServiceUrl`	URL	Optioneel. Een URL naar de servicevoorwaarden voor de verifier. Dit wordt niet gebruikt door de Authenticator-app.

In de volgende schermopname ziet u de clientName eigenschap en de weergavenaam van de authority (de verifier) in de presentatieaanvraag.

Schermopname van het goedkeuren van de presentatieaanvraag.

Type callback

De REST API van de aanvraagservice genereert verschillende gebeurtenissen naar het callback-eindpunt. Met deze gebeurtenissen kunt u de gebruikersinterface bijwerken en doorgaan met het proces nadat de resultaten zijn geretourneerd naar de toepassing. Het Callback type bevat de volgende eigenschappen:

Eigenschap	Type	Omschrijving
`url`	tekenreeks	URI naar het callback-eindpunt van uw toepassing. De URI moet verwijzen naar een bereikbaar eindpunt op internet, anders genereert de service een onleesbare callback-URL. Geaccepteerde IPv4-, IPv6- of DNS-omzetbare hostnaam.
`state`	tekenreeks	Correleert de callback-gebeurtenis met de status die is doorgegeven in de oorspronkelijke nettolading.
`headers`	tekenreeks	Optioneel. U kunt een verzameling HTTP-headers opnemen die vereist zijn voor het ontvangende einde van het POST-bericht. De huidige ondersteunde headerwaarden zijn de `api-key` of de `Authorization` headers. Elke andere header genereert een ongeldige callback-headerfout.

RequestCredential-type

De RequestCredential informatie bevat informatie over de aangevraagde referenties die de gebruiker moet opgeven. RequestCredential bevat de volgende eigenschappen:

Eigenschap	Type	Omschrijving
`type`	tekenreeks	Het verifieerbare referentietype. Het `type` moet overeenkomen met het type zoals gedefinieerd in het `issuer` verifieerbare referentiemanifest (bijvoorbeeld `VerifiedCredentialExpert`). Zie Referenties en omgevingsgegevens verzamelen om uw voorbeeldtoepassing in te stellen om het manifest van de verlener op te halen. Kopieer de referentie-URL van het probleem, open deze in een webbrowser en controleer de id-eigenschap.
`purpose`	tekenreeks	Optioneel. Geef informatie op over het doel van het aanvragen van deze verifieerbare referentie. Dit wordt niet gebruikt door de Authenticator-app.
`acceptedIssuers`	tekenreeksverzameling	Optioneel. Een verzameling did's van verleners die het type verifieerbare referentie kunnen uitgeven dat onderwerpen kunnen presenteren. Zie Referenties en omgevingsgegevens verzamelen om uw voorbeeldtoepassing in te stellen en de waarde van de gedecentraliseerde id (DID) te kopiëren om uw verlener DID op te halen. Als de `acceptedIssuers` verzameling leeg is of niet aanwezig is, accepteert de presentatieaanvraag een referentietype dat is uitgegeven door een verlener.
`configuration.validation`	Configuration.Validation	Optionele instellingen voor presentatievalidatie.
`constraints`	Beperkingen	Optioneel. Verzameling van claimsbeperkingen.

Configuration.Validation-type

De Configuration.Validation informatie bevat informatie over hoe de gepresenteerde referenties moeten worden gevalideerd. Deze bevat de volgende eigenschappen:

Eigenschap	Type	Beschrijving
`allowRevoked`	Booleaanse waarde	Optioneel. Bepaalt of een ingetrokken referentie moet worden geaccepteerd. De standaardwaarde is `false` (deze mag niet worden geaccepteerd).
`validateLinkedDomain`	Booleaanse waarde	Optioneel. Bepaalt of het gekoppelde domein moet worden gevalideerd. Standaard is `false`. Als u deze vlag instelt, `false` betekent dit dat u als een Relying Party-toepassing referenties van een niet-geverifieerd gekoppeld domein accepteert. Als u deze vlag instelt, `true` wordt het gekoppelde domein gevalideerd en worden alleen geverifieerde domeinen geaccepteerd.
`faceCheck`	faceCheck	Optioneel. Hiermee kunt u een livenesscontrole aanvragen tijdens de presentatie.

Type beperkingen

Het constraints type bevat een verzameling claimsbeperkingen waaraan moet worden voldaan wanneer een portemonnee de kandidaatreferenties selecteert. Hiermee kunt u een referentie aanvragen met een specifieke claimwaarde. Opgegeven beperkingen gebruiken de AND-logica, bijvoorbeeld als u drie beperkingen opgeeft, moet aan alle beperkingen worden voldaan. Voor elke beperking in de verzameling moet u één operand met waarden selecteren, bevat of startsWith. Waarden kunnen geen reguliere expressies zijn. Alle vergelijkingen zijn hoofdlettergevoelig.

Eigenschap	Type	Omschrijving
`claimName`	tekenreeks	Verplicht. Naam van de claim voor de beperking. Dit is de claimnaam in de verifieerbare referentie. Zie outputClaim in claimMapping type.
`values`	tekenreeksverzameling	Set waarden die overeenkomen met de claimwaarde. Als u meerdere waarden opgeeft, zoals ["rood", "groen", "blauw"] is het een overeenkomst als de claimwaarde in de referentie een van de waarden in de verzameling heeft.
`contains`	tekenreeks	De beperking resulteert in waar als de claimwaarde de opgegeven waarde bevat.
`startsWith`	tekenreeks	De beperking resulteert in waar als de claimwaarde begint met de opgegeven waarde.

type faceCheck

Het type faceCheck bevat informatie voor het uitvoeren van een livenesscontrole tijdens de presentatie van een referentie. De gevraagde referentie moet een foto van de houder bevatten in de claim met de naam sourcePhotoClaimName. De presentatie slaagt als de betrouwbaarheidscontrole een betrouwbaarheidsniveau bereikt dat gelijk is aan of groter is dan wat is opgegeven in de eigenschap matchConfidenceThreshold. Als niet aan de drempelwaarde wordt voldaan, mislukt de hele presentatie.

Eigenschap	Type	Omschrijving
`sourcePhotoClaimName`	tekenreeks	Verplicht. De naam van de claim in de referentie die de foto bevat. Zie outputClaim in claimMapping type.
`matchConfidenceThreshold`	geheel getal	Optioneel. De vertrouwelijke drempelwaarde voor een geslaagde controle tussen de foto en de livenessgegevens. Moet een geheel getal tussen 50 en 100 zijn. De standaardwaarde is 70.

Succesvolle respons

Als dit lukt, retourneert deze methode een antwoordcode (HTTP 201 Created) en een verzameling gebeurtenisobjecten in de hoofdtekst van het antwoord. In de volgende JSON ziet u een geslaagd antwoord:

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

Het antwoord bevat de volgende eigenschappen:

Eigenschap	Type	Omschrijving
`requestId`	tekenreeks	Een automatisch gegenereerde aanvraag-id. De callback maakt gebruik van dezelfde aanvraag, zodat u de presentatieaanvraag en de bijbehorende callbacks kunt bijhouden.
`url`	tekenreeks	Een URL waarmee de verificator-app wordt gestart en het presentatieproces wordt gestart. U kunt deze URL aan de gebruiker presenteren als ze de QR-code niet kunnen scannen.
`expiry`	geheel getal	Geeft aan wanneer het antwoord verloopt.
`qrCode`	tekenreeks	Een QR-code die de gebruiker kan scannen om de presentatiestroom te starten.

Wanneer uw app het antwoord ontvangt, moet de app de QR-code aan de gebruiker presenteren. De gebruiker scant de QR-code, waarmee de verificator-app wordt geopend en het presentatieproces wordt gestart.

Foutrespons

Als er een fout optreedt met de aanvraag, worden er foutberichten geretourneerd en moet deze op de juiste wijze worden verwerkt door de app.

Callback-gebeurtenissen

Het callback-eindpunt wordt aangeroepen wanneer een gebruiker de QR-code scant, de deep link van de authenticator-app gebruikt of het presentatieproces voltooit.

Eigenschap	Type	Omschrijving
`requestId`	tekenreeks	Toegewezen aan de oorspronkelijke aanvraag toen de nettolading werd gepost naar de verifiable Credentials-service.
`requestStatus`	tekenreeks	De status die is geretourneerd toen de aanvraag werd opgehaald door de verificator-app. Mogelijke waarden: `request_retrieved`: De gebruiker heeft de QR-code gescand of de koppeling geselecteerd waarmee de presentatiestroom wordt gestart. `presentation_verified`: De verifieerbare referentievalidatie is voltooid. Li>`presentation_error`: Er is een fout opgetreden in de presentatie.
`state`	tekenreeks	Retourneert de statuswaarde die u hebt doorgegeven in de oorspronkelijke nettolading.
`subject`	tekenreeks	De verifieerbare referentiegebruiker DEED.
`verifiedCredentialsData`	matrix	Retourneert een matrix met verifieerbare referenties die zijn aangevraagd. Voor elke verifieerbare referentie biedt deze: Het verifieerbare referentietype(en). De DID van de verlener De claims die zijn opgehaald. Het domein van de verifieerbare referentieverlener. De verifieerbare status van de domeinvalidatie van de verlener van referenties.
`receipt`	tekenreeks	Optioneel. Het ontvangstbewijs bevat de oorspronkelijke nettolading die van de portemonnee naar de Verifiable Credentials-service is verzonden. Het ontvangstbewijs moet alleen worden gebruikt voor probleemoplossing/foutopsporing. De notatie in het ontvangstbewijs is niet opgelost en kan worden gewijzigd op basis van de gebruikte portemonnee en versie.

In het volgende voorbeeld ziet u een callback-nettolading wanneer de authenticator-app de presentatieaanvraag start:

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

In het volgende voorbeeld ziet u een callback-nettolading nadat de verifieerbare referentiepresentatie is voltooid:

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

Volgende stappen

Meer informatie over het aanroepen van de REST API van de aanvraagservice.

Delen via