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

[アーティクル]
01/23/2025

検証可能な資格情報 (VC) の定義は、2 つのコンポーネント、ディスプレイ定義とルール定義で構成されています。表示定義は、資格情報のブランド化と要求のスタイル設定を制御します。ルール定義は、検証可能な資格情報を受け取る前にユーザーが指定する必要がある内容を決定します。

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

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

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

分散型 ID ウォレットである Microsoft Authenticator は、ユーザーに発行された検証可能な資格情報をカードとして表示します。 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 トークン: このオプションを構成する場合は、OpenID Connect 構成 URI を指定し、検証可能な資格情報に含める必要がある要求を含める必要があります。この要件を満たし、関連付けられている要求を自分のアカウントから追加するために、Authenticator アプリで "サインイン" するように求められます。このオプションを構成するには、このをガイドする方法を参照してください。
ID トークンヒント: サンプルアプリとチュートリアルでは、ID トークンヒントを使用します。このオプションが構成されている場合、証明書利用者アプリは、要求サービス API 発行要求の検証可能な資格情報に含める必要がある要求を提供する必要があります。依存アプリが要求を取得する場所はアプリ次第ですが、現在のサインインセッション、バックエンドCRMシステム、あるいはユーザー自身が自己主張した入力から取得することもできます。このオプションを構成するには、このをガイドする方法を参照してください。
検証可能な資格情報: 発行フローの最終的な結果は、検証可能な資格情報を生成することですが、発行するために検証可能な資格情報を提示するようにユーザーに依頼することもできます。ルール定義では、提示された検証可能な資格情報から特定の要求を取得し、それらの要求を組織から新しく発行された検証可能な資格情報に含めることができます。このオプションを構成するには、このをガイドする方法を参照してください。
自己証明要求: このオプションを選択すると、ユーザーは Authenticator に情報を直接入力できます。現時点では、自己証明要求に対してサポートされている入力は文字列だけです。このオプションを構成するには、このをガイドする方法を参照してください。

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

資格タイプ

検証可能なすべての資格情報は、ルール定義で の種類 を宣言する必要があります。資格情報の種類は、検証可能な資格情報スキーマを他の資格情報と区別し、発行者と検証者の間の相互運用性を保証します。資格情報の種類を示すには、資格情報が満たす 1 つ以上の資格情報の種類を指定します。各型は一意の文字列で表されます。多くの場合、URI はグローバル一意性を確保するために使用されます。 URI はアドレス指定可能である必要はありません。文字列として扱われます。たとえば、Contoso University によって発行された学位証明書には、次の種類が含まれる場合があります。

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

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

資格情報の相互運用性を確保するために、関連する組織と緊密に連携して、業界で使用する資格情報の種類、スキーマ、URI を定義することをお勧めします。多くの業界団体は、検証可能な資格情報の内容を定義するために再利用できる公式ドキュメントの構造に関するガイダンスを提供しています。また、資格情報の検証者と密接に連携して、検証可能な資格情報を要求して使用する方法を理解する必要があります。

次の手順

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

次の方法で共有