要求サービス REST API の提示の指定

  • [アーティクル]

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

HTTP 要求

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

メソッド メモ
POST この記事で指定されているように、JSON ペイロードを使用します。

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

方法 値
Authorization アクセス トークンをベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチします。 たとえば、「 Authorization: Bearer <token> 」のように入力します。
Content-Type Application/json

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>

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

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

アクセス許可の種類 アクセス許可
Application 3db474b9-6a0c-4840-96ac-1fceb342124f/.default

提示要求ペイロード

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

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

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

パラメーター 型 Description
includeQRCode Boolean 省略可能。 この要求の応答に QR コードを含まれるかどうかを決定します。 QR コードを提示し、ユーザーにそれをスキャンするよう指示します。 QR コードをスキャンすると、この提示要求で認証アプリが起動されます。 指定できる値は、true (既定値) または falseです。 値を false に設定したら、戻された url プロパティを使用してディープ リンクを表示します。
includeReceipt ブール型 省略可能。 この要求の応答に受信確認を含めるかどうかを決定します。 指定できる値は true または false (既定値) です。 受信確認には、認証子から検証可能な資格情報サービスに送信された元のペイロードが含まれます。 受信確認は、トラブルシューティングやペイロードの詳細を取得する必要がある場合に役立ちます。 それ以外の場合は、この値を true に設定する必要はありません。 OpenId Connect SIOP 要求の場合、受信確認には元の要求の ID トークンが含まれます。
authority string 検証者の Microsoft Entra テナントの分散型識別子 (DID) です。 詳細については、「テナントの詳細を収集してサンプル アプリケーションを設定する」を参照してください。
registration RequestRegistration 検証者に関する情報を提供します。
callback Callback 必須。 検証可能な資格情報の提示プロセス中に、開発者が UI を更新できるようにします。 ユーザーがこのプロセスを完了して、結果がアプリケーションに返されたら、プロセスを続行します。
requestedCredentials collection RequestCredential オブジェクトのコレクション。

RequestRegistration 型

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

プロパティ タイプ 説明
clientName string 検証可能な資格情報の検証者の表示名。 この名前は、認証アプリのユーザーに表示されます。
purpose string 省略可能。 検証可能な資格情報が要求されている理由をユーザーに通知するために表示される文字列。
logoUrl URL 省略可能。 検証者のロゴタイプの URL。 これは Authenticator アプリでは使用されません。
termsOfServiceUrl URL 省略可能。 検証者のサービス使用条件への URL。 これは Authenticator アプリでは使用されません。

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

提示要求を承認する方法を示すスクリーンショット。

コールバックの種類

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

プロパティ タイプ 説明
url string アプリケーションのコールバック エンドポイントへの URI。 この URI は、インターネット上の到達可能なエンドポイントを指している必要があります。そうでない場合、サービスによって、コールバック URL 読み取り不可エラーがスローされます。 受け入れられる入力は IPv4、IPv6、または DNS 解決可能ホスト名です。
state string コールバック イベントを、元のペイロードで渡された状態と関連付けます。
headers string 省略可能。 POST メッセージの受信側で必要な HTTP ヘッダーのコレクションを含めることができます。 現在サポートされているヘッダー値は、api-key または Authorization ヘッダーです。 その他のヘッダーでは、無効なコールバック ヘッダー エラーがスローされます。

RequestCredential 型

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

プロパティ タイプ 説明
type string 検証可能な資格情報の種類。 type は、issuer の検証可能な資格情報のマニフェスト (VerifiedCredentialExpert など) で定義されている種類と一致している必要があります。 発行者マニフェストを取得するには、「資格情報と環境の詳細を収集してサンプル アプリケーションを設定する」をご覧ください。 [Issue credential URL](資格情報 URL の発行) をコピーして Web ブラウザーで開き、id プロパティを確認します。
purpose string 省略可能。 この検証可能な資格情報を要求する目的についての情報を提供します。 これは Authenticator アプリでは使用されません。
acceptedIssuers 文字列コレクション 省略可能。 サブジェクトで提示できる検証可能な資格情報の種類を発行できる発行者の DID のコレクション。 発行者 DID を取得するには、「資格情報と環境の詳細を収集してサンプル アプリケーションを設定する」を参照し、分散型識別子 (DID) の値をコピーします。 acceptedIssuers コレクションが空であるか存在しない場合、提示要求では発行者によって発行された資格情報の種類を受け入れます。
configuration.validation Configuration.Validation プレゼンテーション検証のオプション設定。
constraints 制約 省略可能。 クレーム制約のコレクション。

Configuration.Validation 型

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

プロパティ タイプ Description
allowRevoked Boolean 省略可能。 失効した資格情報を受け入れるかどうかを判断します。 既定値は false です (受け入れません)。
validateLinkedDomain Boolean 省略可能。 リンク ドメインを検証するかどうかを判断します。 既定値は false です。 このフラグを false に設定すると、証明書利用者アプリケーションが未検証のリンクされたドメインからの資格情報を受け入れることを意味します。 このフラグを true に設定すると、リンクされたドメインが検証され、検証済みのドメインのみが受け入れられます。
faceCheck faceCheck 省略可能。 提示中にライブネス チェックを要求できるようにします。

制約の種類

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

プロパティ タイプ 説明
claimName string 必須。 制約におけるクレームの名前。 これは、検証可能な資格情報の要求名です。 claimMapping 型の outputClaim を参照してください。
values 文字列コレクション クレーム値と一致する必要がある値のセット。 ["red"、"green"、"blue"] などの複数の値を指定した場合、資格情報内のクレーム値に当該コレクション内の値のいずれかが含まれている場合は一致となります。
contains string 指定した値がクレーム値に含まれている場合、制約は true と評価されます。
startsWith string 指定した値でクレーム値が始まる場合、制約は true に評価されます。

faceCheck 型

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

プロパティ タイプ 説明
sourcePhotoClaimName string 必須。 写真を含む資格情報の要求の名前。 claimMapping 型の outputClaim を参照してください。
matchConfidenceThreshold integer 省略可能。 写真とライブネス データの間で正常にチェックを行うための機密しきい値。 50 から 100 までの整数にする必要があります。 既定値は 70 です。

成功応答

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

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

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

プロパティ タイプ 説明
requestId string 自動生成された要求 ID。 コールバックは同じ要求を使用し、提示要求とそのコールバックを追跡できるようにします。
url string 認証アプリを起動し、提示プロセスを開始する URL。 ユーザーが QR コードをスキャンできない場合は、この URL を提示できます。
expiry 整数 (integer) 応答の有効期限がいつ切れるかを示します。
qrCode string ユーザーがスキャンして提示フローを開始することができる QR コード。

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

エラー応答

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

コールバック イベント

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

プロパティ タイプ 説明
requestId string ペイロードが検証可能な資格情報サービスにポストされるときに、元の要求にマップされます。
requestStatus string 認証アプリによって要求が取得されたときに返される状態。 設定可能な値:
  • request_retrieved: ユーザーが QR コードをスキャンするか、提示フローを開始するリンクを選択しました。
  • presentation_verified: 検証可能な資格情報の検証が正常に完了しました。
    • li>presentation_error提示にエラーがありました。
state string 元のペイロードで渡した状態値が返されます。
subject string 検証可能な資格情報ユーザー DID。
verifiedCredentialsData array 要求された検証可能な資格情報の配列を返します。 検証可能な資格情報ごとに、以下が提供されます。
  • 検証可能な資格情報の種類。
  • 発行者の DID
  • 取得された要求。
  • 検証可能な資格情報の発行者のドメイン。
  • 検証可能な資格情報の発行者のドメイン検証状態。
    • receipt string 省略可能。 受信確認には、ウォレットから検証可能な資格情報サービスに送信された元のペイロードが含まれます。 受信確認は、トラブルシューティング/デバッグにのみ使用される必要があります。 受信確認の形式は修正されません。使用されているウォレットとバージョンに基づいて変更できます。

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

    {
    "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 を呼び出す方法を確認します。