Request Service REST API の提示の指定

Microsoft Entra Verified ID には、Request Service REST API が含まれます。 この API を使用すると、資格情報を発行して検証できます。 この記事では、提示要求のための Request Service REST API を指定します。 提示要求を使用すると、ユーザーに検証可能な資格情報の提示を求め、その資格情報を検証することができます。 別の記事では、Request Service REST API を呼び出す方法について説明します。

HTTP 要求

Request Service REST API の提示要求では、次の HTTP メソッドがサポートされています。

Request Service REST API の提示要求では、次の HTTP ヘッダーが必要です。

Request Service REST API に対する HTTP POST 要求を作成します。 access_token に要求として存在するため、tenantId はこの URL にはもう必要ありません。

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

次の HTTP 要求は、Request Service REST API に対する提示要求を示しています。

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

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

Request Service REST API を呼び出すには、次のアクセス許可が必要です。 詳細については、「アクセス トークンを取得するためのアクセス許可を付与する」を参照してください。

提示要求ペイロード

提示要求ペイロードには、検証可能な資格情報の提示要求に関する情報が含まれています。 次の例は、特定の発行者からの提示要求を示しています。 この要求の結果として、提示プロセスを開始するためのリンクを含む QR コードが返されます。

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "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
        }
      }
    }
  ]
}

ペイロードには、次のプロパティが含まれます。

RequestRegistration 型

RequestRegistration 型により、発行者の情報登録が提供されます。 RequestRegistration 型には次のプロパティが含まれます。

次のスクリーンショットは、提示要求の clientName プロパティと authority (検証者) の表示名を示しています。

コールバックの種類

Request Service REST API により、コールバック エンドポイントに対する複数のイベントが生成されます。 それらのイベントを使用すると、UI を更新し、結果がアプリケーションに返されたらプロセスを続行できます。 Callback 型には次のプロパティが含まれます。

RequestCredential 型

RequestCredential により、ユーザーが指定する必要のある要求された資格情報に関する情報が提供されます。 RequestCredential には次のプロパティが含まれます。

Configuration.Validation 型

Configuration.Validation により、提示された資格情報を検証する方法に関する情報が提供されます。 以下のプロパティを含みます。

Constraints 型

constraints 型には、ウォレットで候補の資格情報を選択する際に満たす必要がある要求制約のコレクションが含まれます。 これにより、特定の要求値を持つ資格情報を要求できるようになります。 制約を指定する場合は AND ロジックを使用します。つまり、3 つの制約を指定した場合は、それらがすべて満たされる必要があります。 コレクション内の制約ごとに、値のオペランド (contains または startsWith) を 1 つ選択する必要があります。 値を正規表現にすることはできません。 すべての比較において大文字と小文字を区別しません。

faceCheck 型

faceCheck 型には、資格情報の提示中にライブネス チェックを実行するための情報が含まれています。 要求された資格情報の、sourcePhotoClaimName で指定された要求には、所有者の写真が含まれている必要があります。 ライブネス チェックが、プロパティ matchConfidenceThreshold で指定されているもの以上の信頼度レベルに達した場合、提示は成功します。 しきい値を満たさない場合、提示全体が失敗します。

成功応答

成功した場合、このメソッドからは、応答コード (HTTP 201 Created) と、応答本文内のイベント オブジェクトのコレクションが返されます。 次の JSON は、成功した応答を示しています。

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

応答には次のプロパティが含まれます。

アプリで応答を受信したら、QR コードをユーザーに提示する必要があります。 ユーザーが QR コードをスキャンすると、認証アプリが開き、提示プロセスを開始されます。

エラー応答

要求でエラーが発生した場合は、エラー応答が返され、アプリで適切に処理する必要があります。

コールバック イベント

ユーザーが QR コードをスキャンするか、認証アプリのディープ リンクを使用するか、提示プロセスを完了すると、コールバック エンドポイントが呼び出されます。

次の例は、認証アプリが提示要求を開始するときのコールバック ペイロードを示しています。

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

次の例は、検証可能な資格情報の提示が正常に完了した後のコールバックのペイロードを示しています。

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

次のステップ

Request Service REST API を呼び出す方法を確認します。