要求サービス REST API の発行の指定

[アーティクル]
02/28/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 要求を作成します。

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

次の HTTP 要求では、Request Service 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"
        }
    },
    ...
}

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

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

発行要求のペイロード

発行要求のペイロードには、検証可能な資格情報の発行要求に関する情報が含まれています。次の例では、姓や名などのユーザークレームを含む PIN コードフローを使用し、発行要求を示します。この要求の結果では、発行プロセスを開始するためのリンクを含む QR コードが返されます。

{
  "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/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

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

パラメーター	型	Description
`includeQRCode`	ブール型	この要求の応答に QR コードを含まれるかどうかを決定します。 QR コードを提示し、ユーザーにそれをスキャンするよう指示します。 QR コードをスキャンすると、この発行要求で認証アプリが起動されます。指定できる値は、`true` (既定値) または `false`です。値を `false` に設定したら、戻された `url` プロパティを使用してディープリンクを表示します。
`callback`	Callback	必須。検証可能な資格情報の発行プロセスの間に、開発者がフローに関する情報を非同期に取得できるようにします。たとえば、ユーザーが QR コードをスキャンしたとき、または発行要求が成功または失敗した場合に、開発者が呼び出しを必要とすることがあります。
`authority`	string	発行者の分散化識別子 (DID)。詳細については、「資格情報と環境の詳細を収集して、サンプルアプリケーションを設定する」を参照してください。
`registration`	RequestRegistration	認証アプリに表示できる発行者に関する情報を提供します。
`type`	string	検証可能な資格情報の種類。検証可能な資格情報のマニフェストで定義されている種類と一致している必要があります。例: `VerifiedCredentialExpert`。詳細については、「Azure で検証された資格情報エキスパートカードを作成する」を参照してください。
`manifest`	string	検証可能な資格情報のマニフェストドキュメントの URL。詳細については、「資格情報と環境の詳細を収集して、サンプルアプリケーションを設定する」を参照してください。
`claims`	string	省略可能。 ID トークンヒント構成証明フローでのみ使用でき、検証可能な認証情報内のサブジェクトに関して行われたアサーションのコレクションを含めることができます。
`pin`	PIN	省略可能。 PIN コードは、ID トークンヒントの構成証明フローでのみ使用できます。発行の間に追加のセキュリティを提供するための PIN 番号。 PIN コードを生成し、アプリのユーザーにそれを提示します。ユーザーは、生成した PIN コードを提供する必要があります。
`expirationDate`	string	省略可能。 expirationDate は、ID トークンヒントの構成証明フローでのみ使用できます。指定する場合、値は ISO8601 形式で表される日付である必要があります。日付は、この発行要求の資格情報規則定義の validityInterval をオーバーライドします。この設定を使用すると、発行日時に関係なく、資格情報の有効期限 (1 日の終わり、月末、年末など) を明示的に制御できます。日付は UTC 形式で表されることに注意してください。年末を指定し、時刻を `23:59:59` に設定すると、UTC 時刻の真夜中の 1 秒前になります。別のタイムゾーンのユーザーは、Microsoft Authenticator のローカルタイムゾーンに表示される有効期限を取得します。つまり、CET タイムゾーンにいるユーザーは、1 月 1 日の午前 1 時として表示されます。資格情報コントラクトでは、フラグ allowOverrideValidityOnIssuance を true に設定する必要があります。

現在、ペイロードで送信できる要求構成証明の種類は 4 つあります。 Microsoft Entra 確認済み ID では、4 つの方法を使用して検証可能な資格情報に要求を挿入し、発行者の DID でその情報を証明します。 4 つの種類は、次の通りです。

ID トークン
ID トークンヒント
検証可能なプレゼンテーションを使用した検証可能な資格情報
自己証明クレーム

入力の種類の詳細については、検証可能な資格情報のカスタマイズに関する記事を参照してください。

RequestRegistration 型

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

プロパティ	タイプ	説明
`clientName`	string	検証可能な資格情報の発行者の表示名。
`logoUrl`	string	省略可能。発行者のロゴの URL。
`termsOfServiceUrl`	string	省略可能。発行する検証可能な資格情報の使用条件の URL。

注意

現時点では、RequestRegistration の情報は、Microsoft Authenticator アプリでの発行中に提示されません。ただし、この情報は、ペイロードで使用できます。

コールバックの種類

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

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

PIN の種類

pin 型は、発行の一部として表示できる PIN コードを定義します。 pin は省略可能であり、使用する場合は、常に帯域外で送信される必要があります。 HASH PIN コードを使用する場合は、salt、alg、iterations の各プロパティを定義する必要があります。 pin には次のプロパティが含まれます。

プロパティ	タイプ	説明
`value`	string	プレーンテキストで PIN の値を格納します。ハッシュされた PIN を使用している場合、value プロパティには、base64 でエンコードされたソルト化されたハッシュが含まれます。
`type`	string	PIN コードの型。指定できる値: `numeric` (既定値)。
`length`	整数 (integer)	PIN コードの長さ。既定の長さは 6、最小値は 4、最大値は 16 です。
`salt`	string	ハッシュされた PIN コードのソルト。ソルトは、ハッシュ計算中に先頭に付加されます。エンコード: UTF-8。
`alg`	string	ハッシュ化された PIN のハッシュアルゴリズム。サポートされるアルゴリズム: `sha256`。
`iterations`	整数 (integer)	ハッシュの反復の数。指定できる値: `1`。

成功応答

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

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 コードをスキャンするか、発行フローを開始するリンクを選択しました。 `issuance_successful`: 検証可能な資格情報の発行が成功しました。 `issuance_error`: 発行中にエラーが発生しました。詳細については、`error` プロパティを参照してください。
`state`	string	元のペイロードで渡した状態値が返されます。
`error`	error	`code` プロパティ値が `issuance_error` の場合、このプロパティにはエラーに関する情報が含まれます。
`error.code`	string	戻りエラーコード。
`error.message`	string	エラーメッセージ。

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

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

次の例では、ユーザーが発行プロセスを正常に完了した後のコールバックのペイロードを示します。

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

コールバックエラー

コールバックエンドポイントは、エラーメッセージと一緒に呼び出される場合があります。次の表に、エラーコードの一覧を示します。

メッセージ	定義
`fetch_contract_error`	検証可能な資格情報のコントラクトをフェッチできません。このエラーは、通常、要求のペイロードの RequestIssuance オブジェクトで指定されているマニフェストを API でフェッチできない場合に発生します。
`issuance_service_error`	検証可能な資格情報サービスは、要件を検証できないか、検証可能な資格情報で問題が発生しました。
`unspecified_error`	このエラーは一般的ではありませんが、調査する価値があります。

次の例では、エラーが発生したときのコールバックのペイロードを示します。

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

次の手順

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