Presentationsspecifikation för REST API för begärandetjänst

Artikel
02/06/2024

Microsoft Entra – verifierat ID innehåller REST-API:et för begärandetjänsten. Med det här API:et kan du utfärda och verifiera en autentiseringsuppgift. Den här artikeln anger REST-API:et för begärandetjänsten för en presentationsbegäran. Presentationsbegäran ber användaren att presentera en verifierbar autentiseringsuppgift och sedan verifiera autentiseringsuppgifterna. En annan artikel beskriver hur du anropar REST-API:et för begärandetjänsten.

HTTP-begäran

Rest API-presentationsbegäran för begärandetjänsten stöder följande HTTP-metod:

Metod	Kommentar
POST	Med JSON-nyttolast enligt beskrivningen i den här artikeln.

Begäran om REST API-presentation för begärandetjänsten kräver följande HTTP-huvuden:

Metod	Värde
`Authorization`	Bifoga åtkomsttoken som en ägartoken i auktoriseringshuvudet i en HTTP-begäran. Exempel: `Authorization: Bearer <token>`
`Content-Type`	`Application/json`

Skapa en HTTP POST-begäran till REST-API:et för begärandetjänsten. tenantId Behövs inte längre i URL:en eftersom den finns som ett anspråk i access_token.

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

Följande HTTP-begäran visar en presentationsbegäran till REST API:et för begärandetjänsten:

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

Följande behörighet krävs för att anropa REST-API:et för begärandetjänsten. Mer information finns i Bevilja behörigheter för att hämta åtkomsttoken.

Behörighetstyp	Behörighet
Program	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Nyttolast för presentationsbegäran

Nyttolasten för presentationsbegäran innehåller information om din verifierbara presentationsbegäran om autentiseringsuppgifter. I följande exempel visas en presentationsbegäran från en specifik utfärdare. Resultatet av den här begäran returnerar en QR-kod med en länk för att starta presentationsprocessen.

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

Nyttolasten innehåller följande egenskaper.

Parameter	Typ	Beskrivning
`includeQRCode`	Booleskt	Valfritt. Avgör om en QR-kod ingår i svaret på den här begäran. Presentera QR-koden och be användaren att skanna den. Genom att skanna QR-koden startas autentiseringsappen med den här presentationsbegäran. Möjliga värden är `true` (standard) eller `false`. När du anger värdet till `false`använder du returegenskapen `url` för att återge en djuplänk.
`includeReceipt`	Booleskt	Valfritt. Avgör om ett kvitto ska ingå i svaret på den här begäran. Möjliga värden är `true` eller `false` (standard). Kvittot innehåller den ursprungliga nyttolasten som skickades från autentiseringstjänsten till verifierbara autentiseringsuppgifter. Kvittot är användbart för felsökning eller om du behöver ge fullständig information om nyttolasten. Annars behöver du inte ange det här värdet som `true` standard. `OpenId Connect SIOP` I begäran innehåller kvittot ID-token från den ursprungliga begäran.
`authority`	sträng	Din decentraliserade identifierare (DID) för din verifierare Microsoft Entra-klientorganisation. Mer information finns i Samla in klientinformation för att konfigurera exempelprogrammet.
`registration`	Begäranderegistrering	Innehåller information om kontrollanten.
`callback`	Motringning	Obligatorisk. Gör att utvecklaren kan uppdatera användargränssnittet under den verifierbara presentationsprocessen för autentiseringsuppgifter. När användaren har slutfört processen fortsätter du processen när resultatet har returnerats till programmet.
`requestedCredentials`	Samling	En samling RequestCredential-objekt .

Typ av begäranderegistrering

Typen RequestRegistration innehåller informationsregistrering för utfärdaren. Typen RequestRegistration innehåller följande egenskaper:

Property	Type	Description
`clientName`	sträng	Ett visningsnamn för kontrollanten för de verifierbara autentiseringsuppgifterna. Det här namnet visas för användaren i autentiseringsappen.
`purpose`	sträng	Valfritt. En sträng som visas för att informera användaren om varför de verifierbara autentiseringsuppgifterna begärs.
`logoUrl`	webbadress	Valfritt. En URL för en logotyp för kontrollanten. Detta används inte av Authenticator-appen.
`termsOfServiceUrl`	webbadress	Valfritt. En URL till användarvillkoren för kontrollanten. Detta används inte av Authenticator-appen.

Följande skärmbild visar clientName egenskapen och visningsnamnet för authority (kontrollanten) i presentationsförfrågan.

