可驗證的認證管理員 API

Microsoft Entra 驗證識別碼 管理員 API 可讓您管理可驗證認證服務的所有層面。 它提供一種方式來設定全新的服務、管理和建立可驗證的認證合約、撤銷可驗證的認證，以及完全退出服務。

API 適用於熟悉 RESTful API 的開發人員，以及 Microsoft Entra 租使用者上足夠的許可權，以啟用服務

基礎 URL

管理員 API 是透過 HTTPS 的伺服器。 文件中參考的所有 URL 都有下列基底： https://verifiedid.did.msidentity.com。

驗證

API 會透過 Microsoft Entra 識別碼受到保護，並使用 OAuth2 持有人令牌。 存取令牌可以是使用者或應用程式。

使用者持有人令牌

應用程式註冊必須具有的 API 許可權 Verifiable Credentials Service Admin ，然後在取得存取權杖時，應用程式應該使用範圍 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	從 已驗證標識元網路讀取項目的許可權

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

如果應用程式想要建立新的授權單位，則需要兩件事。 首先，應用程式註冊需要 VerifiableCredential.Authority.ReadWrite 許可權。 其次，應用程式需要有 Create Key 金鑰保存庫 存取原則的許可權。 如果應用程式只讀取/寫入現有的授權單位，則不需要 金鑰保存庫 許可權。

登入

此 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": "90e10a26-94cd-49d6-8cd7-cacb10f00686",
    "verifiableCredentialRequestServicePrincipalId": "870e10a26-94cd-49d6-8cd7-cacb10f00fe",
    "verifiableCredentialAdminServicePrincipalId": "760e10a26-94cd-49d6-8cd7-cacb10f00ab",
    "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": "ffea7eb3-0000-1111-2222-000000000000",
    "name": "ExampleAuthorityName",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vccontosokv",
        "resourceUrl": "https://vccontosokv.vault.azure.net/"
    }
}

回應包含下列屬性。

授權單位類型

屬性	類型​	描述
Id	string	自動產生的唯一標識符，可用來擷取或更新可驗證認證服務的特定實例
name	string	可驗證認證服務的這個實例易記名稱
status	string	服務的狀態，此值一律為 enabled
didModel	didModel	DID 和金鑰的相關信息
keyVaultMetadata	keyVaultMeta 數據	所使用 金鑰保存庫的相關信息

didModel 類型

Web

屬性	類型​	描述
did	string	這個可驗證認證服務實例的 DID
signingKeys	字串陣列	簽署金鑰的 URL
linkedDomainUrls	字串陣列	連結至此 DID 的網域，預期有一個專案
didModel	didModel	DID 和金鑰的相關信息
didDocumentStatus	string	DID 的狀態，這個方法的值一律 published 為

keyVaultMetadata 類型

屬性	類型​	描述
subscriptionId	string	此 金鑰保存庫 所在的 Azure 訂用帳戶
resourceGroup	string	此 金鑰保存庫的資源群組名稱
resourceName	string	金鑰保存庫 名稱
resourceUrl	string	此 金鑰保存庫的 URL

清單授權單位

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

HTTP 要求

GET /v1.0/verifiableCredentials/authorities

要求標頭

標頭	數值
授權	持有人（令牌）。 必要
內容-類型	application/json

要求本文

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

回應消息

回應訊息是法律檔範例的陣列：

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

    [
        {
            "id": "ffea7eb3-0000-1111-2222-000000000000",
            "name": "AuthorityName",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid.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": "AuthorityName2",
            "keyVaultUrl": "https://vccontosokv.vault.azure.net/",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid2.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid2.contoso.com/"
                ],
                "didDocumentStatus": "published"
            },
            "keyVaultMetadata": {
                "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
                "resourceGroup": "verifiablecredentials",
                "resourceName": "vccontosokv",
                "resourceUrl": "https://vccontosokv.vault.azure.net/"
            }
        }
    ]
}

建立授權單位

此呼叫會建立新的私鑰、修復金鑰和更新金鑰、將這些金鑰儲存在指定的 Azure 金鑰保存庫 中，並將可驗證認證服務的許可權設定為此 金鑰保存庫，並使用對應的 DID 檔案建立新的 DID。

HTTP 要求

POST /v1.0/verifiableCredentials/authorities

要求標頭

標頭	數值
授權	持有人（令牌）。 必要
內容-類型	application/json

要求本文

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

屬性	類型​	描述
name	string	此服務實例的顯示名稱
linkedDomainUrl	string	連結至此 DID 的網域
didMethod	string	必須是 web
keyVaultMetadata	keyVaultMetadata	特定金鑰保存庫的元數據

