検証可能な資格情報の管理 API

Microsoft Entra 確認済み ID の管理 API を使用すると、検証可能な資格情報サービスのすべての側面を管理できます。 新しいサービスの設定、検証可能な資格情報のコントラクトの管理と作成、検証可能な資格情報の取り消し、サービスの完全なオプトアウトを行う方法も提供されます。

ベース URL

管理 API は HTTPS 経由でサービスを提供します。 ドキュメントで参照されているすべての URL は、次をベースとします: https://verifiedid.did.msidentity.com。

認証

API は Microsoft Entra ID を介して保護され、OAuth2 ベアラー トークンを使用します。 アクセス トークンは、ユーザー用またはアプリケーション用にすることができます。

ユーザー ベアラー トークン

アプリの登録には Verifiable Credentials Service Admin に対する API のアクセス許可が必要で、アクセス トークンを取得するときに、アプリはスコープ 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access を使用する必要があります。 アクセス トークンは、認証ポリシー管理者の ロールを持つユーザー用である必要があります。 全体管理者 ロールにもこれらのアクセス許可がありますが、他のロールの組み合わせがニーズを満たしていない場合にのみ使用してください。 ロール グローバル閲覧者を持つユーザーは、読み取り専用 API 呼び出しを実行できます。

アプリケーション ベアラー トークン

Verifiable Credentials Service Admin サービスでは、次のアプリケーションのアクセス許可がサポートされています。

アプリの登録には、Verifiable Credentials Service Admin の API アクセス許可と、テーブルから必要なアクセス許可が必要です。 アプリがアクセス トークンを取得すると、クライアント資格情報フロー経由で、アプリはスコープ 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.defaultを使用する必要があります。

アプリが新しい機関を作成する場合は、必要なものが 2 つあります。 まず、アプリの登録には VerifiableCredential.Authority.ReadWrite アクセス許可が必要です。 次に、アプリには Key Vault アクセス ポリシーの Create Key アクセス許可が必要です。 アプリが既存の機関のみを読み取り/書き込みする場合、Key Vault のアクセス許可は必要ありません。

オンボード

この API は新しい環境を作成するのに役立ち、新しい機関を設定できます。 このプロセスは、Azure portal の [検証可能な資格情報] ページにも移動することで、手動でトリガーできます。 この API は 1 回だけ呼び出す必要があり、この API でまったく新しい環境を設定する場合にのみ必要です。

HTTP 要求

POST /v1.0/verifiableCredentials/onboard

このエンドポイントを使用して、テナントでの検証可能な資格情報サービスのプロビジョニングを完了します。 サービス プリンシパルがまだプロビジョニングされていない場合は、残りのサービス プリンシパルが作成されます。

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
    "verifiableCredentialServicePrincipalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
    "verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
    "status": "Enabled"
}

この API を繰り返し呼び出すと、まったく同じ応答メッセージが返されます。

機関

このエンドポイントを使用して、検証可能な資格情報サービス インスタンスを作成または更新できます。

メソッド

権限を取得する

構成された機関または検証可能な資格情報サービス インスタンスのプロパティを取得します。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/<authorityId>

構成されているいずれかの機関の値で <authorityId> を置き換えます。

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください

応答メッセージ

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "ExampleAuthorityName",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vccontosokv",
        "resourceUrl": "https://vccontosokv.vault.azure.net/"
    }
}

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

機関の種類

didModel 型

ウェブ

keyVaultMetadata 型

権限の一覧表示

このテナントに対して構成されているすべての機関または検証可能な資格情報サービスを取得します

HTTP 要求

GET /v1.0/verifiableCredentials/authorities

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

応答メッセージは、Authorities の配列です

例:

HTTP/1.1 200 OK
Content-type: application/json
{
    "value": [
        {
            "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "name": "AuthorityName",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid.contoso.com/"
                ],
                "didDocumentStatus": "published"
            },
            "keyVaultMetadata": {
                "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
                "resourceGroup": "verifiablecredentials",
                "resourceName": "vccontosokv",
                "resourceUrl": "https://vccontosokv.vault.azure.net/"
            }
        },
        {
            "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "name": "AuthorityName2",
            "keyVaultUrl": "https://vccontosokv.vault.azure.net/",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid2.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid2.contoso.com/"
                ],
                "didDocumentStatus": "published"
            },
            "keyVaultMetadata": {
                "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
                "resourceGroup": "verifiablecredentials",
                "resourceName": "vccontosokv",
                "resourceUrl": "https://vccontosokv.vault.azure.net/"
            }
        }
    ]
}

権限の作成