Skärmbild som visar hur du godkänner presentationsbegäran.

Motringningstyp

Rest-API:et för begärandetjänsten genererar flera händelser till motringningsslutpunkten. Med dessa händelser kan du uppdatera användargränssnittet och fortsätta processen när resultatet har returnerats till programmet. Typen Callback innehåller följande egenskaper:

Property	Type	Description
`url`	sträng	URI till programmets slutpunkt för motringning. URI:n måste peka på en slutpunkt som kan nås på Internet, annars utlöser tjänsten ett oläsbart felmeddelande för återanrops-URL. Accepterade indata IPv4, IPv6 eller DNS-matchbart värdnamn.
`state`	sträng	Korrelerar motringningshändelsen med tillståndet som skickades i den ursprungliga nyttolasten.
`headers`	sträng	Valfritt. Du kan inkludera en samling HTTP-huvuden som krävs i slutet av POST-meddelandet. De aktuella sidhuvudvärdena som stöds är `api-key` rubrikerna `Authorization` eller . Alla andra huvuden utlöser ett ogiltigt motringningshuvudfel.

RequestCredential-typ

RequestCredential Innehåller information om de begärda autentiseringsuppgifterna som användaren behöver ange. RequestCredential innehåller följande egenskaper:

Property	Type	Description
`type`	sträng	Den verifierbara typen av autentiseringsuppgifter. `type` Måste matcha typen enligt definitionen i det `issuer` verifierbara manifestet för autentiseringsuppgifter (till exempel `VerifiedCredentialExpert`). Information om hur du hämtar utfärdarmanifestet finns i Samla in autentiseringsuppgifter och miljöinformation för att konfigurera exempelprogrammet. Kopiera URL:en för problemautentiseringsuppgifter, öppna den i en webbläsare och kontrollera id-egenskapen.
`purpose`	sträng	Valfritt. Ange information om syftet med att begära den här verifierbara autentiseringsuppgiften. Detta används inte av Authenticator-appen.
`acceptedIssuers`	strängsamling	Valfritt. En samling av utfärdarens DID:er som kan utfärda den typ av verifierbara autentiseringsuppgifter som ämnen kan presentera. Information om hur du hämtar utfärdaren GJORDE finns i Samla in autentiseringsuppgifter och miljöinformation för att konfigurera exempelprogrammet och kopiera värdet för den decentraliserade identifieraren (DID). Om samlingen `acceptedIssuers` är tom eller inte finns accepterar presentationsbegäran en typ av autentiseringsuppgifter som utfärdats av en utfärdare.
`configuration.validation`	Configuration.Validation	Valfria inställningar för presentationsverifiering.
`constraints`	Restriktioner	Valfritt. Insamling av anspråksbegränsningar.

Configuration.Validation-typ

Innehåller Configuration.Validation information om hur de presenterade autentiseringsuppgifterna ska verifieras. Det innehåller följande egenskaper: .

Property	Type	Beskrivning
`allowRevoked`	Booleskt	Valfritt. Avgör om en återkallad autentiseringsuppgift ska godkännas. Standardvärdet är `false` (det bör inte accepteras).
`validateLinkedDomain`	Booleskt	Valfritt. Avgör om den länkade domänen ska verifieras. Standard är `false`. Om du anger den här flaggan till innebär det att `false` du som förlitande part accepterar autentiseringsuppgifter från en overifierad länkad domän. Om den här flaggan anges till `true` innebär det att den länkade domänen verifieras och att endast verifierade domäner godkänns.
`faceCheck`	faceCheck	Valfritt. Tillåter begäran om en liveness-kontroll under presentationen.

Villkorstyp

Typen constraints innehåller en samling anspråksbegränsningar som måste uppfyllas när en plånbok väljer kandidatautentiseringsuppgifterna. Detta gör det möjligt att begära en autentiseringsuppgift med ett specifikt anspråksvärde. Angivna begränsningar använder AND-logiken, d.v.s. om du anger tre villkor måste alla uppfyllas. För varje begränsning i samlingen måste du välja en operand med värden, innehåller eller startsWith. Värden får inte vara reguljära uttryck. Alla jämförelser är skiftlägesokänsliga.

