検証可能な資格情報の管理 API
注意
Azure Active Directory の検証可能な資格情報が Microsoft Entra 検証済み ID になり、Microsoft Entra 製品ファミリの一部になりました。 ID ソリューションの Microsoft Entra ファミリの詳細を確認し、統合 Microsoft Entra 管理センターで作業を開始してください。
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
を使用する必要があります。
オンボード
この 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": "90e10a26-94cd-49d6-8cd7-cacb10f00686",
"verifiableCredentialRequestServicePrincipalId": "870e10a26-94cd-49d6-8cd7-cacb10f00fe",
"verifiableCredentialAdminServicePrincipalId": "760e10a26-94cd-49d6-8cd7-cacb10f00ab",
"status": "Enabled"
}
この API を繰り返し呼び出すと、まったく同じ応答メッセージが返されます。
機関
このエンドポイントを使用して、検証可能な資格情報サービス インスタンスを作成または更新できます。
メソッド
メソッド | 戻り値の型 | 説明 |
---|---|---|
Get Authority | Authority | 権限のプロパティを読み取ります |
List Authority | Authority の配列 | 構成されているすべての機関/検証可能な資格情報サービスの一覧を取得します |
Create Authority | Authority | 新しい機関を作成します |
Update authority | Authority | 機関を更新します |
Generate Well known DID Configuration | ||
Generate DID Document | ||
Validate Well-known DID config | ||
Rotate Signing Key |
Get authority
構成された機関または検証可能な資格情報サービス インスタンスのプロパティを取得します。
HTTP 要求
GET /v1.0/verifiableCredentials/authorities/:authorityId
構成されているいずれかの機関の値で :authorityId
を置き換えます。
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
このメソッドでは要求本文を指定しないでください
応答メッセージ
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:ion:EiAVvtjqr_Ji8pXGNtherrMW2FPl5Ays9mII2vP_QTgUWA:eyJkZWx...<SNIP>",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-ffea7eb3-0000-1111-2222-000000000000/5cfb5458af524da88897522690e01a7e"
],
"updateKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-ffea7eb3-0000-1111-2222-000000000000/24494dbbbace4a079422dde943e1b6f0"
],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://www.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
応答には次のプロパティが含まれます。
機関の種類
プロパティ | Type | 説明 |
---|---|---|
Id |
string | 自動生成された一意の ID。検証可能な資格情報サービスの特定のインスタンスを取得または更新するために使用できます。 |
name |
string | 検証可能な資格情報サービスのこのインスタンスのフレンドリ名 |
status |
string | サービスの状態。この値は常に enabled になります |
didModel | didModel | DID とキーに関する情報 |
keyVaultMetadata | keyVaultMeta データ | 使用されるキー コンテナーに関する情報 |
didModel 型
2 つの異なる didModel がサポートされています。 1 つは ion
で、もう 1 つのサポートされているメソッドは web
です
ION
プロパティ | Type | 説明 |
---|---|---|
did |
string | この検証可能な資格情報サービス インスタンスの DID |
signingKeys |
文字列配列 | 署名キーへの URL |
recoveryKeys |
文字列配列 | 回復キーへの URL |
encryptionKeys |
文字列配列 | 暗号化キーへの URL |
linkedDomainUrls |
文字列配列 | この DID にリンクされているドメイン |
didDocumentStatus |
string | DID の状態。ION に書き込まれるときは published 、それ以外の場合は submitted |
Web
プロパティ | Type | 説明 |
---|---|---|
did |
string | この検証可能な資格情報サービス インスタンスの DID |
signingKeys |
文字列配列 | 署名キーへの URL |
linkedDomainUrls |
文字列配列 | 1 つのエントリを想定して、この DID にリンクされているドメイン |
didModel | didModel | DID とキーに関する情報 |
didDocumentStatus |
string | DID の状態。このメソッドの場合、値は常に published |
keyVaultMetadata 型
プロパティ | Type | 説明 |
---|---|---|
subscriptionId |
string | このキー コンテナーが存在する Azure サブスクリプション |
resourceGroup |
string | このキー コンテナーのリソース グループの名前 |
resourceName |
string | キー コンテナー名 |
resourceUrl |
string | このキー コンテナーへの URL |
List authorities
このテナントに対して構成されているすべての機関または検証可能な資格情報サービスを取得します
HTTP 要求
GET /v1.0/verifiableCredentials/authorities
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
このメソッドでは要求本文を指定しないでください。
応答メッセージ
応答メッセージは、機関配列です。例:
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "ContractName",
"status": "Enabled",
"didModel": {
"did": "did:ion:EiAVvtjqr_Ji8pXGNtherrMW2FPl5Ays9mII2vP_QTgUWA:eyJkZWx<SNIP>...",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-ffea7eb3-0000-1111-2222-000000000000/5cfb5458af524da88897522690e01a7e"
],
"updateKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-ffea7eb3-0000-1111-2222-000000000000/24494dbbbace4a079422dde943e1b6f0"
],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://www.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "cc55ba22-0000-1111-2222-000000000000",
"name": "APItest6",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:ion:EiD_mGdhdAXOS1BV6c7r-CCjetaoRKuAENEwsRM1_QEHMg:eyJkZWx0YSI<SNIP>....",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-cc55ba22-0000-1111-2222-000000000000/68f976cc44014eafb354a6fe305b7d4d"
],
"updateKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-cc55ba22-0000-1111-2222-000000000000/b85328af0c1f460ea026fbdda9cd6652"
],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://www.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
Create authority
この呼び出しにより、新しい秘密キー、回復キー、および更新キーが作成され、これらのキーが指定された Azure Key Vault に格納されます。検証可能な資格情報サービスに対するこの Key Vault へのアクセス許可が設定され、対応する DID ドキュメントを使用して新しい DID が作成され、ION ネットワークにコミットされます。
HTTP 要求
POST /v1.0/verifiableCredentials/authorities
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
要求本文で、次を使用して JSON 表現を指定します
プロパティ | Type | 説明 |
---|---|---|
name |
string | サービスのこのインスタンスの表示名 |
linkedDomainUrl |
string | この DID にリンクされているドメイン |
didMethod |
string | オプション web または ion |
keyVaultMetadata |
keyVaultMetadata | 特定のキー コンテナーのメタデータ |
メッセージ例:
{
"name":"ExampleName",
"linkedDomainUrl":"https://www.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
応答メッセージ
成功した場合、応答メッセージには機関の名前が含まれます
did:web のメッセージ例:
{
"id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:www.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://www.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
did:ion のメッセージ例:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "cc55ba22-0000-1111-2222-000000000000",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:ion:EiD_mGdhdAXOS1BV6c7r-CCjetaoRKuAENEwsRM1_QEHMg",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-cc55ba22-0000-1111-2222-000000000000/68f976cc44014eafb354a6fe305b7d4d"
],
"updateKeys": [
"https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-cc55ba22-0000-1111-2222-000000000000/b85328af0c1f460ea026fbdda9cd6652"
],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://www.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
解説
独自の DID キーと秘密キーを使用して複数の機関を作成できますが、これらは Azure portal の UI には表示されません。 現在、1 つの機関のみをサポートしています。 複数の機関が作成されたすべてのシナリオを完全にはテストしていません。 これを試す場合は、その経験を是非お知らせください。
Update authority
このメソッドを使用して、検証可能な資格情報サービスのこの特定のインスタンスの表示名を更新できます。
HTTP 要求
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
更新する機関 ID の値に :authorityId
の値を置き換えます。
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
要求本文で、次を使用して JSON 表現を指定します。
プロパティ | Type | 説明 |
---|---|---|
name |
string | サービスのこのインスタンスの表示名 |
メッセージ例:
{
"name":"ExampleIssuerName"
}
リンクされたドメイン
DID に関連するドメインを更新できます。 この機能は、この更新プログラムを世界中に配布するために、ION に更新操作を記述する必要があります。 更新プログラムが処理され、他のユーザーが使用できるようになるまで、現在は最大 1 時間かかる場合があります。
HTTP 要求
POST /v1.0/verifiableCredentials/authorities/:authorityId/updateLinkedDomains
更新する機関 ID の値に :authorityId
の値を置き換えます。
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
DID ドキュメントに発行するドメインを指定する必要があります。 ドメインの値は配列ですが、1 つのドメインだけ指定する必要があります。
要求本文で、次を使用して JSON 表現を指定します。
プロパティ | Type | 説明 |
---|---|---|
domainUrls |
文字列配列 | ドメインへのリンク。https で始まる必要があり、パスは含めません |
メッセージ例:
{
"domainUrls" : ["https://www.mydomain.com"]
}
応答メッセージ
HTTP/1.1 202 Accepted
Content-type: application/json
Accepted
didDocumentStatus は submitted
に切り替わります。変更が ION ネットワークにコミットされるまでにしばらく時間がかかります。
操作が完了する前に変更を送信しようとすると、次のエラー メッセージが表示されます。
HTTP/1.1 409 Conflict
Content-type: application/json
{
"requestId":"83047b1c5811284ce56520b63b9ba83a","date":"Mon, 07 Feb 2022 18:36:24 GMT",
"mscv":"tf5p8EaXIY1iWgYM.1",
"error":
{
"code": "conflict",
"innererror": {
"code":"ionOperationNotYetPublished",
"message":"There is already an operation in queue for this organization's DID (decentralized identifier), please wait until the operation is published to submit a new one."
}
}
}
didDocumentstatus が published
に戻るまで待ってから、別の変更を送信する必要があります。
ドメイン URL は https で始める必要があり、パス値は含めません。
考えられるエラー メッセージ:
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"57c5ac78abb86bbfbc6f9e96d9ae6b18",
"date":"Mon, 07 Feb 2022 18:47:14 GMT",
"mscv":"+QfihZZk87z0nky2.0",
"error": "BadRequest",
"innererror": {
"code":"parameterUrlSchemeMustBeHttps",
"message":"URLs must begin with HTTPS: domains"
}
}
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"e65753b03f28f159feaf434eaf140547",
"date":"Mon, 07 Feb 2022 18:48:36 GMT",
"mscv":"QWB4uvgYzCKuMeKg.0",
"error": "BadRequest",
"innererror": {
"code":"parameterUrlPathMustBeEmpty",
"message":"The URL can only include a domain. Please remove any characters after the domain name and try again. linkedDomainUrl"
}
}
解説
技術的には複数のドメインを発行できますが、現在サポートされているドメインは機関ごとに 1 つだけです。
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:www.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:www.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://www.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:www.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 signing keys
Rotate signing keys は、did:web 機関の秘密キーを更新します。
HTTP 要求
POST /v1.0/verifiableCredentials/authorities/:authorityId/rotateSigningKey
要求ヘッダー
ヘッダー | 値 |
---|---|
承認 | ベアラー (トークン)。 必須 |
Content-Type | application/json |
要求本文
このメソッドでは要求本文を指定しないでください。
応答メッセージ
HTTP/1.1 202 Accepted
Content-type: application/json
コントラクト
このエンドポイントを使用すると、新しいコントラクトを作成したり、既存のコントラクトを更新したりできます。 コントラクトは、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": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[]
}
応答には次のプロパティが含まれます。
コントラクトの種類
プロパティ | Type | 説明 |
---|---|---|
Id |
string | コントラクト ID |
name |
string | このコントラクトのフレンドリ名 |
status |
string | 常に Enabled |
manifestUrl |
string | 発行要求で使用されるコントラクトの URL |
issueNotificationEnabled |
boolean | この VC を発行する準備ができていることをユーザーに通知する場合は true に設定します |
issueNotificationAllowedToGroupOids |
groupId 文字列の配列 | この資格情報が提供されるグループ ID の配列 |
availableInVcDirectory |
boolean | このコントラクトが検証可能な資格情報のネットワークで公開されているかどうか |
rules | rulesModel | ルール定義 |
displays | displayModel 配列 | 表示定義 |
rulesModel 型
プロパティ | Type | 説明 |
---|---|---|
attestations |
attestations | ルールでサポートされている入力を記述します |
validityInterval |
number | この値は資格情報の有効期間を示します |
vc |
vcType 配列 | このコントラクトの型 |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-type) (省略可能) | このコントラクトの検証可能な資格情報に含める状態エンドポイント |
プロパティ customStatusEndpoint
が指定されていない場合は、anonymous
状態エンドポイントが使用されます。
attestations 型
プロパティ | Type | 説明 |
---|---|---|
idTokens |
idTokenAttestation (配列) (省略可能) | ID トークンの入力について記述します |
idTokenHints |
idTokenHintAttestation (配列) (省略可能) | ID トークン ヒントの入力について記述します |
presentations |
verifiablePresentationAttestation (配列) (省略可能) | 検証可能なプレゼンテーションの入力について記述します |
selfIssued |
selfIssuedAttestation (配列) (省略可能) | 自己発行された入力について記述します |
accessTokens |
accessTokenAttestation (配列) (省略可能) | アクセス トークンの入力について記述します |
idTokenAttestation 型
プロパティ | Type | 説明 |
---|---|---|
mapping |
claimMapping (省略可能) | 入力要求を検証可能な資格情報の出力要求にマップする規則 |
configuration |
string (url) | ID プロバイダーの構成ドキュメントの場所 |
clientId |
string | ID トークンを取得するときに使用するクライアント ID |
redirectUri |
string | ID トークンを取得するときに使用するリダイレクト URI。vcclient://openid/ にする必要があります |
scope |
string | ID トークンを取得するときに使用するスコープのスペース区切りリスト |
required |
boolean (既定値は false) | この構成証明が必要かどうかを示します |
idTokenHintAttestation 型
プロパティ | Type | 説明 |
---|---|---|
mapping |
claimMapping (省略可能) | 入力要求を検証可能な資格情報の出力要求にマップする規則 |
required |
boolean (既定値は false) | この構成証明が必要かどうかを示します |
trustedIssuers |
string (配列) | このコントラクトの検証可能な資格情報を発行できる DID のリスト |
verifiablePresentationAttestation 型
プロパティ | Type | 説明 |
---|---|---|
mapping |
claimMapping (省略可能) | 入力要求を検証可能な資格情報の出力要求にマップする規則 |
credentialType |
string (省略可能) | 入力に必要な資格情報の型 |
required |
boolean (既定値は false) | この構成証明が必要かどうかを示します |
trustedIssuers |
string (配列) | このコントラクトの検証可能な資格情報を発行できる DID のリスト |
selfIssuedAttestation 型
プロパティ | Type | 説明 |
---|---|---|
mapping |
claimMapping (省略可能) | 入力要求を検証可能な資格情報の出力要求にマップする規則 |
required |
boolean (既定値は false) | この構成証明が必要かどうかを示します |
accessTokenAttestation 型
プロパティ | Type | 説明 |
---|---|---|
mapping |
claimMapping (省略可能) | 入力要求を検証可能な資格情報の出力要求にマップする規則 |
required |
boolean (既定値は false) | この構成証明が必要かどうかを示します |
mappings
プロパティに対してサポートされているinputClaim
値は次のとおりです:givenName
、displayName
、preferredLanguage
、userPrincipalName
、surname
、jobTitle
、photo
。
claimMapping 型
プロパティ | Type | 説明 |
---|---|---|
inputClaim |
string | 入力から使用する要求の名前 |
outputClaim |
string | 検証可能な資格情報の要求の名前 |
indexed |
boolean (既定値は false) | この要求の値が検索に使用されるかどうかを示します。特定のコントラクトに対してインデックスを作成できるのは clientMapping オブジェクトだけです |
required |
boolean (既定値は false) | このマッピングが必要かどうかを示します |
type |
string (省略可能) | 要求の種類 |
customStatusEndpoint 型
プロパティ | Type | 説明 |
---|---|---|
url |
string (url) | カスタム状態エンドポイントの URL |
type |
string | エンドポイントの種類 |
例:
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "2f670d73-624a-41fe-a139-6f1f8f2d2e47",
"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 型
プロパティ | Type | 説明 |
---|---|---|
locale |
string | この表示のロケール |
credential |
displayCredential | 検証可能な資格情報の表示プロパティ |
consent |
displayConsent | 検証可能な資格情報が発行されたときの補足データ |
claims |
displayClaims 配列 | 検証可能な資格情報に含まれる要求のラベル |
displayCredential 型
プロパティ | Type | 説明 |
---|---|---|
title |
string | 資格情報のタイトル |
issuedBy |
string | 資格情報の発行者の名前 |
backgroundColor |
number (16 進数) | 16 進数の資格情報の背景色 (例: #FFAABB) |
textColor |
number (16 進数) | 16 進数の資格情報のテキストの色 (例: #FFAABB) |
description |
string | 各資格情報の横に表示される補助テキスト |
logo |
displayCredentialLogo | 資格情報に使用するロゴ |
displayCredentialLogo 型
プロパティ | Type | 説明 |
---|---|---|
uri |
string (URI) | ロゴの uri |
description |
string | ロゴの説明 |
displayConsent 型
プロパティ | Type | 説明 |
---|---|---|
title |
string | 同意のタイトル |
instructions |
string | 同意を表示するときに使用する補足テキスト |
displayClaims 型
プロパティ | Type | 説明 |
---|---|---|
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.blob.core.windows.net/public/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": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "test1",
"authorityId": "ffea7eb3-0000-1111-2222-000000000000",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
"name": "test2",
"authorityId": "cc55ba22-0000-1111-2222-000000000000",
"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": "cc55ba22-0000-1111-2222-000000000000",
"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}],}
}
応答メッセージ
メッセージ例:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[]
}
資格情報
このエンドポイントを使用すると、発行された検証可能な資格情報を検索し、失効状態を確認し、資格情報を取り消すことができます。
メソッド
メソッド | 戻り値の型 | 説明 |
---|---|---|
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 );
}
次の要求は、要求のフィルター パラメーターに計算値を追加する方法を示しています。 現時点では、filter=indexclaimhash eq 形式のみがサポートされています。
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",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": 1644029489000
}
]
}
メッセージ例:
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "issuerRevoked",
"issuedAt": 1644029489000
}
]
}
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
注記
注意
キー コンテナーに対する削除権限がない場合は、エラー メッセージが返されますが、そのままオプトアウトされます