Spezifikation der Ausstellung für die Anforderungsdienst-REST-API (Vorschau)

Artikel
02/27/2024

Microsoft Entra Verified ID umfasst die REST-API für den Anforderungsdienst. Mit dieser API können Sie Anmeldeinformationen ausstellen und überprüfen. In diesem Abschnitt wird die Anforderungs-Dienst-REST-API für eine Anforderung der Ausstellung beschrieben. Ein weiterer Artikel beschreibt das Aufrufen der Anforderungsdienst-REST-API.

HTTP-Anforderung

Die Anforderung des Dienste-REST-API unterstützt die folgende HTTP-Methode:

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

Für die Anforderung des Dienste-REST-API sind folgende HTTP-Header erforderlich:

Name	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.

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

Die folgende HTTP-Anforderung demonstriert eine Anforderung an die Anforderungs-Dienst-REST-API:

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

{
    "includeQRCode": true,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

Für die Anforderung der Dienste-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 Anforderung zur Ausstellung

Die Nutzdaten der Ausgabeanforderung enthalten Informationen über Ihre Anforderung zur Ausgabe von überprüfbaren Berechtigungsnachweisen. Das folgende Beispiel veranschaulicht eine Anforderung zur Ausstellung unter Verwendung des PIN-Code-Flusses mit Benutzerangaben wie Vor- und Nachname. Das Ergebnis dieser Anforderung ist ein QR-Code mit einem Link zum Starten des Ausstellungsverfahrens.

{
  "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",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

Die Nutzdaten enthalten die folgenden Eigenschaften:

Parameter	Typ	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 Authentifizierungs-App mit dieser Anforderung gestartet. Mögliche Werte sind: `true` (Standard) oder `false`. Wenn der Parameter auf `false` festgelegt ist, verwenden Sie die `url`Rückgabeeigenschaft, um einen Deep Link zu rendern.
`callback`	Callback	Erforderlich. Ermöglicht es dem Entwickler, asynchron Informationen über den Ablauf während des Prozesses der Ausstellung von überprüfbaren Berechtigungsnachweisen zu erhalten. So könnte der Entwickler beispielsweise einen Aufruf wünschen, wenn der Benutzer den QR-Code gescannt hat oder wenn die Ausgabeanforderung erfolgreich war oder fehlgeschlagen ist.
`authority`	Zeichenfolge	Der dezentrale Identifikation (DID) des Ausstellers. Weitere Informationen finden Sie unter Sammeln Sie Anmeldeinformationen und Umgebungsdetails, um Ihre Beispielanwendung einzurichten.
`registration`	RequestRegistration	Liefert Informationen über den Aussteller, die in der Authentifikator-App angezeigt werden können.
`type`	Zeichenfolge	Der Typ des Nachweises. Sollte dem Typ entsprechen, der im Manifest des Nachweises definiert ist. Beispiel: `VerifiedCredentialExpert`. Weitere Informationen finden Sie unter Erstellen der Expertenkarte für den Nachweis (Verified Credential) in Azure.
`manifest`	string	Die URL des Manifest-Dokuments des Nachweises (Verified Credential). Weitere Informationen finden Sie unter Sammeln Sie Anmeldeinformationen und Umgebungsdetails, um Ihre Beispielanwendung einzurichten.
`claims`	Zeichenfolge	Optional. Kann nur verwendet werden, um dem Nachweisflow ID-Tokenhinweis eine Sammlung von Assertions über den Antragsteller im Nachweis hinzuzufügen.
`pin`	PIN	Optional. PIN-Code kann nur mit dem ID-Tokenhinweis-Nachweisfluss verwendet werden. Eine PIN-Nummer, die zusätzliche Sicherheit bei der Ausstellung bietet. Sie generieren einen PIN-Code und zeigen ihn dem Benutzer in Ihrer Anwendung an. Der Benutzer muss den von Ihnen generierten PIN-Code angeben.
`expirationDate`	Zeichenfolge	Optional. Der expirationDate-Parameter kann nur mit dem Nachweisfluss ID-Tokenhinweis verwendet werden. Sofern angegeben, muss das Ablaufdatum ein Datum im ISO8601-Format sein. Das Datum überschreibt den validityInterval-Wert in der Definition der Anmeldeinformationenregeln für diese Ausstellungsanforderung. Verwenden Sie diese Einstellung, um unabhängig vom Ausstellungszeitpunkt explizit zu steuern, wann Anmeldeinformationen ablaufen (z. B. Tagesende, Monatsende oder Jahresende). Beachten Sie, dass das Datum im UTC-Format (Coordinated Universal Time, koordinierte Weltzeit) angegeben wird. Wenn Sie „Jahresende“ angeben und die Zeit auf `23:59:59` festlegen, bedeutet dies in der UTC-Zeit 1 Sekunde bis Mitternacht. Jeder Benutzer in einer anderen Zeitzone sieht das Ablaufdatum, das in der lokalen Zeitzone in Microsoft Authenticator angezeigt wird. In der CET-Zeitzone (Central European Time, mitteleuropäische Zeit) wird das Ablaufdatum daher als 1. Januar 1.00 Uhr angezeigt. Für den Anmeldeinformationsvertrag muss das Flag allowOverrideValidityOnIssuance auf WAHR festgelegt sein.

Derzeit gibt es vier Anspruchsnachweistypen, die Sie in den Nutzdaten senden können. Microsoft Entra Verified ID verwendet vier Methoden, um Ansprüche in einen Nachweis einzufügen und diese Informationen mit der DID des Ausstellers zu bestätigen. Nachstehend werden die vier Typen aufgeführt:

ID-Token
ID-Tokenhinweis
Nachweise (Verifiable Credentials) per verifizierbarer Bereitstellung
Selbst bestätigte Ansprüche

Ausführliche Informationen zu den Eingabetypen finden Sie im Abschnitt Anpassen Ihres Nachweises (Verifiable Credential).

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 Ausstellers des Nachweises.
`logoUrl`	Zeichenfolge	Optional. Die URL für das Logo des Ausstellers.
`termsOfServiceUrl`	Zeichenfolge	Optional. Die URL für die Nutzungsbedingungen für den von Ihnen ausgestellten Nachweis (Verifiable Credential).

Hinweis

Derzeit werden die RequestRegistration Informationen nicht während der Ausstellung in der Microsoft Authentifizierungs-App angezeigt. Diese Informationen können jedoch in der Nutzlast verwendet werden.

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. Die URI muss auf einen erreichbaren Endpunkt im Internet verweisen, andernfalls wird der Dienst den Fehler URL unreadable callback ausgeben. Akzeptierte Formate IPv4, IPv6 oder DNS-auflösbarer 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. Die derzeit unterstützten Kopfzeilenwerte sind die `api-key` oder die `Authorization` Kopfzeilen. Jeder andere Header führt zu einem ungültigen Callback-Header-Fehler

PIN-Typ

Der pin Typ definiert einen PIN-Code, der als Teil der Ausstellung angezeigt werden kann. pin ist optional und sollte bei Verwendung immer bandextern (out-of-band) gesendet werden. Wenn Sie einen HASH-PIN-Code verwenden, müssen Sie die Eigenschaften salt, alg und iterations definieren. pin enthält die folgenden Eigenschaften:

Eigenschaft	Typ	Beschreibung
`value`	Zeichenfolge	Enthält den PIN-Wert in Klartext. Bei Verwendung einer gehashten PINs enthält die Eigenschaft Wert den Salted Hash, base64-kodiert.
`type`	Zeichenfolge	Der Typ des PIN-Codes. Möglicher Wert: `numeric` (Standard).
`length`	integer	Die Länge des PIN-Codes. Die Standardlänge ist 6, der Mindeswert ist 4 und der Höchstwert ist 16.
`salt`	string	Der Salt-Wert des Hash-PIN-Codes. Der Salt wird bei der Hash-Berechnung vorangestellt. Codierung: UTF-8.
`alg`	Zeichenfolge	Der Hashing-Algorithmus für die gehashte PIN. Unterstützter Algorithmus: `sha256`.
`iterations`	integer	Die Anzahl der Hashing-Iterationen. Möglicher Wert: `1`.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 Ausstellungsanforderung und ihre Rückruffunktionen nachverfolgen können.
`url`	Zeichenfolge	Eine URL, mit der die Authenticator-App gestartet wird und der Ausstellungsprozess beginnt. 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`	Zeichenfolge	Ein QR-Code, den der Benutzer scannen kann, um den Ausgabestrom 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 Authentifizierungs-App geöffnet wird und der Ausstellungsprozess beginnt.

Fehlerantwort

Wenn bei der Anforderung ein Fehler auftritt, wird eine Fehlerantwort zurückgegeben, die von der App entsprechend behandelt werden muss.

Callback-Ereignisse

Der Callback-Endpunkt wird aufgerufen, wenn ein Benutzer den QR-Code scannt, den Deep Link seiner Authentifizierungs-App verwendet oder den Ausstellungsprozess 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 für die Anforderung zurückgegebene Status. Mögliche Werte: `request_retrieved`: Der Benutzer hat den QR-Code gescannt oder auf den Link geklickt, der den Ausstellungsablauf startet. `issuance_successful`: Die Ausstellung der Nachweise (Verifiable Credentials) war erfolgreich. `issuance_error`: Bei der Ausstellung ist ein Fehler aufgetreten. Ausführliche Informationen finden Sie unter der `error`-Eigenschaft.
`state`	Zeichenfolge	Gibt den Statuswert zurück, den Sie in den ursprünglichen Nutzdaten übergeben haben.
`error`	error	Wenn der `code` Eigenschaftswert `issuance_error` ist, enthält diese Eigenschaft Informationen über den Fehler.
`error.code`	Zeichenfolge	Der zurückgegebene Fehlercode.
`error.message`	Zeichenfolge	Die Fehlermeldung.

Das folgende Beispiel demonstriert Callback-Nutzdaten, wenn die Anforderung zur Ausstellung durch die Authentifizierungs-App gestartet wird:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Das folgende Beispiel zeigt Callback-Nutzdaten nach erfolgreichem Abschluss des Ausstellungsprozesses durch den Benutzer:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Callback-Fehler

Der Callback-Endpunkt kann mit einer Fehlermeldung aufgerufen werden. Die folgende Tabelle listet die Fehlercodes auf:

`Message`	Definition
`fetch_contract_error`	Der Vertrag über den Nachweis kann nicht abgerufen werden. Dieser Fehler tritt normalerweise auf, wenn die API das Manifest nicht abrufen kann, das in der Nutzlast der Anforderungsdaten RequestIssuance object (Ausstellungsobjekt anfordern) von Ihnen angegeben wurde.
`issuance_service_error`	Der Dienst Nachweise (Verifiable Credentials) kann die Anforderungen nicht überprüfen oder es ist ein Fehler in den Nachweisen (Verifiable Credentials) aufgetreten.
`unspecified_error`	Dieser Fehler ist ungewöhnlich, aber es lohnt sich, ihn zu untersuchen.

Das folgende Beispiel zeigt Callback-Nutzdaten, wenn ein Fehler aufgetreten ist:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
}

Nächste Schritte

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

Teilen über