範例 訊息：

{
  "name":"ExampleName",
  "linkedDomainUrl":"https://verifiedid.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:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.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:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "submitted"
    },
    "keyVaultMetadata": {
        "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
        "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	string	此服務實例的顯示名稱

範例訊息

{
  "name":"ExampleIssuerName"
}

刪除授權單位

這個方法可用來刪除授權單位。 目前只能 did:ion 刪除授權單位。 當您刪除授權單位時，任何核發的已驗證標識符認證都會變成無效，且無法再驗證，因為發行授權單位已消失。

HTTP 要求

DELETE /beta/verifiableCredentials/authorities/:authorityId

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

要求標頭

標頭	數值
授權	持有人（令牌）。 必要
內容-類型	application/json

要求本文

沒有要求本文

回應消息

回應訊息範例：

成功刪除授權單位回應。

HTTP/1.1 200 OK

如果刪除授權單位成功，但 Azure 金鑰保存庫 金鑰的清除失敗，您會收到下列回應。

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

備註

要求呼叫端具有目標金鑰保存庫的 KEY 列表許可權。

驗證已知的 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": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "outOfSync"
    },
    "keyVaultMetadata": {
        "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
        "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": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
        "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": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": false,
    "manifestUrl": "...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": <rulesModel>,
    "displays": <displayModel[]>,
    "allowOverrideValidityIntervalOnIssuance": false
}

回應包含下列屬性

合約類型

屬性	類型​	描述
Id	string	合約標識碼
name	string	此合約的易記名稱
status	string	一律為 Enabled
manifestUrl	string	發行要求中使用的合約 URL
issueNotificationEnabled	boolean	如果使用者會收到通知，則設定為 true，使用者已準備好發出此 VC
issueNotificationAllowedToGroupOids	groupId 字串的陣列	此認證的群組標識子陣列將會提供給
availableInVcDirectory	boolean	此合約是否在可驗證認證網路中發佈
規則	rulesModel	規則定義
顯示	displayModel 陣列	顯示定義
allowOverrideValidityIntervalOnIssuance	boolean	如果允許 createIssuanceRequest API 呼叫覆寫認證的到期日。 這隻適用於 idTokenHint 流程。

rulesModel 類型

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

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

證明類型

屬性	類型​	描述
idTokens	idTokenAttestation （array） （選擇性）	描述標識碼令牌輸入
idTokenHints	idTokenHintAttestation （array） （選擇性）	描述標識元令牌提示輸入
presentations	verifiablePresentationAttestation （array） （選擇性）	描述可驗證的簡報輸入
selfIssued	selfIssuedAttestation （array） （選擇性）	描述自我發出的輸入
accessTokens	accessTokenAttestation （array） （選擇性）	描述存取令牌輸入

idTokenAttestation 類型

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

idTokenHintAttestation 類型

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

verifiablePresentationAttestation 類型

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

selfIssuedAttestation 類型

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

accessTokenAttestation 類型

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

屬性的支援inputClaim值為mappings：givenName、、、displayNamepreferredLanguage、userPrincipalName、、mailsurname、、 jobTitlephoto。

claimMapping 類型

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

customStatusEndpoint 類型

屬性	類型​	描述
url	字串 (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 類型

屬性	類型​	描述
locale	string	此顯示的地區設定
credential	displayCredential	可驗證認證的顯示屬性
consent	displayConsent	發出可驗證認證時的補充數據
claims	displayClaims 陣列	可驗證認證中包含的宣告標籤

displayCredential 類型

屬性	類型​	描述
title	string	認證的標題
issuedBy	string	認證簽發者的名稱
backgroundColor	數位 （十六進位）	例如，十六進位中的認證背景色彩，例如 #FFAABB
textColor	數位 （十六進位）	例如，十六進位中的認證文字色彩，例如 #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.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"
                }
            ]
        }
    ]
}

列出合約

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

HTTP 要求

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

要求標頭

標頭	數值
授權	持有人（令牌）。 必要
內容-類型	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

要求標頭

標頭	數值
授權	持有人（令牌）。 必要
內容-類型	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}],}
    "availableInVcDirectory": true
    "allowOverrideValidityIntervalOnIssuance": true
}

回應消息

範例 訊息：

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

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "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 + 宣告值）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 參數。 目前僅支援 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

備註

注意

如果您沒有 金鑰保存庫 刪除許可權，我們會傳回錯誤訊息，但仍退出宣告

下一步

• 指定要求服務 REST API 發行要求
• Microsoft Entra 驗證識別碼 網路 API