Präsentationsspezifikation der Anforderungsdienst-REST-API

Microsoft Entra Verified ID umfasst die REST-API für den Anforderungsdienst. Mit dieser API können Sie Nachweise (Verifiable Credentials) ausstellen und überprüfen. In diesem Artikel wird die Anforderungsdienst-REST-API für eine Präsentationsanforderung beschrieben. Die Präsentationsanforderung fordert den Benutzer auf, einen Nachweis zu präsentieren und diesen dann zu überprüfen. Ein weiterer Artikel beschreibt das Aufrufen der Anforderungsdienst-REST-API.

HTTP-Anforderung

Die Präsentationsanforderung der Anforderungsdienst-REST-API unterstützt die folgende HTTP-Methode:

Methode	Hinweise
POST	Mit JSON-Nutzdaten, wie in diesem Abschnitt beschrieben.

Die Präsentationsanforderung der Anforderungsdienst-REST-API erfordert die folgenden HTTP-Header:

Methode	Wert
Authorization	Fügen Sie das Zugriffstoken als Bearertoken an den Autorisierungsheader einer HTTP-Anforderung an. Beispiel: Authorization: Bearer <token>.
Content-Type	Application/json

Erstellen Sie eine HTTP POST-Anforderung für die Anforderungsdienst-REST-API. Die tenantId ist in der URL nicht mehr erforderlich, weil sie als Anspruch im access_token vorliegt.

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

Die folgende HTTP-Anforderung veranschaulicht eine Präsentationsanforderung an die Anforderungsdienst-REST-API:

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

Zum Aufrufen der Anforderungsdienst-REST-API ist die folgende Berechtigung erforderlich. Weitere Informationen finden Sie unter Erteilen von Berechtigungen zum Abrufen von Zugriffstoken.

Berechtigungstyp	Berechtigung
Application	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Nutzdaten der Präsentationsanforderung

Die Nutzdaten der Präsentationsanforderung enthalten Informationen zu Ihrer Nachweispräsentationsanforderung. Im folgenden Beispiel wird eine Präsentationsanforderung von einem bestimmten Aussteller dargestellt. Das Ergebnis dieser Anforderung gibt einen QR-Code mit einem Link zum Starten des Präsentationsprozesses zurück.

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

Die Nutzdaten enthalten die folgenden Eigenschaften.

Parameter	Typ	Beschreibung
includeQRCode	Boolean	Optional. Legt fest, ob ein QR-Code in der Antwort auf diese Anforderung enthalten ist. Präsentieren Sie den QR-Code, und fordern Sie den Benutzer auf, ihn zu scannen. Durch das Scannen des QR-Codes wird die Authentifikator-App mit dieser Präsentationsanforderung gestartet. Mögliche Werte sind: true (Standard) oder false. Wenn der Parameter auf false festgelegt ist, verwenden Sie die urlRückgabeeigenschaft, um einen Deep Link zu rendern.
includeReceipt	Boolean	Optional. Legt fest, ob ein Beleg in der Antwort dieser Anforderung enthalten sein soll. Mögliche Werte sind true oder false (Standardwert). Der Beleg enthält die ursprünglichen Nutzdaten, die vom Authentifikator an den Nachweisdienst gesendet wurden. Der Beleg ist nützlich für die Problembehandlung oder für den Fall, dass Sie die vollständigen Details der Nutzdaten abrufen müssen. Andernfalls muss dieser Wert nicht standardmäßig auf true festgelegt werden. In der OpenId Connect SIOP-Anforderung enthält der Beleg das ID-Token aus der ursprünglichen Anforderung.
authority	Zeichenfolge	Ihr dezentralisierter Bezeichner (DID) Ihres Microsoft Entra-Prüfungsmandanten. Weitere Informationen finden Sie unter Erfassen von Mandantendetails zum Einrichten Ihrer Beispielanwendung.
registration	RequestRegistration	Stellt Informationen zum Prüfer bereit.
callback	Callback	Erforderlich. Ermöglicht dem Entwickler, die Benutzeroberfläche während des Nachweispräsentationsprozesses zu aktualisieren. Wenn der Benutzer den Prozess abgeschlossen hat, setzen Sie den Prozess fort, nachdem die Ergebnisse an die Anwendung zurückgegeben werden.
requestedCredentials	collection	Eine Sammlung von RequestCredential-Objekten.