この呼び出しにより、新しい 秘密キー が作成され、指定された Azure Key Vault にキーが格納され、検証可能な資格情報サービスに対するこの Key Vault へのアクセス許可が設定され、対応する DID ドキュメントを使用して新しい DID が作成されます。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities

要求ヘッダー

要求本文

要求本文で、次を使用して JSON 表現を指定します

メッセージ例:

{
  "name":"ExampleName",
  "linkedDomainUrl":"https://verifiedid.contoso.com/",
  "didMethod": "web",
  "keyVaultMetadata":
  {
    "subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroup":"verifiablecredentials",
    "resourceName":"vccontosokv",
    "resourceUrl": "https://vccontosokv.vault.azure.net/"
  }
}

応答メッセージ

成功した場合、応答メッセージには機関の名前が含まれます

did:web のメッセージ例:

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

did:ion のメッセージ例:

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "APItest6",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "submitted"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vccontosokv",
        "resourceUrl": "https://vccontosokv.vault.azure.net/"
    }
}

解説

独自の DID キーと秘密キーを使用して複数の機関を作成できますが、これらは Azure portal の UI には表示されません。 現在、1 つの機関のみをサポートしています。 複数の機関が作成されたすべてのシナリオを完全にはテストしていません。 これを試す場合は、その経験を是非お知らせください。

機関を更新します

このメソッドを使用して、検証可能な資格情報サービスのこの特定のインスタンスの表示名を更新できます。

HTTP 要求

PATCH /v1.0/verifiableCredentials/authorities/<authorityId>

更新する機関 ID の値に <authorityId> の値を置き換えます。

要求ヘッダー

要求本文

要求本文で、次を使用して JSON 表現を指定します。

メッセージ例:

{
  "name":"ExampleIssuerName"
}

機関を削除します

このメソッドを使用して、機関を削除できます。 現在、削除できるのは did:ion 機関だけです。 機関を削除すると、発行された検証済み ID 資格情報は無効になり、発行元の機関がなくなったので検証できなくなります。

HTTP 要求

DELETE /beta/verifiableCredentials/authorities/<authorityId>

削除する機関 ID の値に <authorityId> の値を置き換えます。

要求ヘッダー

要求本文

要求本文はありません

応答メッセージ

応答メッセージの例:

権限の削除応答が成功しました。

HTTP/1.1 200 OK

機関の削除が成功したが、Azure Key Vault キーのクリーンアップが失敗した場合、この応答が返されます。

HTTP/1.1 400 Bad Request
Content-type: application/json

{
"error": {
        "code": "deleteIssuerSuccessfulButKeyDeletionFailed",
        "message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
    }
}

既知の DID 構成

generateWellknownDidConfiguration メソッドは、署名された did-configuration.json ファイルを生成します。 このファイルは、この検証可能な資格情報インスタンスのリンクされたドメインでホストされている Web サイトのルートにある .well-known フォルダーにアップロードする必要があります。 手順はこちらで確認できます

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/generateWellknownDidConfiguration

要求ヘッダー

要求本文

指定した機関の linkedDomains 内のいずれかのドメインを指定する必要があります。

{
    "domainUrl":"https://atest/"
}

応答メッセージ

応答メッセージの例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbGciOiJFUzI1NksiL...<SNIP>..."
    ]
}

この結果をファイル名 did-configuration.json で保存し、このファイルを正しいフォルダーと Web サイトにアップロードします。 この DID/DID ドキュメントにリンクされていないドメインを指定すると、次のエラーが表示されます。

HTTP/1.1 400 Bad Request
Content-type: application/json

{
  "requestId":"079192a95fbf56a661c1b2dd0e012af5",
  "date":"Mon, 07 Feb 2022 18:55:53 GMT",
  "mscv":"AVQh55YiU3FxMipB.0",
  "error":
  {
    "code":"wellKnownConfigDomainDoesNotExistInIssuer",
    "message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
  }
}

解説

複数の DID を同じドメインに指定できます。 この構成を選択した場合は、生成されたトークンを組み合わせて、同じ did-configuration.json ファイルに格納する必要があります。 ファイルには、これらのトークンの配列を含めます。

次に例を示します。

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbG..token1...<SNIP>...",
        "eyJhbG..token2...<SNIP>..."
    ]
}

DID ドキュメントを生成する

