可驗認證管理員 API

Microsoft Entra 已驗證識別碼管理員 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	從已驗證識別碼網路 (部分機器翻譯) 讀取項目的權限

應用程式註冊必須具有 Verifiable Credentials Service Admin 的 API 權限和上表要求的權限。 透過用戶端認證流程取得存取權杖時，應用程式應該使用範圍 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default。

如果應用程式想要建立新的授權單位，則需要兩個項目。 首先，應用程式註冊需要 VerifiableCredential.Authority.ReadWrite 權限。 其次，應用程式需要 Key Vault 存取原則中的 Create Key 權限。 如果應用程式只會讀取/寫入現有的授權單位，則不需要 Key Vault 權限。

登入

此 API 旨在協助建立新的環境，以便可以設定新的授權單位。 您也可以瀏覽至 Azure 入口網站中的 [可驗認證] 頁面，手動觸發此動作。 您只需要呼叫此 API 一次，而且只在您想要僅使用 API 設定全新的環境時才需要呼叫。

HTTP 要求

POST /v1.0/verifiableCredentials/onboard

使用此端點完成租用戶中可驗認證服務的佈建。 如果尚未佈建其餘的服務主體，系統會建立這些服務主體。

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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 將會產生完全相同的傳回訊息。

授權單位

此端點可以用來建立或更新可驗認證服務執行個體。

方法

方法	傳回類型	描述
取得授權單位	授權單位	讀取授權單位的屬性
列出授權單位	授權單位陣列	取得所有已設定授權單位/可驗認證服務的清單
建立授權單位	授權單位	建立新的授權單位
更新授權單位	授權單位	更新授權單位
刪除授權單位	授權單位	刪除授權單位
產生已知的 DID 設定
產生 DID 文件
驗證已知的 DID 設定
輪替簽署金鑰	授權單位	輪替簽署金鑰
與 DID 文件同步	授權單位	使用新的簽署金鑰同步 DID 文件

取得授權單位

擷取已設定授權單位或可驗認證服務執行個體的屬性。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/:authorityId

將 :authorityId 取代為其中一個已設定授權單位的值。

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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	字串	自動產生的唯一識別碼，可用來擷取或更新可驗認證服務的特定執行個體
name	字串	這個可驗認證服務執行個體的自訂名稱
status	字串	服務的狀態，此值將一律為 enabled
didModel	didModel	DID 和金鑰的相關資訊
keyVaultMetadata	keyVaultMeta 資料	所使用金鑰保存庫的相關資訊

didModel 類型

Web

屬性	類型​	描述
did	字串	這個可驗認證服務執行個體的 DID
signingKeys	字串陣列	簽署金鑰的 URL
linkedDomainUrls	字串陣列	連結至此 DID 的網域，預期有一個項目
didModel	didModel	DID 和金鑰的相關資訊
didDocumentStatus	字串	DID 的狀態，這個方法的值一律為 published

keyVaultMetadata 類型

屬性	類型​	描述
subscriptionId	字串	此 Key Vault 所在的 Azure 訂用帳戶
resourceGroup	字串	來自此 Key Vault 的資源群組名稱
resourceName	字串	Key Vault 名稱
resourceUrl	字串	此 Key Vault 的 URL

列出授權單位

取得此租用戶的所有已設定授權單位或可驗認證服務

HTTP 要求

GET /v1.0/verifiableCredentials/authorities

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

請不要為此方法提供要求本文。

回應訊息

回應訊息是授權單位的陣列

範例：

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

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

建立授權單位

此呼叫會建立新的私密金鑰、修復金鑰和更新金鑰，將這些金鑰儲存在指定的 Azure Key Vault 中，並針對可驗認證服務設定此 Key Vault 的權限，以及使用對應的 DID 文件建立新的 DID。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

在要求本文中，提供如下的 JSON 表示法

屬性	類型​	描述
name	字串	此服務執行個體的顯示名稱
linkedDomainUrl	字串	連結至此 DID 的網域
didMethod	字串	必須是 web
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 入口網站的 UI 中。 目前我們只支援擁有 1 個授權單位。 我們尚未使用多個已建立的授權單位完整測試所有案例。 如果您嘗試這樣做，請讓我們知道您的體驗。

更新授權單位

這種方法可以用來更新這個可驗認證服務特定執行個體的顯示名稱。

HTTP 要求

PATCH /v1.0/verifiableCredentials/authorities/:authorityId

將 :authorityId 的值取代為您要更新的授權單位識別碼值。

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

在要求本文中，提供如下的 JSON 表示法。

屬性	類型​	描述
name	字串	此服務執行個體的顯示名稱

範例訊息

{
  "name":"ExampleIssuerName"
}

刪除授權單位

此方法可用來刪除授權單位。 目前只能刪除 did:ion 個授權單位。 刪除授權單位時，任何核發的已驗證識別碼認證都會變得無效，因此不再可驗證，因為核發授權單位已消失。

HTTP 要求

DELETE /beta/verifiableCredentials/authorities/:authorityId