RequestRegistration-Typ

Der RequestRegistration Typ stellt Informationen zur Registrierung für den Aussteller bereit. Die RequestRegistration Typ enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
clientName	Zeichenfolge	Ein Anzeigename des Prüfers des Nachweises. Dieser Name wird dem Benutzer in der Authentifikator-App angezeigt.
purpose	Zeichenfolge	Optional. Eine Zeichenfolge, die angezeigt wird, um den Benutzer darüber zu informieren, warum die Nachweise angefordert werden.
logoUrl	URL	Dies ist optional. Eine URL für einen Logotyp des Prüfers. Dies wird von der Authenticator-App nicht verwendet.
termsOfServiceUrl	URL	Dies ist optional. Eine URL zu den Vertragsbedingungen für den Prüfer. Dies wird von der Authenticator-App nicht verwendet.

Der folgende Screenshot zeigt die clientName-Eigenschaft und den Anzeigenamen der authority (des Prüfers) in der Präsentationsanforderung.

Rückruftyp

Die Anforderungsdienst-REST-API generiert mehrere Ereignisse für den Rückrufendpunkt. Mit diesen Ereignissen können Sie die Benutzeroberfläche aktualisieren und den Prozess fortsetzen, sobald die Ergebnisse an die Anwendung zurückgegeben werden. Die Callback Typ enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
url	Zeichenfolge	URI zum Rückrufendpunkt Ihrer Anwendung. Der URI muss auf einen erreichbaren Endpunkt im Internet verweisen, andernfalls gibt der Dienst einen Fehler mit dem Hinweis aus, dass die Rückruf-URL nicht gelesen werden kann. Akzeptierte Eingaben: IPv4, IPv6 oder auflösbarer DNS-Hostname
state	Zeichenfolge	Korreliert das Rückrufereignis mit dem Zustand, der in den ursprünglichen Nutzdaten übergeben wird.
headers	Zeichenfolge	Optional. Sie können eine Sammlung von HTTP-Headern einfügen, die von der empfangenden Seite der POST-Nachricht benötigt werden. Derzeit werden die Header api-key und Authorization als Headerwerte unterstützt. Jeder andere Header führt zu einem Fehler aufgrund eines ungültigen Rückrufheaders.

Typ „RequestCredential“

Der Typ RequestCredential stellt Informationen zu den angeforderten Anmeldeinformationen bereit, die der Benutzer angeben muss. RequestCredential enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
type	Zeichenfolge	Der Typ des Nachweises. Der type muss dem Typ entsprechen, der im issuer-Nachweismanifest definiert ist (z. B. VerifiedCredentialExpert). Um das Ausstellermanifest zu erhalten, lesen Sie Erfassen von Nachweisen und Umgebungsdetails zum Einrichten Ihrer Beispielanwendung. Kopieren Sie die Ausstelleranmeldeinformationen-URL, öffnen Sie die URL in einem Webbrowser und überprüfen Sie die ID-Eigenschaft.
purpose	Zeichenfolge	Optional. Geben Sie Informationen zum Zweck der Anforderung dieses Nachweises an. Dies wird von der Authenticator-App nicht verwendet.
acceptedIssuers	Zeichenfolgensammlung	Optional. Eine Sammlung von Aussteller-DIDs, die den Nachweistyp ausstellen könnten, der von Antragstellern präsentiert wird. Um Ihren Aussteller-DID zu erhalten, lesen Sie Erfassen von Nachweisen und Umgebungsdetails zum Einrichten Ihrer Beispielanwendung, und kopieren Sie den Wert des dezentralisierten Bezeichners (Decentralized Identifier, DID) . Wenn die acceptedIssuers-Sammlung leer oder nicht vorhanden ist, wird die Präsentationsanforderung einen Anmeldeinformationstyp akzeptieren, der von einem beliebigen Zertifikataussteller ausgestellt wurde.
configuration.validation	Configuration.Validation	Optionale Einstellungen für die Präsentationsüberprüfung.
constraints	Einschränkungen	Optional. Sammlung von Anspruchseinschränkungen.

