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

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

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

この API は、RESTful API を使い慣れた開発者と、サービスを有効にするために必要な Microsoft Entra テナントに対するアクセス許可を持つ開発者を対象としています

ベース 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 サービスでは、次のアプリケーションのアクセス許可がサポートされています。

権限	説明
VerifiableCredential.Authority.ReadWrite	権限オブジェクトの読み取り/書き込み権限
VerifiableCredential.Contract.ReadWrite	コントラクトオブジェクトの読み取り/書き込みアクセス許可
VerifiableCredential.Credential.Search	取り消す資格情報を検索する権限
VerifiableCredential.Credential.Revoke	以前に発行された資格情報を取り消す権限
VerifiableCredential.Network.Read	検証済み ID ネットワークからエントリを読み取る権限

アプリの登録には、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

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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 を繰り返し呼び出すと、まったく同じ応答メッセージが返されます。

機関

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

メソッド

メソッド	戻り値の型	説明
Get Authority	Authority	権限のプロパティを読み取ります
List Authority	Authority の配列	構成されているすべての機関/検証可能な資格情報サービスの一覧を取得します
Create Authority	Authority	新しい機関を作成します
Update authority	Authority	機関を更新します
Delete authority	Authority	機関を削除します
Generate DID Document
Rotate Signing Key	Authority	署名キーのローテーション
署名キーの作成	Authority	署名キーを作成する
DID ドキュメントと同期する	Authority	DID ドキュメントを新しい署名キーと同期する
Generate Well known DID Configuration
Validate Well-known DID config

Get authority

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

HTTP 要求

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

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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/"
    }
}

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

機関の種類

プロパティ	タイプ	説明
`Id`	string	自動生成された一意の ID。検証可能な資格情報サービスの特定のインスタンスを取得または更新するために使用できます。
`name`	string	検証可能な資格情報サービスのこのインスタンスのフレンドリ名
`status`	string	サービスの状態では、この値は常に `enabled`
didModel	didModel	DID とキーに関する情報
keyVaultMetadata	keyVaultMeta データ	使用されるキーコンテナーに関する情報

didModel 型

Web

プロパティ	タイプ	説明
`did`	string	この検証可能な資格情報サービスインスタンスの DID
`signingKeys`	文字列配列	署名キーへの URL
`linkedDomainUrls`	文字列配列	1 つのエントリを想定して、この DID にリンクされているドメイン
didModel	didModel	DID とキーに関する情報
`didDocumentStatus`	string	DID の状態。このメソッドの場合、値は常に `published`

keyVaultMetadata 型

プロパティ	タイプ	説明
`subscriptionId`	string	このキーコンテナーが存在する Azure サブスクリプション
`resourceGroup`	string	このキーコンテナーのリソースグループの名前
`resourceName`	string	キーコンテナー名
`resourceUrl`	string	このキーコンテナーへの URL

List authorities

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

HTTP 要求

GET /v1.0/verifiableCredentials/authorities

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

応答メッセージは、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/"
            }
        }
    ]
}

Create authority

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

HTTP 要求

POST /v1.0/verifiableCredentials/authorities

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

プロパティ	タイプ	説明
`name`	string	サービスのこのインスタンスの表示名
`linkedDomainUrl`	string	この DID にリンクされているドメイン
`didMethod`	string	`Default` である必要があります。
`keyVaultMetadata`	keyVaultMetadata	特定のキーコンテナーのメタデータ

メッセージ例:

{
  "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> の値を置き換えます。

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

プロパティ	タイプ	説明
`name`	string	サービスのこのインスタンスの表示名

メッセージ例:

{
  "name":"ExampleIssuerName"
}

機関を削除します

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

HTTP 要求

DELETE /beta/verifiableCredentials/authorities/<authorityId>

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

要求本文はありません

応答メッセージ

応答メッセージの例:

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

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"
    }
}

Well-known DID configuration

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

指定した機関の 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>..."
    ]
}

Generate DID document

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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 アクセス許可が必要です。

Validate well-known DID configuration

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

