検証可能な資格情報の管理 API
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 | |
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
、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 に対する削除アクセス許可がない場合は、エラー メッセージが返され、引き続きオプトアウトされます