この呼び出しによって、DID:WEB 識別子に使用される DID ドキュメントが生成されます。 サービスが DID ドキュメントを生成した後、管理者はファイルを https://domain/.well-known/did.json の場所に配置する必要があります。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/generateDidDocument

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "did:web:verifiedid.contoso.com",
    "@context": [
        "https://www.w3.org/ns/did/v1",
        {
            "@base": "did:web:verifiedid.contoso.com"
        }
    ],
    "service": [
        {
            "id": "#linkeddomains",
            "type": "LinkedDomains",
            "serviceEndpoint": {
                "origins": [
                    "https://verifiedid.contoso.com/"
                ]
            }
        },
        {
            "id": "#hub",
            "type": "IdentityHub",
            "serviceEndpoint": {
                "instances": [
                    "https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
                ]
            }
        }
    ],
    "verificationMethod": [
        {
            "id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
            "controller": "did:web:verifiedid.contoso.com",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyJwk": {
                "crv": "secp256k1",
                "kty": "EC",
                "x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
                "y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
            }
        }
    ],
    "authentication": [
        "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
    ],
    "assertionMethod": [
        "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
    ]
}

注記

呼び出し元に、ターゲット キー コンテナーに対する KEY List アクセス許可が必要です。

既知の DID 構成を検証する

この呼び出しでは、DID セットアップが確認されます。 既知の DID 構成がダウンロードされ、DID と署名が検証されます。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/validateWellKnownDidConfiguration

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

HTTP/1.1 204 No Content
Content-type: application/json

署名キーのローテーション

Rotate 署名キーは、did:web 機関用の新しい秘密キーを作成します。 更新を反映するため、DID ドキュメントを再登録する必要があります。 再登録が完了すると、synchronizeWithDidDocument は、署名に新しいキーの使用を開始するようシステムに指示します。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/didInfo/signingKeys/rotate

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

didDocumentStatus が outOfSyncに変わります。

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "outOfSync"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

署名キーを作成する

作成 署名キーは、did:web 機関の既存の Key Vault に新しい秘密キーを作成します。 権限の didDocumentStatus が outOfSyncに変更された場合、DID ドキュメントを再登録して更新を反映する必要があります。 DID ドキュメントが再登録されたら、synchronizeWithDidDocument 呼び出、署名に新しいキーの使用を開始するようにシステムに指示します。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys

要求ヘッダー

要求本文

{
	"signingKeyCurve": "P-256"
}

応答メッセージ

HTTP/1.1 200 OK
Content-type: application/json

{
	"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
	"keyUrl": "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407",
	"curve": "P-256"
}

DID ドキュメントと同期する

署名キーのローテーション後、更新を反映するため、DID ドキュメントを再登録する必要があります。 プロセスが完了すると、synchronizeWithDidDocument は、署名に新しいキーの使用を開始するようシステムに指示します。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/didInfo/synchronizeWithDidDocument

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

didDocumentStatus は、呼び出しが成功すると outOfSync から published に変わります。

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

コントラクト

このエンドポイントを使用すると、新しいコントラクトを作成したり、既存のコントラクトを更新したりできます。 コントラクトは、2 つの JSON 定義で表される 2 つの部分で構成されます。 コントラクトを手動で設計および作成する方法については、こちらを参照してください。

• 表示定義は、検証可能な資格情報の外観 (背景色、ロゴ、検証可能な資格情報のタイトルなど) を制御するために管理者によって使用されます。 このファイルには、検証可能な資格情報内に格納する必要がある要求も含まれます。
• ルール定義には、自己構成証明要求、入力として別の検証可能な資格情報、ユーザーが OIDC 互換 ID プロバイダーにサインインした後に受信した ID トークンなどの構成証明を収集して収集する方法に関する情報が含まれています。

メソッド

コントラクトを取得する

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractId>

機関とコントラクトの正しい値で <authorityId> と <contractId> を置き換えます。

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

メッセージ例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": false,
    "manifestUrl": "...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": <rulesModel>,
    "displays": <displayModel[]>,
    "allowOverrideValidityIntervalOnIssuance": false
}

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

コントラクトの種類

rulesModel 型

プロパティ customStatusEndpoint が指定されていない場合は、anonymous 状態エンドポイントが使用されます。

構成証明の種類

idTokenAttestation 型

idTokenHintAttestation 型

verifiablePresentationAttestation 型

selfIssuedAttestation 型

accessTokenAttestation 型

inputClaim プロパティに対してサポートされている mappings 値は次のとおりです: givenName、displayName、preferredLanguage、userPrincipalName、surname、mail、jobTitle、photo。

claimMapping 型

customStatusEndpoint 型

例:

"rules": {
    "attestations": {
        "idTokens": [
            {
                "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
                "redirectUri": "vcclient://openid/",
                "scope": "openid",
                "mapping": [
                    {
                        "outputClaim": "givenName",
                        "required": false,
                        "inputClaim": "given_name",
                        "indexed": false
                    },
                    {
                        "outputClaim": "familyName",
                        "required": false,
                        "inputClaim": "family_name",
                        "indexed": true
                    }
                ],
                "required": false
            }
        ]
    },
    "validityInterval": 2592000,
    "vc": {
        "type": [
            "BankofWoodgroveIdentity"
        ]
    }
}

