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

[アーティクル]
08/29/2023

注意

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、mail、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

注記

注意

キーコンテナーに対する削除権限がない場合は、エラーメッセージが返されますが、そのままオプトアウトされます

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

ベース URL

認証

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

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

オンボード

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

機関

メソッド

Get authority

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

機関の種類

didModel 型

ION

Web

keyVaultMetadata 型

List authorities

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

Create authority

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

解説

Update authority

HTTP 要求

要求ヘッダー

要求本文

リンクされたドメイン

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

解説

Well-known DID configuration

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

解説

Generate DID document

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

注記

Validate well-known DID configuration

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

Rotate signing keys

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

コントラクト

メソッド

Get contract

HTTP 要求

要求ヘッダー

要求本文

応答メッセージ

コントラクトの種類

rulesModel 型

attestations 型

idTokenAttestation 型

idTokenHintAttestation 型

verifiablePresentationAttestation 型

selfIssuedAttestation 型

accessTokenAttestation 型

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

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