將 :authorityId 的值取代為您要刪除的授權單位識別碼值。

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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"
    }
}

已知的 DID 設定

generateWellknownDidConfiguration 方法會產生已簽署的 did-configuration.json 檔案。 此檔案必須上傳至網站根目錄中的 .well-known，而該網站是針對此可驗認證執行個體的連結網域中的網域所裝載。 在這裡可以找到相關指示。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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 儲存此結果，並將此檔案上傳至正確的資料夾和網站。 如果您指定未連結至此 DID/DID 文件的網域，則會收到錯誤：

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

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

備註

您可以將多個 DID 指向相同的網域。 如果您選擇此設定，則必須結合產生的權杖，並將其放在相同的 did-configuration.json 檔案中。 此檔案包含這些權杖的陣列。

例如：

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

產生 DID 文件

此呼叫會產生用於 DID:WEB 識別碼的 DID 文件。 在產生此 DID 文件之後，管理員必須將檔案放在 https://domain/.well-known/did.json 位置。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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"
    ]
}

備註

要求呼叫者具有目標金鑰保存庫的金鑰清單權限。

驗證已知的 DID 設定

此呼叫會檢查您的 DID 設定。 其會下載已知的 DID 設定，並驗證是否已使用正確的 DID，且簽章正確無誤。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

請不要為此方法提供要求本文。

回應訊息

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

輪替簽署金鑰

輪替簽署金鑰會為 did:web 授權單位建立新的私密金鑰。 應該重新註冊 DID 文件以反映更新。 完成此作業時，synchronizeWithDidDocument 會指示系統開始使用新金鑰進行簽署。

HTTP 要求

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

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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 文件同步

輪替簽署金鑰之後，應該重新註冊 (部分機器翻譯) DID 文件以反映更新。 完成此作業時，synchronizeWithDidDocument 會指示系統開始使用新金鑰進行簽署。

HTTP 要求

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

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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
}

合約

此端點可讓您建立新的合約，並更新現有的合約。 合約是由兩個 JSON 定義所代表的兩個部分所組成。 如需如何手動設計和建立合約的相關資訊，可在這裡找到。

• 管理員會使用顯示定義來控制可驗認證的外觀，例如可驗認證的背景色彩、標誌和標題。 此檔案也包含必須儲存在可驗認證內的宣告。
• 規則定義包含如何蒐集和收集證明的相關資訊，例如自我證明宣告、另一個作為輸入的可驗認證，或也許是使用者登入 OIDC 相容識別提供者之後收到的識別碼權杖。

方法

方法	傳回類型	描述
取得合約	合約	讀取合約的屬性
列出合約	合約集合	取得所有已設定合約的清單
建立合約	合約	建立新合約
更新合約	合約	建立合約

取得合約

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

將 :authorityId 和 :contractId 取代為授權單位和合約的正確值。

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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	字串	合約識別碼
name	字串	此合約的自訂名稱
status	字串	一律為 Enabled
manifestUrl	字串	簽發要求中所用合約的 URL
issueNotificationEnabled	boolean	如果使用者收到通知，此 VC 已備妥可供其發出，請設定為 true
issueNotificationAllowedToGroupOids	groupId 字串的陣列	此認證將提供給其的群組識別碼陣列
availableInVcDirectory	boolean	此合約是否在可驗認證網路中發佈
規則	rulesModel	規則定義
顯示	displayModel 陣列	顯示定義
allowOverrideValidityIntervalOnIssuance	boolean	如果允許 createIssuanceRequest API 呼叫覆寫認證的到期日。 這僅適用 idTokenHint 流程。

rulesModel 類型

