要求服務 REST API 發行規格

發行項
02/25/2024

Microsoft Entra 驗證識別碼包含要求服務 REST API。此 API 可讓您發出並驗證認證。本文指定發行要求的要求服務 REST API。另一篇文章說明如何呼叫要求服務 REST API。

HTTP 要求

要求服務 REST API 發行要求支援下列 HTTP 方法：

方法	注意
POST	使用本文中指定的 JSON 承載。

要求服務 REST API 發行要求需要下列 HTTP 標頭：

名稱	值
`Authorization`	將存取令牌作為持有人令牌附加至 HTTP 要求中的授權標頭。例如： `Authorization: Bearer <token>` 。
`Content-Type`	`application/json`

建構對要求服務 REST API 的 HTTP POST 要求。

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest

下列 HTTP 要求示範要求服務 REST API 的要求：

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>

{
    "includeQRCode": true,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

需要下列許可權才能呼叫要求服務 REST API。如需詳細資訊，請參閱授與許可權以取得存取令牌。

權限類型	權限
申請	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

發行要求承載

發行要求承載包含可驗證認證發行要求的相關信息。下列範例示範使用 PIN 碼流程搭配使用者宣告的發行要求，例如名字和姓氏。此要求的結果會傳回 QR 代碼，其中包含啟動發行程式的連結。

{
  "includeQRCode": false,
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

承載包含下列屬性：

參數	類型	描述
`includeQRCode`	布林值	判斷 QR 代碼是否包含在此要求的回應中。顯示 QR 代碼，並要求用戶掃描它。掃描 QR 代碼會使用此發行要求啟動驗證器應用程式。可能的值為 `true` （預設值）或 `false`。當您將值設定為 `false`時，請使用 return `url` 屬性來轉譯深層連結。
`callback`	回調	必要。可讓開發人員在可驗證的認證發行程序期間，以異步方式取得流程的相關信息。例如，當使用者掃描 QR 代碼或發行要求成功或失敗時，開發人員可能會想要呼叫。
`authority`	string	簽發者的分散式標識碼（DID）。如需詳細資訊，請參閱收集認證和環境詳細數據，以設定範例應用程式。
`registration`	RequestRegistration	提供可在驗證器應用程式中顯示之簽發者的相關信息。
`type`	string	可驗證的認證類型。應該符合可驗證認證指令清單中所定義的類型。例如： `VerifiedCredentialExpert` 。如需詳細資訊，請參閱在 Azure 中建立已驗證的認證專家卡片。
`manifest`	string	可驗證認證指令清單檔的 URL。如需詳細資訊，請參閱收集認證和環境詳細數據，以設定範例應用程式。
`claims`	string	選擇性。只能用於標識元令牌提示證明流程，以在可驗證認證中包含有關主體的判斷提示集合。
`pin`	針	選擇性。 PIN 碼只能與標識元令牌提示證明流程搭配使用。在發行期間提供額外安全性的 PIN 號碼。您會產生 PIN 碼，並將它呈現給應用程式中的使用者。用戶必須提供您產生的 PIN 碼。
`expirationDate`	string	選擇性。 expirationDate 只能與標識符令牌提示證明流程搭配使用。如果指定，該值必須是以ISO8601格式表示的日期。日期將會覆寫此發行要求的認證規則定義中的 validityInterval 。使用此設定可明確控制認證到期的時間，例如，無論何時發出認證，例如結束、月底或年底。請注意，日期是以UTC格式表示。如果您指定年終，且時間設定為 `23:59:59`，也就是 UTC 時間的午夜 1 秒。不同時區中的任何用戶都會取得 Microsoft Authenticator 中當地時區中顯示的到期日。這表示，如果您位於 CET 時區，則會在上午 1 點顯示為 1 月 1 日。認證合約必須將旗標 allowOverrideValidityOnIssuance 設定為 true。

您目前可以在承載中傳送四種宣告證明類型。 Microsoft Entra 驗證識別碼使用四種方式將宣告插入可驗證的認證，並證明該資訊與簽發者的 DID。以下是四種類型：

標識元令牌
標識元令牌提示
透過可驗證的簡報驗證認證
自我證明的宣告

您可以在自訂可驗證認證中找到輸入類型的詳細資訊。

RequestRegistration 類型

此 RequestRegistration 類型會提供簽發者的資訊註冊。這個 RequestRegistration 類型包含下列屬性：

屬性	類型	描述
`clientName`	string	可驗證認證的簽發者的顯示名稱。
`logoUrl`	string	選擇性。簽發者標誌的 URL。
`termsOfServiceUrl`	string	選擇性。您發出之可驗證認證的使用規定 URL。

注意

目前， RequestRegistration 在 Microsoft Authenticator 應用程式中的發行期間不會顯示資訊。不過，這項資訊可以在承載中使用。

回呼類型

要求服務 REST API 會產生數個事件給回呼端點。這些事件可讓您更新UI，並在結果傳回應用程式之後繼續程式。這個 Callback 類型包含下列屬性：

屬性	類型	描述
`url`	string	應用程式回呼端點的 URI。 URI 必須指向因特網上的可連線端點，否則服務會擲回回呼 URL 無法讀取的錯誤。接受的格式 IPv4、IPv6 或 DNS 可解析主機名
`state`	string	將回呼事件與傳入原始承載的狀態相互關聯。
`headers`	string	選擇性。您可以包含 POST 訊息接收端所需的 HTTP 標頭集合。目前支持的標頭值是 `api-key` 或 `Authorization` 標頭。任何其他標頭都會擲回無效的回呼標頭錯誤

釘選類型

此 pin 類型會定義可顯示為發行一部分的 PIN 碼。 pin 是選擇性的，如果使用的話，應該一律從頻外傳送。當您使用HASH PIN碼時，必須定義 salt、 alg和 iterations 屬性。 pin 包含下列屬性：

屬性	類型	描述
`value`	string	包含純文字中的 PIN 值。當您使用哈希 PIN 時，value 屬性會包含已編碼的 salted 哈希 base64。
`type`	string	PIN 碼的類型。可能的值： `numeric` （預設值）。
`length`	整數	PIN 碼的長度。默認長度為 6，最小值為 4，最大值為 16。
`salt`	string	哈希 PIN 碼的 Salt。 Salt 會在哈希計算期間加上。編碼：UTF-8。
`alg`	string	哈希 PIN 的哈希演算法。支持的演算法： `sha256`。
`iterations`	整數	哈希反覆運算的數目。可能的值： `1`。

成功的回覆

如果成功，這個方法會傳回回應碼（HTTP 201 Created），以及響應主體中的事件物件集合。下列 JSON 示範成功的回應：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
}

回應包含下列屬性：

屬性	類型	描述
`requestId`	string	自動產生的要求標識碼。回呼使用相同的要求，可讓您追蹤發行要求及其回呼。
`url`	string	啟動驗證器應用程式的 URL，並啟動發行程式。如果使用者無法掃描 QR 代碼，您可以將此 URL 呈現給使用者。
`expiry`	整數	指出回應何時到期。
`qrCode`	string	用戶可以掃描以啟動發行流程的 QR 代碼。

當您的應用程式收到回應時，應用程式必須向用戶顯示 QR 代碼。用戶會掃描 QR 代碼，這會開啟驗證器應用程式並啟動發行程式。

回覆錯誤

如果要求發生錯誤，則會傳回錯誤回應，而且應該由應用程式適當地處理。

回呼事件

當用戶掃描 QR 代碼、使用驗證器應用程式的深層連結或完成發行程式時，就會呼叫回呼端點。

屬性	類型	描述
`requestId`	string	當承載張貼至可驗證認證服務時，對應至原始要求。
`requestStatus`	string	要求傳回的狀態。可能的值： `request_retrieved`：用戶掃描 QR 代碼，或選取啟動發行流程的連結。 `issuance_successful`：可驗證認證的發行成功。 `issuance_error`：發行期間發生錯誤。如需詳細資訊，請參閱 `error` 屬性。
`state`	string	傳回您傳入原始承載的狀態值。
`error`	error	`code`當屬性值為 `issuance_error`時，這個屬性會包含錯誤的相關信息。
`error.code`	string	傳回錯誤碼。
`error.message`	string	錯誤訊息。

下列範例示範驗證器應用程式啟動發行要求時回呼承載：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

下列範例示範使用者成功完成發行程序之後的回呼承載：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

回呼錯誤

回呼端點可能會以錯誤訊息呼叫。下表列錯誤碼：

訊息	定義
`fetch_contract_error`	無法擷取可驗證的認證合約。當 API 無法擷取您在要求承載 RequestIssuance 物件中指定的指令清單時，通常會發生此錯誤。
`issuance_service_error`	可驗證認證服務無法驗證需求，或可驗證認證發生錯誤。
`unspecified_error`	此錯誤並不常見，但值得調查。

下列範例示範發生錯誤時的回呼承載：

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
}

下一步

瞭解如何呼叫要求服務 REST API。