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

注意

Azure Active Directory の検証可能な資格情報が Microsoft Entra 検証済み ID になり、Microsoft Entra 製品ファミリの一部になりました。 ID ソリューションの Microsoft Entra ファミリの詳細を確認し、統合 Microsoft Entra 管理センターで作業を開始してください。

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://www.contoso.com/api/verifier/presentationCallbac",
    "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: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
        }
      }
    }
  ]
}

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

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

RequestRegistration 型

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

プロパティ Type 説明
clientName string 検証可能な資格情報の発行者の表示名。 この名前は、認証アプリのユーザーに表示されます。

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

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

コールバックの種類

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

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

RequestCredential 型

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

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

Configuration.Validation 型

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

プロパティ Type 説明
allowRevoked Boolean 失効した資格情報を受け入れるかどうかを判断します。 既定値は false です (受け入れません)。
validateLinkedDomain Boolean リンク ドメインを検証するかどうかを判断します。 既定値は false です。 このフラグを false に設定すると、証明書利用者アプリケーションが未検証のリンクされたドメインからの資格情報を受け入れることを意味します。 このフラグを true に設定すると、リンクされたドメインが検証され、検証済みのドメインのみが受け入れられます。

成功応答

成功した場合、このメソッドからは、応答コード (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/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

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

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

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

エラー応答

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

コールバック イベント

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

プロパティ Type 説明
requestId string ペイロードが検証可能な資格情報サービスにポストされるときに、元の要求にマップされます。
requestStatus string 認証アプリによって要求が取得されたときに返される状態。 指定できる値
  • request_retrieved: ユーザーが QR コードをスキャンするか、提示フローを開始するリンクを選択しました。
  • presentation_verified: 検証可能な資格情報の検証が正常に完了しました。
state string 元のペイロードで渡した状態値が返されます。
subject string 検証可能な資格情報ユーザー DID。
issuers 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: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": "..."
      }
    }
    

    次の手順

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