Specificatie REST API voor services -presentatie aanvragen (preview)

Azure Active Directory verifieerbare referenties (Azure AD) bevat de REST API voor services. Met deze API kunt u een referentie uitgeven en verifiëren. In dit artikel wordt de aanvraagaanvraag REST API voor services voor een presentatieaanvraag opgegeven. De presentatieaanvraag vraagt de gebruiker om een verifieerbare referentie te presenteren en vervolgens de referentie te verifiëren.

HTTP-aanvraag

De aanvraag request REST API voor services-presentatie ondersteunt de volgende HTTP-methode:

Methode Notities
POST Met JSON-nettolading zoals opgegeven in dit artikel.

Voor de aanvraag REST API voor services aanvraag voor de presentatie zijn de volgende HTTP-headers vereist:

Methode Waarde
Authorization Koppel het toegangs token als bearer-token aan de autorisatie-header in een HTTP-aanvraag. Bijvoorbeeld Authorization: Bearer <token>.
Content-Type Application/json

Een HTTP POST-aanvraag maken voor de aanvraag REST API voor services. Vervang door {tenantID} uw tenant-id of tenantnaam.

https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request

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

POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request
Content-Type: application/json
Authorization: Bearer  <token>

{  
    "includeQRCode": true,  
    "callback": {  
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",  
    "state": "11111111-2222-2222-2222-333333333333",  
      "headers": {  
        "api-key": "an-api-key-can-go-here"  
      }  
    },  
    ...
} 

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

Machtigingstype Machtiging
Toepassing bbb94529-53a3-4be5-a069-7eaf2712b826/.default

Nettolading van presentatieaanvraag

De nettolading van de presentatieaanvraag bevat informatie over de presentatieaanvraag voor uw verifieerbare referenties. In het volgende voorbeeld wordt een presentatieaanvraag van een specifieke vergever gedemonstreerd. Het resultaat van deze aanvraag retourneert een QR-code met een koppeling om het presentatieproces te starten.

{
  "includeQRCode": true,
  "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "presentation": {
    "includeReceipt": true,
    "requestedCredentials": [
      {
        "type": "VerifiedCredentialExpert",
        "purpose": "So we can see that you a veritable credentials expert",
        "acceptedIssuers": [
          "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
        ]
      }
    ]
  }
}

De nettolading bevat de volgende eigenschappen.

Parameter Type Description
includeQRCode Booleaans Hiermee bepaalt u of er een QR-code is opgenomen in het antwoord van deze aanvraag. Presenter de QR-code en vraag de gebruiker om deze te scannen. Als u de QR-code scant, wordt de authenticator-app met deze presentatieaanvraag gelanceerd. Mogelijke waarden zijn true (standaard) of false . Wanneer u de waarde in stelt op false , gebruikt u de eigenschap return om een url dieptekoppeling weer te geven.
authority tekenreeks Uw gedecentraliseerde id (DID) van uw verifier-Azure AD-tenant. Zie Tenantdetails verzamelen om uw voorbeeldtoepassing in te stellen voor meer informatie.
registration RequestRegistration Bevat informatie over de verifier.
presentation RequestPresentation Bevat informatie over de presentatieaanvraag voor verifieerbare referenties.
callback Callback Hiermee kan de ontwikkelaar de gebruikersinterface bijwerken tijdens het presentatieproces voor verifieerbare referenties. Wanneer de gebruiker het proces heeft voltooid, gaat u door met het proces nadat de resultaten zijn geretourneerd naar de toepassing.

RequestRegistration-type

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

Eigenschap Type Description
clientName tekenreeks Een weergavenaam van de vergever van de verifieerbare referentie. Deze naam wordt weergegeven aan de gebruiker in de authenticator-app.

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

Schermopname die laat zien hoe u de presentatieaanvraag goedkeurt.

RequestPresentation-type

Het RequestPresentation type bevat informatie die vereist is voor de presentatie van verifieerbare referenties. RequestPresentation bevat de volgende eigenschappen:

Eigenschap Type Description
includeReceipt Booleaans 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 ver authenticator naar de service Verifiable Credentials. Het ontvangstbewijs is handig voor het oplossen van problemen en mag niet standaard worden ingesteld. In de OpenId Connect SIOP aanvraag bevat het ontvangstbewijs het id-token van de oorspronkelijke aanvraag.
requestedCredentials verzameling Een verzameling RequestCredential-objecten.

RequestCredential-type

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

