Präsentationsspezifikation der Anforderungsdienst-REST-API

Hinweis

Microsoft Entra Verified ID, ein Feature der Microsoft Entra-Produktfamilie, ersetzt jetzt Azure Active Directory-Nachweise. Erfahren Sie mehr über die Microsoft Entra-Familie mit Lösungen für die Identitätsverwaltung, und beginnen Sie im einheitlichen Microsoft Entra Admin Center.

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://www.contoso.com/api/verifier/presentationCallbac",
    "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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Die Nutzdaten enthalten die folgenden Eigenschaften.

Parameter type Beschreibung
includeQRCode Boolesch 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 Boolesch 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 string Ihr dezentralisierter Bezeichner (DID) Ihres Azure AD-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 type Beschreibung
clientName Zeichenfolge Ein Anzeigename des Ausstellers des Nachweises. Dieser Name wird dem Benutzer in der Authentifikator-App angezeigt.

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

Screenshot: Genehmigen 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 type 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 type 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 Geben Sie Informationen zum Zweck der Anforderung dieses Nachweises an.
acceptedIssuers Zeichenfolgensammlung 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 ist, akzeptiert die Präsentationsanforderung einen Anmeldeinformationstyp, der von einem beliebigen Aussteller ausgestellt wurde.
configuration.validation Configuration.Validation Optionale Einstellungen für die Präsentationsüberprüfung.

Configuration.Validation-Typ

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

Eigenschaft type Beschreibung
allowRevoked Boolesch Legt fest, ob eine widerrufene Anmeldeinformation akzeptiert werden soll. Der Standardwert ist false (nicht akzeptiert).
validateLinkedDomain Boolean 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.

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/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

Die Antwort enthält die folgenden Eigenschaften:

Eigenschaft type 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 type 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.
state string Gibt den Statuswert zurück, den Sie in den ursprünglichen Nutzdaten übergeben haben.
subject Zeichenfolge Der Benutzer-DID des Nachweises.
issuers 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:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "verifiedCredentialsData": [
        {
          "issuer": "did:ion:issuer",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          }
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Nächste Schritte

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