可驗認證管理員 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值如下：givenNamedisplayNamepreferredLanguageuserPrincipalNamesurnamejobTitlephoto。
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.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": "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 上沒有刪除權限，我們會傳回錯誤訊息，且仍會退出
下一步
意見反映
即將推出：我們會在 2024 年淘汰 GitHub 問題，並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交及檢視以下的意見反映：