Delen via


De REST API van de aanvraagservice aanroepen

Microsoft Entra geverifieerde ID bevat de REST API van de aanvraagservice. Met deze API kunt u referenties uitgeven en verifiëren. In dit artikel leest u hoe u de REST API van de aanvraagservice kunt gaan gebruiken.

API-toegangstoken

Uw toepassing moet een geldig toegangstoken met de vereiste machtigingen bevatten, zodat deze toegang heeft tot de REST API van de aanvraagservice. Toegangstokens die zijn uitgegeven door het Microsoft Identity Platform bevatten informatie (bereiken) die door de REST API van de aanvraagservice worden gebruikt om de aanroeper te valideren. Een toegangstoken zorgt ervoor dat de aanroeper over de juiste machtigingen beschikt om de bewerking uit te voeren die ze aanvragen.

Als u een toegangstoken wilt ophalen, moet uw app worden geregistreerd bij het Microsoft Identity Platform en worden geautoriseerd door een beheerder voor toegang tot de REST API van de aanvraagservice. Als u de toepassing verifieerbare referenties-app niet hebt geregistreerd, raadpleegt u hoe u de app registreert en vervolgens een toepassingsgeheim genereert.

Een toegangstoken opvragen

Gebruik de stroom voor het verlenen van OAuth 2.0-clientreferenties om het toegangstoken te verkrijgen met behulp van het Microsoft Identity Platform. Gebruik hiervoor een vertrouwde bibliotheek. In deze zelfstudie gebruiken we de Microsoft Authentication Library (MSAL). MSAL vereenvoudigt het toevoegen van verificatie en autorisatie aan een app die een beveiligde web-API kan aanroepen.

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

Geef in de voorgaande code de volgende parameters op:

Parameter Voorwaarde Beschrijving
Instantie Vereist De directorytenant waarop de toepassing van plan is te werken. Voorbeeld: https://login.microsoftonline.com/{your-tenant}. (Vervang door your-tenant uw tenant-id of -naam.)
Client ID Vereist De toepassings-ID die aan uw app is toegewezen. U vindt deze informatie in Azure Portal, waar u uw app hebt geregistreerd.
Clientgeheim Vereist Het clientgeheim dat u hebt gegenereerd voor uw app.
Bereiken Vereist Moet worden ingesteld op 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Deze instelling produceert een toegangstoken met een rolclaim van VerifiableCredential.Create.All.

Zie een van de volgende artikelen voor meer informatie over het verkrijgen van een toegangstoken met behulp van de identiteit van een console-app:

U kunt ook toegang krijgen tot een tokenaanvraag met een certificaat in plaats van een clientgeheim.

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

De API aanroepen

Een verifieerbare referentie uitgeven of verifiëren:

  1. Maak een HTTP POST-aanvraag naar de REST API van de aanvraagservice. De tenant-id is niet meer nodig in de URL omdat deze aanwezig is als een claim in het toegangstoken.

    Probleem

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

    Verifiëren

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Koppel het toegangstoken als bearer-token aan de autorisatieheader in een HTTP-aanvraag.

    Authorization: Bearer <token>
    
  3. Stel de Content-Type koptekst in op Application/json.

  4. Bereid de nettolading van de uitgifte - of presentatieaanvraag voor en koppel deze aan de hoofdtekst van de aanvraag.

  5. Dien de aanvraag in bij de REST API van de aanvraagservice.

De AANVRAAGservice-API retourneert een HTTP-statuscode 201 Created voor een geslaagde aanroep. Als de API-aanroep een fout retourneert, raadpleegt u de documentatie voor foutreferenties.

Voorbeeld van uitgifteaanvraag

In het volgende voorbeeld ziet u een verifieerbare uitgifteaanvraag voor referenties. Zie de uitgiftespecificatie van de REST API-aanvraagservice voor meer informatie over de nettolading.

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

{...JSON payload...}

Uitgifteaanvraag met behulp van de idTokenHint attestation-stroom:

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

Zie een van de volgende codevoorbeelden voor de volledige code:

Voorbeeld van presentatieaanvraag

In het volgende voorbeeld ziet u een verifieerbare presentatieaanvraag voor referenties. Zie de presentatiespecificatie van de REST API-aanvraagservice voor meer informatie over de nettolading.

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

{...JSON payload...}

Presentatieaanvraag voor een referentie met een bepaald type en verlener:

{
  "includeQRCode": true,
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "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
        }
      }
    }
  ]
}

Zie een van de volgende codevoorbeelden voor de volledige code:

Callback-gebeurtenissen

De nettolading van de aanvraag bevat het callback-eindpunt voor uitgifte en presentatie . Het eindpunt maakt deel uit van uw webtoepassing en moet openbaar beschikbaar zijn via het HTTPS-protocol. De Api voor aanvraagservice roept uw eindpunt aan om uw app te informeren over bepaalde gebeurtenissen. Dergelijke gebeurtenissen kunnen bijvoorbeeld zijn wanneer een gebruiker de QR-code scant, de dieptekoppeling naar de verificator-app gebruikt of het presentatieproces voltooit.

In het volgende diagram wordt de aanroep van uw app beschreven in de REST API van de aanvraagservice en de callbacks naar uw toepassing.

Diagram met de aanroep naar de API en de callback-gebeurtenissen.

Configureer uw eindpunt om te luisteren naar binnenkomende HTTP POST-aanvragen. In het volgende codefragment ziet u hoe u de HTTP-aanvraag voor de uitgifteaanroep kunt verwerken en hoe u de gebruikersinterface dienovereenkomstig bijwerkt:

Niet van toepassing. Kies een van de andere programmeertalen.

Volgende stappen

Meer informatie over deze specificaties: