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

[アーティクル]
10/24/2024

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>

{
    "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 を呼び出すには、次のアクセス許可が必要です。詳細については、「アクセストークンを取得するためのアクセス許可を付与する」を参照してください。

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

提示要求ペイロード

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

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

パラメーター	型	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 解決可能ホスト名です。ネットワークを強化するには、FAQ を参照してください。
`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/00001111-aaaa-2222-bbbb-3333cccc4444/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 を呼び出す方法を確認します。

次の方法で共有

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

HTTP 要求

提示要求ペイロード

RequestRegistration 型

コールバックの種類

RequestCredential 型

Configuration.Validation 型

制約の種類

faceCheck 型

成功応答

エラー応答

コールバックイベント

次の手順

フィードバック

その他のリソース

次の方法で共有

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

HTTP 要求

提示要求ペイロード

RequestRegistration 型

コールバックの種類

RequestCredential 型

Configuration.Validation 型

制約の種類

faceCheck 型

成功応答

エラー応答

コールバック イベント

次の手順

フィードバック

その他のリソース

コールバックイベント