Eigenschap Type Description
type tekenreeks Het verifieerbare referentietype. De type moet overeenkomen met het type zoals gedefinieerd in het issuer verifieerbare referentiemanifest (bijvoorbeeld VerifiedCredentialExpert ). Zie Referenties en omgevingsdetailsverzamelen om uw voorbeeldtoepassing in te stellen om het manifest van de vergever op te halen. Kopieer de URL voor probleemreferenties, open deze in een webbrowser en controleer de eigenschap id.
purpose tekenreeks Geef informatie op over het doel van het aanvragen van deze verifieerbare referentie.
acceptedIssuers tekenreeksverzameling Een verzameling van de DID's van verwerkers die het type verifieerbare referentie kunnen uitgeven dat de onderwerpen kunnen presenteren. Zie Gather credentials and environment details to set up your sample application (Referenties en omgevingsgegevensverzamelen om uw voorbeeldtoepassing in te stellen) en kopieer de waarde van de Gedecentraliseerde id (DID).

Type callback

De aanvraag REST API voor services 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 Description
url tekenreeks URI naar het callback-eindpunt van uw toepassing.
state tekenreeks Koppelt aan 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 headers mogen alleen de header of bevatten api-key die vereist is voor autorisatie.

Geslaagd antwoord

Als dit lukt, retourneert deze methode een antwoordcode (HTTP 201 Gemaakt) en een verzameling gebeurtenisobjecten in de antwoord-body. De volgende JSON toont een geslaagd antwoord:

{  
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid://vc/?request_uri=https://beta.did.msidentity.com/v1.0/87654321-0000-0000-0000-000000000000/verifiablecredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
} 

Het antwoord bevat de volgende eigenschappen:

Eigenschap Type Description
requestId tekenreeks Een automatisch gegenereerde correlatie-id. De callback maakt gebruik van dezelfde aanvraag, zodat u de presentatieaanvraag en de callbacks kunt bijhouden.
url tekenreeks Een URL waarmee de authenticator-app wordt gestart en het presentatieproces wordt gestart. U kunt deze URL aan de gebruiker presenteren als deze de QR-code niet kan 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 authenticator-app wordt geopend en het presentatieproces wordt gestart.

Foutbericht

Foutreacties kunnen ook worden geretourneerd, zodat de app deze op de juiste manier kan verwerken. De volgende JSON toont een niet-geautoriseerd foutbericht:

{
    "requestId": "fb888ac646c96083de83b099b2678de0",
    "date": "Wed, 29 Sep 2021 21:49:00 GMT",
    "error": {
        "code": "unauthorized",
        "message": "Failed to authenticate the request."
    }
}

Het antwoord bevat de volgende eigenschappen:

Eigenschap Type Description
requestId tekenreeks Een automatisch gegenereerde aanvraag-id.
date date Het tijdstip van de fout.
error.code tekenreeks De retourfoutcode.
error.message tekenreeks Het foutbericht.

Callback-gebeurtenissen

Het callback-eindpunt wordt aangeroepen wanneer een gebruiker de QR-code scant, de dieptekoppeling van de authenticator-app gebruikt of het presentatieproces af rondt.

Eigenschap Type Description
requestId tekenreeks Deze is aan de oorspronkelijke aanvraag toe te staan toen de nettolading werd geplaatst in de service Verifiable Credentials.
code tekenreeks De code die is geretourneerd toen de aanvraag werd opgehaald door de authenticator-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.
state tekenreeks Retourneert de statuswaarde die u hebt doorgegeven in de oorspronkelijke nettolading.
subject tekenreeks De verifieerbare referentiegebruiker heeft dit gedaan.
issuers matrix Retourneert een matrix met verifieerbare referenties die zijn aangevraagd. Voor elke verifieerbare referentie biedt deze het volgende:
  • Het verifieerbare referentietype.
  • De opgehaalde claims.
  • Het domein van de verifieerbare referentievergever.
  • De validatiestatus van het domein van de verifieerbare referentievergever.
  • receipt tekenreeks Optioneel. Het ontvangstbewijs bevat de oorspronkelijke nettolading die van de ver authenticator naar Verifieerbare referenties is verzonden.

    In het volgende voorbeeld wordt een callback-nettolading gedemonstreerd wanneer de authenticator-app de presentatieaanvraag start:

    {  
        "requestId":"aef2133ba45886ce2c38974339ba1057",  
        "code":"request_retrieved",  
        "state":"Wy0ThUz1gSasAjS1"
    } 
    

    In het volgende voorbeeld wordt een callback-nettolading gedemonstreerd nadat de presentatie van de verifieerbare referentie is voltooid:

    {
      "requestId": "87e1cb24-9096-409f-81cb-9e645f23a4ba",
      "code": "presentation_verified",
      "state": "f3d94e35-ca5f-4b1b-a7d7-a88caa05e322",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "issuers": [
        {
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "John",
            "lastName": "Doe"
          },
          "domain": "https://contoso.com/",
          "verified": "DNS",
          "issuer": "did:ion:….."
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>"
      }
    } 
    

    Volgende stappen

    Meer informatie over het aanroepen van de REST API voor services.