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

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

HTTP 要求

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

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

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

発行要求のペイロード

発行要求のペイロードには、検証可能な資格情報の発行要求に関する情報が含まれています。 次の例では、姓や名などのユーザー クレームを含む 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"
}

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

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

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

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

RequestRegistration 型

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

コールバックの種類

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

PIN の種類

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

成功応答

成功した場合、このメソッドからは、応答コード (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>"  
} 

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

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

エラー応答

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

コールバック イベント

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

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

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

コールバック エラー

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

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

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