Rest API-uitgiftespecificatie van aanvraagservice

Artikel
12/07/2023

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 voor aanvraagservice voor een uitgifteaanvraag opgegeven. In een ander artikel wordt beschreven hoe u de REST API van de aanvraagservice aanroept.

HTTP-aanvraag

De REST API-uitgifteaanvraag van de aanvraagservice ondersteunt de volgende HTTP-methode:

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

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

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

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

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

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

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 uitgifteaanvraag

De nettolading van de uitgifteaanvraag bevat informatie over uw verifieerbare referentieuitgifteaanvraag. In het volgende voorbeeld ziet u een uitgifteaanvraag met behulp van een pincodecodestroom met gebruikersclaims, zoals voornaam en achternaam. Het resultaat van deze aanvraag retourneert een QR-code met een koppeling om het uitgifteproces te starten.

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

De payload bevat de volgende eigenschappen:

Parameter	Type	Beschrijving
`includeQRCode`	Booleaanse waarde	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 uitgifteaanvraag. 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.
`callback`	Callback	Verplicht. Hiermee kan de ontwikkelaar asynchroon informatie over de stroom ophalen tijdens het verifieerbare referentieuitgifteproces. De ontwikkelaar kan bijvoorbeeld een aanroep willen wanneer de gebruiker de QR-code heeft gescand of als de uitgifteaanvraag slaagt of mislukt.
`authority`	tekenreeks	De gedecentraliseerde id (DID) van de verlener. Zie Referenties en omgevingsgegevens verzamelen om uw voorbeeldtoepassing in te stellen voor meer informatie.
`registration`	RequestRegistration	Biedt informatie over de verlener die kan worden weergegeven in de verificator-app.
`type`	tekenreeks	Het verifieerbare referentietype. Moet overeenkomen met het type zoals gedefinieerd in het verifieerbare referentiemanifest. Voorbeeld: `VerifiedCredentialExpert`. Zie De geverifieerde referentie-expertkaart maken in Azure voor meer informatie.
`manifest`	tekenreeks	De URL van het verifieerbare referentiemanifestdocument. Zie Referenties en omgevingsgegevens verzamelen om uw voorbeeldtoepassing in te stellen voor meer informatie.
`claims`	tekenreeks	Optioneel. Kan alleen worden gebruikt voor de attestation-stroom voor id-tokenhints om een verzameling asserties over het onderwerp op te nemen in de verifieerbare referentie.
`pin`	PIN	Optioneel. Pincode kan alleen worden gebruikt met de attestation-stroom id-tokenhint . Een pincodenummer om extra beveiliging te bieden tijdens uitgifte. U genereert een pincode en presenteert deze aan de gebruiker in uw app. De gebruiker moet de pincode opgeven die u hebt gegenereerd.
`expirationDate`	tekenreeks	Optioneel. De vervaldatum kan alleen worden gebruikt met de attestation-attestation-stroom id-tokenhint . Indien opgegeven, moet de waarde een datum zijn die wordt uitgedrukt in de indeling ISO8601 . De datum overschrijft de geldigheidsinterval in de definitie van de referentieregels voor deze uitgifteaanvraag. Gebruik deze instelling om expliciet te bepalen wanneer een referentie verloopt, zoals het einde van de dag, het einde van de maand of het einde van het jaar, ongeacht wanneer deze is uitgegeven. Houd er rekening mee dat de datum wordt uitgedrukt in DE UTC-indeling. Als u het einde van het jaar opgeeft, waarbij de tijd is ingesteld op `23:59:59`, is dat 1 seconde tot middernacht in utc-tijd. Elke gebruiker in een andere tijdzone krijgt de vervaldatum die wordt weergegeven in de lokale tijdzone in Microsoft Authenticator. Dit betekent dat als u zich in de CET-tijdzone bevindt, het wordt gepresenteerd als 1 januari 11:00 uur. Voor het referentiecontract moet de vlag allowOverrideValidityOnIssuance zijn ingesteld op true.

Er zijn momenteel vier typen claims attestation die u in de nettolading kunt verzenden. Microsoft Entra geverifieerde ID gebruikt vier manieren om claims in te voegen in een verifieerbare referentie en deze informatie te bevestigen met de DID van de verlener. Hier volgen de vier typen:

