検証可能な資格情報をカスタマイズする

[アーティクル]
03/15/2024

検証可能な資格情報の定義は、表示定義とルール定義の 2 つのコンポーネントから成ります。表示定義は、資格情報のブランド化とクレームのスタイル設定を制御します。ルール定義は、検証可能な資格情報を受信する前にユーザーが提供する必要があるものを決定します。

この記事では、組織の要件を満たすように両方の種類の定義を変更する方法について説明します。

表示定義: ウォレット資格情報ビジュアル

Microsoft Entra 確認済み ID では、ブランドを反映するために使用できる限定されたオプションのセットが提供されます。この記事では、資格情報をカスタマイズする方法と、ユーザーに発行された後に見栄えの良い資格情報を設計するためのベストプラクティスについて説明します。

Microsoft Authenticator は、分散型の ID ウォレットで、カードとしてユーザーに発行された検証可能な資格情報を表示します。 VC 管理者として、組織のブランドに合わせてカードの色、アイコン、テキスト文字列を選択できます。

Authenticator で検証済み資格情報カードを示すスクリーンショット。主要な要素がコールアウトされています。

カードにはカスタマイズ可能なフィールドも含まれています。このフィールドを使用すると、カードの目的や、カードに含まれる属性などをユーザーに知らせることができます。

資格情報の表示の定義を作成する

表示定義は、ウォレットアプリで検証可能な資格情報の内容を表示する方法を説明する単純な JSON ドキュメントです。

注意

この表示モデルは現在、Microsoft Authenticator でのみ使用されています。

表示の定義の構造を次に示します。 URL として指定する場合、ロゴ URI はインターネットで公開された URL である必要があります。

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png",
        "description": "Verified Credential Expert Logo"
      },
      "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
    },
    "consent": {
      "title": "Do you want to get your Verified Credential?",
      "instructions": "Sign in with your account to get your card."
    },
    "claims": [
      {
        "claim": "vc.credentialSubject.firstName",
        "label": "First name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.lastName",
        "label": "Last name",
        "type": "String"
      }
    ]
}

プロパティの詳細については、「displayModel 型」を参照してください。

ルールの定義: ユーザーから必要とするもの

ルールの定義は、検証可能な資格情報の重要なプロパティを記述する単純な JSON ドキュメントです。具体的には、検証可能な資格情報と資格情報の種類を設定するためにクレームがどのように使用されるかが記載されています。

{
  "attestations": {
      ...
  },
  "validityInterval":  2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

構成証明

現在、ルール定義で構成できる構成証明の種類は次の 4 つです。 Microsoft Entra 確認済み ID 発行サービスによって、検証可能な資格情報に挿入し、その情報を分散化識別子 (DID) で構成証明するために使われるクレームを提供するには、さまざまな方法があります。ルールの定義では、複数の構成証明の種類を使用できます。

ID トークン: このオプションを構成した場合は、Open ID Connect 構成 URI を指定し、検証可能な資格情報に含める必要があるクレームを含める必要があります。ユーザーは、この要件を満たし、関連するクレームをアカウントから追加するために、Authenticator アプリに "サインイン" するよう求められます。このオプションを構成するには、こちらのハウツーガイドを参照してください
ID トークンヒント: サンプルアプリとチュートリアルで、ID トークンヒントを使用します。このオプションを構成した場合は、証明書利用者アプリで、Request Service API 発行要求の検証可能な資格情報に含める必要があるクレームを提供する必要があります。証明書利用者アプリでのクレームの取得元はアプリ次第ですが、現在のサインインセッション、バックエンド CRM システム、またはセルフアサートされたユーザー入力から取得できます。このオプションを構成するには、こちらのハウツーガイドを参照してください
検証可能な資格情報: 発行フローの最終的な結果として、検証可能な資格情報が生成されますが、これを発行するために検証可能な資格情報を提示するようにユーザーに要求することもできます。ルール定義では、提示された検証可能な資格情報から特定のクレームを取得し、組織から新しく発行された検証可能な資格情報にそれらのクレームを含めることができます。このオプションを構成するには、こちらのハウツーガイドを参照してください
自己証明クレーム: このオプションを選択すると、ユーザーは直接 Authenticator に情報を入力できます。現時点では、自己証明クレームでサポートされている唯一の入力は文字列です。このオプションを構成するには、こちらのハウツーガイドを参照してください

ルール JSON モデルの詳細については、「rulesModel 型」を参照してください。

[資格情報の種類]

検証可能な資格情報のすべてにおいて、ルール定義で "type" を宣言する必要があります。資格情報の種類によって、検証可能な資格情報のスキーマが他の資格情報と区別され、発行者と検証者の間の相互運用性が確保されます。資格情報の種類を示すには、資格情報が満たす 1 つまたは複数の資格情報の種類を指定します。それぞれの種類は、一意の文字列で表されます。多くの場合、グローバルな一意性を確保するために URI が使用されます。この場合、アドレス指定可能な URI でなくてもかまいません。文字列として扱われます。例として、Contoso 大学によって発行された卒業証書の資格情報は、次の型を宣言する場合があります。

Type	目的
`https://schema.org/EducationalCredential`	Contoso 大学によって発行された卒業証書に、schema.org の `EducationaCredential` オブジェクトによって定義された属性が含まれていることを宣言します。
`https://schemas.ed.gov/universityDiploma2020`	Contoso 大学によって発行された卒業証書に、米国教育省によって定義された属性が含まれていることを宣言します。
`https://schemas.contoso.edu/diploma2020`	Contoso 大学によって発行された卒業証書に、Contoso 大学によって定義された属性が含まれていることを宣言します。

3 種類の卒業証書を宣言することで、Contoso は検証者からのさまざまな要求を満たす資格情報を発行できます。銀行はユーザーに EducationCredential のセットを要求でき、要求を満たすために卒業証書を使用することができます。または、Contoso 大学の同窓会は、https://schemas.contoso.edu/diploma2020 の種類の資格情報を要求することができ、卒業証書もその要求を満たします。

資格情報の相互運用性を確保するために、関連する組織と密接に連携して、業界で使用する資格情報の種類、スキーマ、および URI を定義することをお勧めします。多くの業界団体では、検証可能な資格情報の内容を定義するために転用できる正式文書の構造に関するガイダンスを提供しています。また、資格情報の検証者と密接に連携して、検証者がどのような意図で、検証可能な資格情報を要求して使用するのかを理解する必要があります。

次のステップ

これで、検証可能な資格情報の設計と、独自の資格情報を作成する方法に関する理解が深まりました。以下も参照してください。

次の方法で共有