{
	"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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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 トークンなどの構成証明を収集して収集する方法に関する情報が含まれています。

メソッド

メソッド	戻り値の型	説明
Get contract	コントラクト	コントラクトのプロパティを読み取ります
List contracts	コントラクトのコレクション	構成されているすべてのコントラクトの一覧を取得します
Create contract	コントラクト	新しいコントラクトを作成する
Update contract	コントラクト	コントラクトを更新します

Get contract

HTTP 要求

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

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

メッセージ例:

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
}

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

コントラクトの種類

プロパティ	タイプ	説明
`Id`	string	コントラクト ID
`name`	string	このコントラクトのフレンドリ名
`status`	string	常に `Enabled`
`manifestUrl`	string	発行要求で使用されるコントラクトの URL
`issueNotificationEnabled`	boolean	ユーザーに対して true に設定すると、この VC が発行される準備ができていることが通知されます
`issueNotificationAllowedToGroupOids`	groupId 文字列の配列	この資格情報を使用できるグループ ID の配列
`availableInVcDirectory`	boolean	このコントラクトが検証可能な資格情報のネットワークで公開されているかどうか
rules	rulesModel	ルール定義
displays	displayModel 配列	表示定義
`allowOverrideValidityIntervalOnIssuance`	boolean	createIssuanceRequest API 呼び出しで資格情報の有効期限をオーバーライドできる場合。これは idTokenHint フローでのみ有効です。

rulesModel 型

プロパティ	タイプ	説明
`attestations`	attestations	ルールでサポートされている入力を記述します
`validityInterval`	number	この値は資格情報の有効期間を示します
`vc`	vcType 配列	このコントラクトの型
`customStatusEndpoint`	[customStatusEndpoint] (#customstatusendpoint-type) (省略可能)	このコントラクトの検証可能な資格情報に含める状態エンドポイント

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

構成証明の種類

プロパティ	タイプ	説明
`idTokens`	idTokenAttestation (配列) (省略可能)	ID トークンの入力について記述します
`idTokenHints`	idTokenHintAttestation (配列) (省略可能)	ID トークンヒントの入力について記述します
`presentations`	verifiablePresentationAttestation (配列) (省略可能)	検証可能なプレゼンテーションの入力について記述します
`selfIssued`	selfIssuedAttestation (配列) (省略可能)	自己発行された入力について記述します
`accessTokens`	accessTokenAttestation (配列) (省略可能)	アクセストークンの入力について記述します

idTokenAttestation 型

プロパティ	タイプ	説明
`mapping`	claimMapping (省略可能)	入力要求を検証可能な資格情報の出力要求にマップする規則
`configuration`	string (url)	ID プロバイダーの構成ドキュメントの場所
`clientId`	string	ID トークンを取得するときに使用するクライアント ID
`redirectUri`	string	ID トークンを取得するときに使用するリダイレクト URI。vcclient://openid/ にする必要があります
`scope`	string	ID トークンを取得するときに使用するスコープのスペース区切りリスト
`required`	boolean (既定値は false)	この構成証明が必要かどうかを示します

idTokenHintAttestation 型

プロパティ	タイプ	説明
`mapping`	claimMapping (省略可能)	入力要求を検証可能な資格情報の出力要求にマップする規則
`required`	boolean (既定値は false)	この構成証明が必要かどうかを示します
`trustedIssuers`	string (配列)	このコントラクトの検証可能な資格情報を発行できる DID のリスト

verifiablePresentationAttestation 型

プロパティ	タイプ	説明
`mapping`	claimMapping (省略可能)	入力要求を検証可能な資格情報の出力要求にマップする規則
`credentialType`	string (省略可能)	入力に必要な資格情報の型
`required`	boolean (既定値は false)	この構成証明が必要かどうかを示します
`trustedIssuers`	string (配列)	このコントラクトの検証可能な資格情報を発行できる DID のリスト

selfIssuedAttestation 型

プロパティ	タイプ	説明
`mapping`	claimMapping (省略可能)	入力要求を検証可能な資格情報の出力要求にマップする規則
`required`	boolean (既定値は false)	この構成証明が必要かどうかを示します

accessTokenAttestation 型

プロパティ	タイプ	説明
`mapping`	claimMapping (省略可能)	入力要求を検証可能な資格情報の出力要求にマップする規則
`required`	boolean (既定値は false)	この構成証明が必要かどうかを示します

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

claimMapping 型

プロパティ	タイプ	説明
`inputClaim`	string	入力から使用する要求の名前
`outputClaim`	string	検証可能な資格情報の要求の名前
`indexed`	boolean (既定値は false)	この要求の値が検索に使用されるかどうかを示します。指定されたコントラクトごとにインデックスを作成できる clientMapping オブジェクトは 1 つだけです
`required`	boolean (既定値は false)	このマッピングが必要かどうかを示します
`type`	string (省略可能)	要求の種類

customStatusEndpoint 型

プロパティ	タイプ	説明
`url`	string (url)	カスタム状態エンドポイントの URL
`type`	string	エンドポイントの種類

例:

"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 型

プロパティ	タイプ	説明
`locale`	string	この表示のロケール
`credential`	displayCredential	検証可能な資格情報の表示プロパティ
`consent`	displayConsent	検証可能な資格情報が発行されたときの補足データ
`claims`	displayClaims 配列	検証可能な資格情報に含まれる要求のラベル

displayCredential 型

プロパティ	タイプ	説明
`title`	string	資格情報のタイトル
`issuedBy`	string	資格情報の発行者の名前
`backgroundColor`	number (16 進数)	16 進数の資格情報の背景色 (例: #FFAABB)
`textColor`	number (16 進数)	16 進数の資格情報のテキストの色 (例: #FFAABB)
`description`	string	各資格情報の横に表示される補助テキスト
`logo`	displayCredentialLogo	資格情報に使用するロゴ

displayCredentialLogo 型

プロパティ	タイプ	説明
`uri`	string (URI)	ロゴの URI。値が URL の場合は、パブリックインターネット経由で匿名で到達できる必要があります。
`description`	string	ロゴの説明

displayConsent 型

プロパティ	タイプ	説明
`title`	string	同意のタイトル
`instructions`	string	同意を表示するときに使用する補足テキスト

displayClaims 型

プロパティ	タイプ	説明
`label`	string	表示されている要求のラベル
`claim`	string	ラベルが適用される要求の名前
`type`	string	要求の種類
`description`	string (省略可能)	要求の説明

例:

{
  "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"
                }
            ]
        }
    ]
}