Property	Type	Description
`claimName`	sträng	Obligatorisk. Namn på anspråket för villkoret. Det här är anspråksnamnet i den verifierbara autentiseringsuppgiften. Se outputClaim i claimMapping-typ.
`values`	strängsamling	Uppsättning värden som ska matcha anspråksvärdet. Om du anger flera värden, till exempel ["röd", "grön", "blå"] är det en matchning om anspråksvärdet i autentiseringsuppgiften har något av värdena i samlingen.
`contains`	sträng	Villkoret utvärderas till sant om anspråksvärdet innehåller det angivna värdet.
`startsWith`	sträng	Villkoret utvärderas till sant om anspråksvärdet börjar med det angivna värdet.

faceCheck-typ

FaceCheck-typen innehåller information om hur du utför liveness-kontrollen under presentationen av en autentiseringsuppgift. Den begärda autentiseringsuppgiften måste innehålla ett foto av innehavaren i anspråket som heter av sourcePhotoClaimName. Presentationen lyckas om liveness-kontrollen når en konfidensnivå som är lika med eller större än vad som anges i egenskapen matchConfidenceThreshold. Om tröskelvärdet inte uppfylls misslyckas hela presentationen.

Property	Type	Description
`sourcePhotoClaimName`	sträng	Obligatorisk. Namnet på anspråket i autentiseringsuppgifterna som innehåller fotot. Se outputClaim i claimMapping-typ.
`matchConfidenceThreshold`	integer	Valfritt. Det konfidentiella tröskelvärdet för en lyckad kontroll mellan fotot och liveness-data. Måste vara ett heltal mellan 50 och 100. Standardvärdet är 70.

Lyckat svar

Om det lyckas returnerar den här metoden en svarskod (HTTP 201 Skapad) och en samling händelseobjekt i svarstexten. Följande JSON visar ett lyckat svar:

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

Svaret innehåller följande egenskaper:

Property	Type	Description
`requestId`	sträng	Ett automatiskt genererat begärande-ID. Återanropet använder samma begäran så att du kan hålla reda på presentationsbegäran och dess återanrop.
`url`	sträng	En URL som startar autentiseringsappen och startar presentationsprocessen. Du kan visa den här URL:en för användaren om de inte kan skanna QR-koden.
`expiry`	integer	Anger när svaret upphör att gälla.
`qrCode`	sträng	En QR-kod som användaren kan skanna för att starta presentationsflödet.

När din app får svaret måste appen presentera QR-koden för användaren. Användaren söker igenom QR-koden, vilket öppnar autentiseringsappen och startar presentationsprocessen.

Felsvar

Om det uppstår ett fel med begäran returneras ett felsvar och bör hanteras på lämpligt sätt av appen.

Återanropshändelser

Motringningsslutpunkten anropas när en användare söker igenom QR-koden, använder djuplänken i autentiseringsappen eller avslutar presentationsprocessen.

Property	Type	Description
`requestId`	sträng	Mappad till den ursprungliga begäran när nyttolasten bokfördes till verifierbara autentiseringsuppgifter.
`requestStatus`	sträng	Statusen som returnerades när begäran hämtades av autentiseringsappen. Möjliga värden: `request_retrieved`: Användaren skannade QR-koden eller valde länken som startar presentationsflödet. `presentation_verified`: Verifieringen av verifierbara autentiseringsuppgifter har slutförts. li>`presentation_error`: Det uppstod ett fel i presentationen.
`state`	sträng	Returnerar det tillståndsvärde som du skickade i den ursprungliga nyttolasten.
`subject`	sträng	Den verifierbara användaren av autentiseringsuppgifter gjorde det.
`verifiedCredentialsData`	matris	Returnerar en matris med begärda verifierbara autentiseringsuppgifter. För varje verifierbar autentiseringsuppgift tillhandahåller den: Verifierbara typ av autentiseringsuppgifter. Utfärdarens DID Anspråken som hämtats. Den verifierbara utfärdarens domän för autentiseringsuppgifter. Den verifierbara utfärdaren av autentiseringsuppgifternas domänverifieringsstatus.
`receipt`	sträng	Valfritt. Kvittot innehåller den ursprungliga nyttolasten som skickas från plånboken till verifierbara autentiseringsuppgifter. Kvittot ska endast användas för felsökning/felsökning. Formatet i kvittot korrigeras inte och kan ändras baserat på den plånbok och version som används.

I följande exempel visas en återanropsnyttolast när autentiseringsappen startar presentationsbegäran:

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

I följande exempel visas en återanropsnyttolast när presentationen av verifierbara autentiseringsuppgifter har slutförts:

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

Nästa steg

Lär dig hur du anropar REST-API:et för begärandetjänsten.