次の方法で共有

要求サービス 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 要求を作成します。

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>

{
    "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 コードが返されます。

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/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 Boolean 省略可能。 この要求の応答に 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 解決可能なホスト名の形式を受け入れます。 ネットワークを強化するには、FAQ を参照してください。
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/00001111-aaaa-2222-bbbb-3333cccc4444/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 を呼び出す方法を確認します。