Configuration.Validation-Typ

Configuration.Validation informiert darüber, wie die dargestellten Anmeldeinformationen überprüft werden sollten. Es enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
allowRevoked	Boolean	Optional. Legt fest, ob eine widerrufene Anmeldeinformation akzeptiert werden soll. Der Standardwert ist false (nicht akzeptiert).
validateLinkedDomain	Boolean	Optional. Legt fest, ob die verknüpfte Domäne überprüft werden soll. Der Standardwert ist false. Wenn Sie dieses Flag auf false festlegen, bedeutet dies, dass Sie als Anwendung für vertrauende Parteien Anmeldeinformationen einer nicht überprüften verknüpften Domäne akzeptieren. Durch Festlegen dieses Flags auf true wird die verknüpfte Domäne überprüft, und nur überprüfte Domänen werden akzeptiert.
faceCheck	faceCheck	Optional. Ermöglicht das Anfordern eines Livetests während der Präsentation.

Einschränkungstyp

Der constraints-Typ enthält eine Sammlung von Anspruchseinschränkungen, die erfüllt werden müssen, wenn eine Geldbörse die Kandidatenanmeldeinformationen auswählt. Dadurch wird das Anfordern einer Anmeldeinformation mit einem bestimmten Anspruchswert ermöglicht. Die angegebenen Bedingungen verwenden die UND-Logik, d. h. wenn Sie drei Bedingungen angeben, müssen alle erfüllt sein. Für jede Einschränkung in der Auflistung müssen Sie einen Operanden von Werten auswählen, enthält oder beginnt mit. Werte dürfen keine regulären Ausdrücke sein. Beim allen Vergleichen wird die Groß-/Kleinschreibung nicht beachtet.

Eigenschaft	Typ	Beschreibung
claimName	string	Obligatorisch. Name des Anspruchs für die Einschränkung. Dies ist der Anspruchsname im Nachweis. Siehe outputClaim im claimMapping-Typ.
values	Zeichenfolgensammlung	Wertesatz, der mit dem Anspruchswert übereinstimmen soll. Wenn Sie mehrere Werte angeben, z. B. ["red", "green", "blue"] ist dies eine Übereinstimmung, wenn der Anspruchswert in den Anmeldeinformationen einen der Werte in der Sammlung aufweist.
contains	Zeichenfolge	Die Einschränkung wird als true ausgewertet, wenn der Anspruchswert den angegebenen Wert enthält.
startsWith	Zeichenfolge	Die Einschränkung wird als true ausgewertet, wenn der Anspruchswert mit dem angegebenen Wert beginnt.

faceCheck-Typ

Der FaceCheck-Typ enthält Informationen zum Durchführen des Livetests während der Präsentation einer Anmeldeinformationen. Die angeforderten Anmeldeinformationen müssen ein Foto des Inhabers in dem Anspruch enthalten, der vom sourcePhotoClaimName benannt ist. Die Präsentation wird erfolgreich ausgeführt, wenn der Livetest ein Konfidenzniveau erreicht, das dem in der Eigenschaft „matchConfidenceThreshold“ angegebenen Wert entspricht oder größer ist. Wenn der Schwellenwert nicht erreicht ist, schlägt die gesamte Präsentation fehl.

Eigenschaft	Typ	Beschreibung
sourcePhotoClaimName	string	Erforderlich. Der Name des Anspruchs in den Anmeldeinformationen, die das Foto enthalten. Siehe outputClaim im claimMapping-Typ.
matchConfidenceThreshold	integer	Optional. Der vertrauliche Schwellenwert für eine erfolgreiche Überprüfung zwischen dem Foto und den Liveness-Daten. Muss eine ganze Zahl zwischen 50 und 100 sein. Der Standardwert ist 70.