屬性	類型​	描述
attestations	證明	描述規則支援的輸入
validityInterval	數值	此值會顯示認證的存留期
vc	vcType 陣列	此合約的類型
customStatusEndpoint	[customStatusEndpoint] (#customstatusendpoint-type) (選用)	要包含在此合約可驗認證中的狀態端點

如果未指定 customStatusEndpoint 屬性，則會使用 anonymous 狀態端點。

證明類型

屬性	類型​	描述
idTokens	idTokenAttestation (陣列) (選擇性)	描述識別碼權杖輸入
idTokenHints	idTokenHintAttestation (陣列) (選擇性)	描述識別碼權杖提示輸入
presentations	verifiablePresentationAttestation (陣列) (選擇性)	描述可驗證的簡報輸入
selfIssued	selfIssuedAttestation (陣列) (選擇性)	描述自我發行的輸入
accessTokens	accessTokenAttestation (陣列) (選擇性)	描述存取權杖輸入

idTokenAttestation 類型

屬性	類型​	描述
mapping	claimMapping (選擇性)	規則，將輸入宣告對應至可驗認證中的輸出宣告
configuration	字串 (url)	身分識別提供者設定文件的位置
clientId	字串	取得識別碼權杖時要使用的用戶端識別碼
redirectUri	字串	取得識別碼權杖時的重新導向 URI 必須是 vcclient://openid/
scope	字串	取得識別碼權杖時要使用的範圍空格分隔清單
required	布林值 (預設值 false)	指出是否需要此證明

idTokenHintAttestation 類型

屬性	類型​	描述
mapping	claimMapping (選擇性)	規則，將輸入宣告對應至可驗認證中的輸出宣告
required	布林值 (預設值 false)	指出是否需要此證明
trustedIssuers	字串 (陣列)	允許核發此合約可驗認證的 DID 清單

verifiablePresentationAttestation 類型

屬性	類型​	描述
mapping	claimMapping (選擇性)	規則，將輸入宣告對應至可驗認證中的輸出宣告
credentialType	字串 (選擇性)	輸入的必要認證類型
required	布林值 (預設值 false)	指出是否需要此證明
trustedIssuers	字串 (陣列)	允許核發此合約可驗認證的 DID 清單

selfIssuedAttestation 類型

屬性	類型​	描述
mapping	claimMapping (選擇性)	規則，將輸入宣告對應至可驗認證中的輸出宣告
required	布林值 (預設值 false)	指出是否需要此證明

accessTokenAttestation 類型

屬性	類型​	描述
mapping	claimMapping (選擇性)	規則，將輸入宣告對應至可驗認證中的輸出宣告
required	布林值 (預設值 false)	指出是否需要此證明

mappings 屬性支援的 inputClaim 值如下：givenNamedisplayNamepreferredLanguageuserPrincipalNamesurnamemailjobTitlephoto。

claimMapping 類型

屬性	類型​	描述
inputClaim	字串	要從輸入使用的宣告名稱
outputClaim	字串	可驗認證中宣告的名稱
indexed	布林值 (預設值 false)	指出這個宣告的值是否用於搜尋；指定的合約只允許一個 clientMapping 物件編製索引
required	布林值 (預設值 false)	指出是否需要此對應
type	字串 (選擇性)	宣告的類型

customStatusEndpoint 類型

屬性	類型​	描述
url	字串 (url)	自訂狀態端點的 URL
type	字串	端點的類型

範例：

"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	字串	此顯示的地區設定
credential	displayCredential	可驗認證的顯示屬性
consent	displayConsent	核發可驗認證時的補充資料
claims	displayClaims 陣列	可驗認證中包含的宣告標籤

displayCredential 類型

屬性	類型​	描述
title	字串	認證標題
issuedBy	字串	認證簽發者的名稱
backgroundColor	數字 (十六進位)	以十六進位表示認證的背景色彩，例如，#FFAABB
textColor	數字 (十六進位)	以十六進位表示認證的文字色彩，例如，#FFAABB
description	字串	每個認證顯示的補充文字
logo	displayCredentialLogo	要用於認證的標誌

displayCredentialLogo 類型

屬性	類型​	描述
uri	字串 (URI)	標誌的 URI。 如果這是 URL，則必須可透過公用網際網路匿名連線。
description	字串	標誌的描述

displayConsent 類型

屬性	類型​	描述
title	字串	同意的標題
instructions	字串	顯示同意時要使用的補充文字

displayClaims 類型

屬性	類型​	描述
label	字串	顯示中宣告的標籤
claim	字串	套用標籤的宣告名稱
type	字串	宣告的類型
description	字串 (選擇性)	宣告的描述

範例：

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

列出合約

此 API 會列出所指定授權單位目前租用戶中設定的所有合約。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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
}

認證

此端點可讓您搜尋已發出的可驗認證、檢查撤銷狀態和撤銷認證。

方法

方法	傳回類型	描述
取得認證	認證	讀取認證的屬性
搜尋認證	認證集合	搜尋具有特定宣告值的認證清單
撤銷認證		撤銷特定認證

取得認證

此 API 可讓您擷取特定認證，並檢查狀態以查看是否已將其撤銷。

HTTP 要求

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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"
}

搜尋認證

您可以搜尋 具有特定索引宣告的可驗認證。 因為只會儲存雜湊，所以您必須搜尋特定的計算值。 您需要使用的演算法是：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}

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	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"
        }
    ]
}

撤銷認證

此 API 可讓您撤銷特定認證。在使用搜尋 API 搜尋認證之後，您可以指定特定認證識別碼來撤銷認證。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

請不要為此方法提供要求本文。

回應訊息

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

退出

此方法會完全移除此租用戶中可驗認證服務的所有執行個體。 其會移除所有已設定的合約。 無法檢查每個發出的可驗認證是否撤銷。 此動作無法復原。

警告

此動作無法復原，且會使所有已發出的可驗認證和已建立的合約失效。

HTTP 要求

POST /v1.0/verifiableCredentials/optout

要求標頭

標頭	數值
授權	持有人 (權杖)。 必要
內容-類型	application/json

要求本文

請不要提供此方法的要求本文

回應訊息

範例回應訊息

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

OK

備註

注意

如果您在 Key Vault 上沒有刪除權限，我們會傳回錯誤訊息，且仍會退出

下一步

• 指定要求服務 REST API 簽發要求
• Microsoft Entra 驗證識別碼網路 API (部分機器翻譯)