Id-token
ID-tokenhint
Verifieerbare referenties via een verifieerbare presentatie
Zelf-geteste claims

Gedetailleerde informatie over de invoertypen vindt u in Het aanpassen van uw verifieerbare referentie.

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 uitgever van de verifieerbare referentie.
`logoUrl`	tekenreeks	Optioneel. De URL voor het logo van de verlener.
`termsOfServiceUrl`	tekenreeks	Optioneel. De URL voor de gebruiksvoorwaarden van de verifieerbare referentie die u uitgeeft.

Notitie

Op dit moment wordt de RequestRegistration informatie niet weergegeven tijdens de uitgifte in de Microsoft Authenticator-app. Deze informatie kan echter worden gebruikt in de nettolading.

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 indelingen 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

Type speld

Het pin type definieert een pincode die kan worden weergegeven als onderdeel van de uitgifte. pin is optioneel en, indien gebruikt, moet altijd buiten de band worden verzonden. Wanneer u een HASH-pincodecode gebruikt, moet u de salteigenschappen en algiterations eigenschappen definiëren. pin bevat de volgende eigenschappen:

Eigenschap	Type	Omschrijving
`value`	tekenreeks	Bevat de pincodewaarde in tekst zonder opmaak. Wanneer u een hash-pincode gebruikt, bevat de waarde-eigenschap de gezouten hash, base64 gecodeerd.
`type`	tekenreeks	Het type pincode. Mogelijke waarde: `numeric` (standaard).
`length`	geheel getal	De lengte van de pincode. De standaardlengte is 6, het minimum is 4 en het maximum is 16.
`salt`	tekenreeks	Het zout van de gehashte pincodecode. Het zout wordt voorafgegaan tijdens de hashberekening. Codering: UTF-8.
`alg`	tekenreeks	Het hash-algoritme voor de gehashte pincode. Ondersteund algoritme: `sha256`.
`iterations`	geheel getal	Het aantal hash-iteraties. Mogelijke waarde: `1`.

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

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 uitgifteaanvraag en de bijbehorende callbacks kunt bijhouden.
`url`	tekenreeks	Een URL waarmee de authenticator-app wordt gestart en het uitgifteproces 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 uitgiftestroom 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 uitgifteproces wordt gestart.

Foutrespons

Als er een fout optreedt met de aanvraag, wordt er een foutbericht 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 uitgifteproces 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 voor de aanvraag. Mogelijke waarden: `request_retrieved`: De gebruiker heeft de QR-code gescand of de koppeling geselecteerd waarmee de uitgiftestroom wordt gestart. `issuance_successful`: De uitgifte van de verifieerbare referenties is geslaagd. `issuance_error`: Er is een fout opgetreden tijdens de uitgifte. Zie de `error` eigenschap voor meer informatie.
`state`	tekenreeks	Retourneert de statuswaarde die u hebt doorgegeven in de oorspronkelijke nettolading.
`error`	error	Wanneer de eigenschapswaarde `code` is `issuance_error`, bevat deze eigenschap informatie over de fout.
`error.code`	tekenreeks	De retourfoutcode.
`error.message`	tekenreeks	Het foutbericht.

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

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

In het volgende voorbeeld ziet u een callback-nettolading nadat de gebruiker het uitgifteproces heeft voltooid:

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

Callback-fouten

Het callback-eindpunt kan worden aangeroepen met een foutbericht. De volgende tabel bevat de foutcodes:

Bericht	Definitie
`fetch_contract_error`	Kan het verifieerbare referentiecontract niet ophalen. Deze fout treedt meestal op wanneer de API het manifest dat u opgeeft niet kan ophalen in het request payload-object RequestIssuance van de aanvraag.
`issuance_service_error`	De verifiable Credentials-service kan geen vereisten valideren of er is iets misgegaan in Verifieerbare referenties.
`unspecified_error`	Deze fout is ongebruikelijk, maar de moeite waard om te onderzoeken.

In het volgende voorbeeld ziet u een callback-nettolading wanneer er een fout is opgetreden:

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

Volgende stappen

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