Erfolgreiche Antwort

Bei Erfolg gibt diese Methode einen HTTP 201 Created-Antwortcode und eine Sammlung von Ereignisobjekten im Antworttext zurück. Im folgenden JSON-Beispiel wird eine erfolgreiche Antwort dargestellt:

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

Die Antwort enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
requestId	string	Automatisch generierte Anforderungs-ID. Die Rückruffunktion (Callback) verwendet dieselbe Anforderung, sodass Sie die Präsentationsanforderung und ihre Rückruffunktionen nachverfolgen können.
url	Zeichenfolge	Eine URL, die zuerst die Authentifikator-App und dann den Präsentationsprozess startet. Sie können dem Benutzer diese URL präsentieren, wenn er den QR-Code nicht scannen kann.
expiry	integer	Gibt an, wann die Antwort abläuft.
qrCode	string	Ein QR-Code, den der Benutzer scannen kann, um den Präsentationsflow zu starten.

Wenn Ihre App die Antwort erhält, muss sie dem Benutzer den QR-Code präsentieren. Der Benutzer scannt den QR-Code, wodurch die Authentifikator-App geöffnet wird und der Präsentationsprozess gestartet wird.

Fehlerantwort

Wenn bei der Anforderung ein Fehler auftritt, werden Fehlerantworten zurückgegeben und sollten von der App entsprechend behandelt werden.

Callback-Ereignisse

Der Callback-Endpunkt wird aufgerufen, wenn ein Benutzer den QR-Code scannt, den Deep Link seiner Authentifikator-App verwendet oder den Präsentationsprozess abschließt.

Eigenschaft	Typ	Beschreibung
requestId	Zeichenfolge	Wird der ursprünglichen Anforderung zugeordnet, wenn die Nutzdaten an den Nachweisdienst (Verifiable-Credentials-Dienst) gesendet wurden.
requestStatus	Zeichenfolge	Der Code, der zurückgegeben wird, wenn die Anforderung von der Authentifikator-App abgerufen wurde. Mögliche Werte: request_retrieved: Der Benutzer hat den QR-Code gescannt oder den Link ausgewählt, der den Präsentationsflow startet. presentation_verified: Die Überprüfung der Nachweise wurde erfolgreich abgeschlossen. li>presentation_error: In der Präsentation ist ein Fehler aufgetreten.
state	Zeichenfolge	Gibt den Statuswert zurück, den Sie in den ursprünglichen Nutzdaten übergeben haben.
subject	Zeichenfolge	Der Benutzer-DID des Nachweises.
verifiedCredentialsData	array	Gibt ein Array von angeforderten Nachweisen zurück. Für jeden Nachweis wird Folgendes angegeben: Der Typ bzw. die Typen des Nachweises. Die DID des Ausstellers. Die abgerufenen Ansprüche. Die Domäne des Nachweisausstellers. Der Überprüfungsstatus der Domäne des Nachweisausstellers.
receipt	Zeichenfolge	Optional. Der Beleg enthält die ursprünglichen Nutzdaten, die vom Wallet an den Nachweisdienst gesendet wurden. Der Beleg sollte nur für die Problembehandlung bzw. zum Debuggen verwendet werden. Das Format im Beleg ist nicht unveränderlich und kann sich je nach verwendetem Wallet und Version ändern.

Das folgende Beispiel demonstriert Callback-Nutzdaten, wenn die Präsentationsanforderung durch die Authentifikator-App gestartet wird:

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

Das folgende Beispiel demonstriert Callback-Nutzdaten, nachdem die Präsentation der Nachweise erfolgreich abgeschlossen wurde.

{
  "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ächste Schritte

Lesen Sie die Informationen zum Aufrufen der Anforderungsdienst-REST-API.