displayModel 型

displayCredential 型

displayCredentialLogo 型

displayConsent 型

displayClaims 型

例:

{
  "displays": [
        {
            "locale": "en-US",
            "card": {
                "backgroundColor": "#FFA500",
                "description": "ThisisyourBankofWoodgroveIdentity",
                "issuedBy": "BankofWoodgrove",
                "textColor": "#FFFF00",
                "title": "BankofWoodgroveIdentity",
                "logo": {
                    "description": "Defaultbankofwoodgrovelogo",
                    "uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png"
                }
            },
            "consent": {
                "instructions": "Please login with your bankofWoodgrove account to receive this credential.",
                "title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
            },
            "claims": [
                {
                    "claim": "vc.credentialSubject.givenName",
                    "label": "Name",
                    "type": "String"
                },
                {
                    "claim": "vc.credentialSubject.familyName",
                    "label": "Surname",
                    "type": "String"
                }
            ]
        }
    ]
}

コントラクトを一覧表示する

この API には、指定した機関の現在のテナントで構成されているすべてのコントラクトが一覧表示されます。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

メッセージ例:

{
    "value":
    [
        {
            "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
            "name": "test1",
            "authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
            "name": "test2",
            "authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        }
    ]
}

コントラクトの作成

コントラクトを作成する場合、使用する名前はテナント内で一意である必要があります。 複数の機関を作成する場合、コントラクト名はすべての機関で一意である必要があります。 コントラクトの名前は、発行要求で使用されるコントラクト URL の一部です。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/contracts

要求ヘッダー

要求本文

要求の例

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

応答メッセージ

メッセージ例:

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "GUID",
    "name": "ExampleContractName1",
    "issuerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
    "manifestUrl": "https://..."
}

コントラクトを更新します

この API では、コントラクトを更新できます。

PATCH /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>

要求の例:

{
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],}
    "availableInVcDirectory": true
    "allowOverrideValidityIntervalOnIssuance": true
}

応答メッセージ

メッセージ例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": true,
    "manifestUrl": "https://...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": rulesModel,
    "displays": displayModel[],
    "allowOverrideValidityIntervalOnIssuance": true
}

資格情報

このエンドポイントを使用すると、発行された検証可能な資格情報を検索し、失効状態を確認し、資格情報を取り消すことができます。

メソッド

認証情報の取得

この API を使用すると、特定の資格情報を取得し、状態を確認して取り消されたかどうかを確めることができます。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials/:credentialId

要求ヘッダー

応答メッセージ

メッセージ例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
    "contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
    "status": "valid",
    "issuedAt": "2017-09-13T21:59:23.9868631Z"
}

資格情報の検索

特定のインデックス要求を使用して、検証可能な資格情報を検索できます。 ハッシュのみが格納されるため、計算された特定の値を検索する必要があります。 使用する必要があるアルゴリズムは、Base64Encode(SHA256(contractid + claim value)) です。C# の例は次のようになります。

  string claimvalue = "Bowen";
  string contractid = "<...your-contract-id-value...>";
  string output;

  using (var sha256 = SHA256.Create())
  {
    var input = contractid + claimvalue;
    byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
    hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
    output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
  }

次の要求は、要求のフィルター パラメーターに計算値を追加する方法を示しています。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

メッセージ例:

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
            "status": "valid",
            "issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
        }
    ]
}

資格情報の取り消し

この API を使用すると、特定の資格情報を取り消すことができます。検索 API を使用して資格情報を検索した後、特定の資格情報 ID を指定することで資格情報を取り消すことができます。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/<authorityId>/contracts/<contractid>/credentials/:credentialid/revoke

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください。

応答メッセージ

HTTP/1.1 204 No Content
Content-type: application/json

オプトアウト

このメソッドは、このテナント内の検証可能な資格情報サービスのすべてのインスタンスを削除します。 構成されているすべてのコントラクトが削除されます。 失効について、発行されたすべての検証可能な資格情報を確認できるわけではありません。 この削除操作は元に戻すことができません。

HTTP 要求

POST /v1.0/verifiableCredentials/optout

要求ヘッダー

要求本文

このメソッドでは要求本文を指定しないでください

応答メッセージ

応答メッセージの例

HTTP/1.1 200 OK
Content-type: application/json

OK

注記

次のステップ

• 要求サービス REST API の発行要求を指定する
• Microsoft Entra 確認済み ID ネットワーク API