Share via


要求サービス REST API

注意

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

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

API のアクセス トークン

アプリケーションから要求サービス REST API にアクセスできるように、必要なアクセス許可を持つ有効なアクセス トークンを含める必要があります。 Microsoft ID プラットフォームによって発行されたアクセス トークンには、要求サービス REST API で呼び出し元を検証するために使用される情報 (スコープ) が含まれています。 アクセス トークンによって、呼び出し元が要求している操作を実行するための適切なアクセス許可を持っていることが保証されます。

アクセス トークンを取得するには、アプリが Microsoft ID プラットフォームに登録され、要求サービス REST API へのアクセスを管理者によって認可されている必要があります。 "検証可能な資格情報アプリ" のアプリケーションを登録していない場合は、アプリを登録する方法を参照し、アプリケーション シークレットを生成します。

アクセス トークンを取得する

OAuth 2.0 クライアント資格情報の付与フローを使用し、Microsoft ID プラットフォームを使用してアクセス トークンを取得します。 この目的には、信頼されたライブラリを使用します。 このチュートリアルでは、Microsoft Authentication Library (MSAL) を使用します。 MSAL を使用すると、セキュリティで保護された Web API を呼び出せるアプリに認証と承認を簡単に追加できます。

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

前のコードで、次のパラメーターを指定します。

パラメーター 条件 説明
Authority 必須 アプリケーションで操作する対象のディレクトリ テナント。 (例: https://login.microsoftonline.com/{your-tenant})。 (your-tenant は、実際のテナント ID または名前に置き換えます。)
クライアント ID 必須 お使いのアプリに割り当てられたアプリケーション ID。 この情報は、アプリを登録した、Azure portal で確認できます。
クライアント シークレット 必須 アプリ用に生成したクライアント シークレット。
スコープ 必須 3db474b9-6a0c-4840-96ac-1fceb342124f/.default に設定する必要があります。 これにより、VerifiableCredential.Create.Allロール要求が含まれたアクセス トークンが生成されます。

コンソール アプリの ID を使用してアクセス トークンを取得する方法の詳細については、C#PythonNode.jsJava のいずれかの記事を参照してください。

クライアント シークレットではなく、証明書を使用してトークン要求にアクセスすることもできます。

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=12345678-0000-0000-00000000000000000
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

API を呼び出す

検証可能な資格情報を発行または検証するには、次の手順を実行します。

  1. Request Service REST API に対する HTTP POST 要求を作成します。 access_token に要求として存在するため、tenantId はこの URL にはもう必要ありません。

    問題点

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

    確認

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. アクセス トークンをベアラー トークンとして HTTP 要求の Authorization ヘッダーにアタッチします。

    Authorization: Bearer <token>
    
  3. Content-Type ヘッダーを Application/json に設定します。

  4. 発行またはプレゼンテーションの要求ペイロードを準備して、要求本文にアタッチします。

  5. 要求を要求サービス REST API に送信します。

要求サービス API は、呼び出しが成功すると HTTP 状態コード 201 Created を返します。 API 呼び出しでエラーが返される場合は、エラーのリファレンス ドキュメントを確認してください。

発行要求の例

次の例は、検証可能な資格情報の発行要求を示しています。 ペイロードの詳細については、「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://www.contoso.com/api/issuer/issuanceCallback",
        "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
        "headers": {
            "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
        }
    },
    "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDek...",
    "registration": {
        "clientName": "Verifiable Credential Expert Sample"
    },
    "type": "VerifiedCredentialExpert",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

完全なコードについては、次のいずれかのコード サンプルを参照してください。

プレゼンテーション要求の例

次の例は、検証可能な資格情報のプレゼンテーション要求を示しています。 ペイロードの詳細については、「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/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "includeReceipt": true,
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": true,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

完全なコードについては、次のいずれかのコード サンプルを参照してください。

コールバック イベント

要求ペイロードには、発行およびプレゼンテーションのコールバック エンドポイントが含まれています。 エンドポイントは Web アプリケーションの一部であり、HTTPS プロトコルを介して一般公開されている必要があります。 要求サービス API はエンドポイントを呼び出して、特定のイベントについてアプリに通知します。 たとえば、ユーザーが QR コードをスキャンしたり、Authenticator アプリへのディープ リンクを使用したり、プレゼンテーション プロセスを終了したりしたときに、このようなイベントが発生します。

次の図は、要求サービス REST API に対してアプリで行う呼び出しと、アプリケーションへのコールバックを示しています。

API への呼び出しとコールバック イベントを示す図。

受信 HTTP POST 要求をリッスンするようにエンドポイントを構成します。 次のコード スニペットは、発行のコールバック HTTP 要求を処理し、それに応じて UI を更新する方法を示しています。

適用不可。 他のいずれかのプログラミング言語を選択してください。

次の手順

これらの仕様の詳細を学習します。