Microsoft Entra Verified ID を使ってみた（③検証編） #Azure

前回の記事でVerified IDを使ったデジタル証明書の発行を行いましたが、今回は発行した証明書を検証していきます。

Microsoft Entra Verified ID を使ってみた（②発行編）

コードは Microsoft 公式で公開されているこちらを参考にしております。

前提条件

アプリケーションの動作環境は、前回の記事同様とします。
Verified IDの環境構築は完了しているものとします。
- 環境構築についてはこちらの記事をご参照ください。
既に前回の記事の証明書発行でデジタル証明書が発行されているものとします。

ソースコード

全体のソースコードはこちらのGitHubに公開いたしました。

今回Frontend, Backendの2つの実装をご紹介しますが、下記のそれぞれ下記のディレクトリ直下をご参照ください。

Backend：backendディレクトリ
Frontend：frontendディレクトリ

まずは動かしてみる

Frontendの起動

下記コマンドを実行し、Frontendを起動します。

ライブラリのインストール
```
> npm ci
```
実行
```
> ng serve --open
```

動作確認

Frontendが起動したら、自動的にhttp://localhost:4200/にアクセスされます。

アプリケーション起動時、このようなメイン画面が表示されるため証明書の検証をしてみます。

証明書検証

証明書の検証を動かしてみます。

証明書の検証画面を開くと、このようにQRコードが表示されます。発行時と同様にQRコードをモバイル端末のカメラアプリやMicrosoft Authenticatorで読み取ります。
QRコードを読み取るとAuthenticatorで「Verifiable Credentials Expart Verifierと共有しますか？」と表示されるため、共有します。
証明書の検証が完了します。アプリケーションの画面では、証明書に記載されている氏名が表示されます。

デジタル証明書検証ページ

この画面では証明書発行ページで発行された証明書を検証します。

発行ページ同様にページにステータスを持たせ、Backendから返却されたステータスによってQRコードや証明書検証完了などの表示切り替えを行います。

証明書検証ページにアクセスすると、Backendの証明書検証のリクエストAPIを呼び出します。
BackendからURL等が返却されたら、URLをもとにQRコードを生成し表示します。
証明書検証のステータス取得API を定期的に呼び出し、「QR 読み取り中」や「検証完了」などのステータスに応じて QR コード表完了表示などに切り替えます。

証明書検証の概要

デジタル証明書の検証は下記の流れで行われます。ほとんど証明書の発行と同じで、違いはユーザー属性の入力やPINが無くなったくらいです。

ユーザーはデジタル証明書検証のリクエストを依頼します。
Verified ID はアプリケーションへ URL を返却し、アプリケーションはそれを元に QR コードを表示します。
ユーザーは QR コードを読み取り、デジタル証明書の検証を許可します。
Verified ID は QR コードが読み取り、デジタル証明書の検証が許可されたことをアプリケーションへ通知し、アプリケーションはデジタル証明書の検証が完了したことを画面表示します。

実装のポイント（Backend）

Backendでは、下記のAPIを作成しています。

証明書検証コントローラー
- 証明書検証のリクエストAPI
- Verified IDからコールバックされた時のAPI
- 証明書検証のステータス取得API

ポイントとしては証明書の発行 or 検証がまだ途中なのか、完了したのかといった状態をメモリキャッシュで保管しておき、都度この値を更新しています。

証明書検証コントローラー

基本的に証明書発行とソースコードは変わりませんが、Verified IDのAPIの仕様が少し異なってきます。

証明書検証のリクエストAPI

Verified IDの証明書検証APIを呼び出します。
- 詳細：Presentation request payload
- APIのURLは下記の通りです。
  - POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
- Request Bodyのcallback等は発行のAPIと同じですが、PINの要素が無くなりrequestedCredentialsという項目が追加されています。
- APIの呼び出し成功すると、URLや有効期限が返却されます。形式は証明書発行のAPIと同じです。
  - 詳細：Successful response
メモリキャッシュについても証明書の発行同様に、stateをキーに持たせておきます。

Verified IDからコールバックされた時のAPI

ユーザーがAuthenticatorでの操作を行ったタイミングで、Verified APIからBackendへコールバックがされます。
- 詳細：Callback events
- requestStatusについてはこのような値になります。
  - QRコードが読み取られたとき：request_retrieved
  - 証明書が承認されたとき：presentation_verified
- 証明書発行と大きく異なる点としては、証明書検証が承認されたときのコールバックの内容です。
  - verifiedCredentialsDataが返され、その中のclaims要素に証明書に登録したIDや氏名があります。

このAPIでは、下記の通りコールバックされたときにrequestStatusの値によってメモリ内の状態を更新します。

// ①QRコードが読み取られた時は「request_retrieved」が返される
if (presentationCallback.RequestStatus == "request_retrieved")
{
    var cacheData = new CacheData
    {
        Status = "request_retrieved",
        Message = "QR Code is scanned. Waiting for validation...",
    };
    Cache.Set(state, JsonConvert.SerializeObject(cacheData));
}

// ②証明書が承認された時は「presentation_verified」が返される
if (presentationCallback.RequestStatus == "presentation_verified")
{
    var cacheData = new CacheData
    {
        Status = "presentation_verified",
        Message = "Presentation verified",
        FirstName = presentationCallback.VerifiedCredentialsData!.First().Claims.FirstName,
        LastName = presentationCallback.VerifiedCredentialsData!.First().Claims.LastName,

        ...
    };
    Cache.Set(state, JsonConvert.SerializeObject(cacheData));
}

証明書検証のステータス取得API

このAPIではメモリ内の状態を参照し、ステータスを返します。

証明書検証が完了したときに氏名を画面に表示するには、ステータスがpresentation_verifiedの場合は氏名も加えて返すようにします。

if (Cache.TryGetValue(state, out string buf))
{
    var cacheData = JsonConvert.DeserializeObject<CacheData>(buf);

    if (cacheData != null)
    {
        var result = new PresentationResponseViewModel
        {
            Status = cacheData.Status,
            Message = cacheData.Message
        };

        if (!string.IsNullOrEmpty(cacheData.Expiry))
        {
            result.Expiry = cacheData.Expiry;
        }

        if (cacheData.Status == "presentation_verified")
        {
            result.LastName = cacheData.LastName;
            result.FirstName = cacheData.FirstName;
            ...
        }

        return result;
    }
}

まとめ

デジタル証明書の発行と同様に、いくつかのAPIを呼び出すだけで簡単に検証もできます。

次回は、デジタル証明書の見た目についてのカスタマイズをしていきたいと思います。

参考資料

サンプルコード
- Microsoft公式GitHub
公式リファレンス
- Issuance request payload
  - 証明書発行のAPIリクエスト

Microsoft Entra Verified ID を使ってみた（③検証編）