List contracts

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

メッセージ例:

{
    "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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

要求の例

{
    "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
}

資格情報

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

メソッド

メソッド	戻り値の型	説明
Get credential	資格情報	資格情報のプロパティを読み取ります
Search credentials	資格情報のコレクション	特定の要求値を使用して資格情報の一覧を検索します
Revoke credential		特定の資格情報を取り消します

Get credential

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

応答メッセージ

メッセージ例:

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

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

Search credentials

特定のインデックス要求を使用して、検証可能な資格情報を検索できます。ハッシュのみが格納されるため、計算された特定の値を検索する必要があります。使用する必要があるアルゴリズムは、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}

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

メッセージ例:

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"
        }
    ]
}

Revoke credential

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

HTTP 要求

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

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

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

オプトアウト

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

警告

この操作を元に戻すことはできず、発行されたすべての検証可能な資格情報と作成されたコントラクトが無効になります。

HTTP 要求

POST /v1.0/verifiableCredentials/optout

要求ヘッダー

ヘッダー	値
承認	ベアラー (トークン)。必須
Content-Type	application/json

要求本文

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

応答メッセージ

応答メッセージの例

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

OK

注記

注意

Key Vault に対する削除アクセス許可がない場合は、エラーメッセージが返され、引き続きオプトアウトされます

次の方法で共有

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

ベース URL

認証

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

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

オンボード

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

機関

メソッド

Get authority

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

機関の種類

didModel 型

Web

keyVaultMetadata 型

List authorities

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

Create authority

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

解説

機関を更新します

HTTP 要求

要求ヘッダー

要求本文

機関を削除します

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

Well-known DID configuration

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

解説

Generate DID document

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

注記

Validate well-known DID configuration

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

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

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

署名キーを作成する

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

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

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

コントラクト

メソッド

Get contract

HTTP 要求

要求ヘッダー

要求本文

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

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