要求服務 REST API 發佈規格

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/aaaabbbb-0000-cccc-1111-dddd2222eeee/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 時，請使用傳回 url 屬性來呈現深層連結。
callback	回呼	必要。 允許開發人員在可驗認證發佈程式期間，以非同步方式取得流程的資訊。 例如，開發人員可能會想要在使用者掃描 QR 代碼時呼叫，或在發佈要求成功或失敗時呼叫。
authority	字串	簽發者的分散式識別碼 (DID)。 如需詳細資訊，請參閱收集認證和環境詳細資料，以設定您的範例應用程式。
registration	RequestRegistration	提供可在驗證器應用程式中顯示的簽發者相關資訊。
type	字串	可驗認證類型。 應符合可驗認證資訊清單中所定義的類型。 例如： VerifiedCredentialExpert 。 如需詳細資訊，請參閱在 Azure 中建立已驗證認證專家卡。
manifest	字串	可驗認證資訊清單文件的 URL。 如需詳細資訊，請參閱收集認證和環境詳細資料，以設定您的範例應用程式。
claims	字串	選擇性。 只能用於識別碼權杖提示證明流程，以在可驗認證中包含有關主體的判斷提示集合。
pin	PIN	選擇性。 PIN 碼只能使用識別碼權杖提示證明流程。 PIN 碼可在發行期間提供額外的安全性。 您會產生 PIN 碼，並將其呈現給應用程式中的使用者。 使用者必須提供您所產生的 PIN 碼。
expirationDate	字串	選擇性。 expirationDate 只能使用識別碼權杖提示證明流程。 如果指定，該值必須是以 ISO8601 格式表示的日期。 日期將會覆寫此發行要求的認證規則定義中 validityInterval。 使用此設定可明確控制認證到期的時間，例如一天結束、月底或年終，無論何時發出認證。 請注意，日期是以 UTC 格式表示。 如果您指定年終，且時間設定為 23:59:59，也就是 UTC 時間 1 秒到午夜。 不同時區中的任何用戶都會取得 Microsoft Authenticator 中當地時區顯示的到期日。 這表示，如果您位於 CET 時區，則會顯示為 1 月 1 日凌晨 1 點。 認證合約必須讓旗標 allowOverrideValidityOnIssuance 設為 true。

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

• 識別碼權杖
• 識別碼權杖提示
• 透過可驗證展示的可驗認證
• 自我證明宣告

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

RequestRegistration 類型

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

屬性	類型​	描述
clientName	字串	可驗認證簽發者的顯示名稱。
logoUrl	字串	選擇性。 簽發者標誌的 URL。
termsOfServiceUrl	字串	選擇性。 您所發佈的可驗認證使用規定 URL。

注意

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

回呼類型

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

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

PIN 類型

pin 類型會定義可在發佈過程中顯示的 PIN 碼。 pin 為選用，且如果使用的話，應該一律在頻外傳送。 當您使用雜湊 PIN 碼時，您必須定義 salt、alg 和 iterations 屬性。 pin 包含下列屬性：

屬性	類型​	描述
value	字串	在純文字中包含 PIN 值。 當您使用雜湊 PIN 時，值屬性會包含以 Salt 處理的雜湊，並以 base64 編碼。
type	字串	PIN 碼的類型。 可能的值：numeric (預設)。
length	整數	PIN 碼的長度。 預設長度為 6，最小值為 4，最大值為 16。
salt	字串	雜湊 PIN 碼的 Salt。 Salt 是在雜湊計算期間附加。 編碼：UTF-8。
alg	字串	雜湊 PIN 的雜湊演算法。 支援的演算法：sha256。
iterations	整數	雜湊反覆運算的數目。 可能值：1。

成功回應

如果成功，這個方法會傳回回應碼 (已建立 HTTP 201)，以及回應本文中的事件物件集合。 下列 JSON 示範成功的回應：

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

此回應包含下列屬性：

屬性	類型​	描述
requestId	字串	自動產生的要求識別碼。 回呼會使用相同的要求，讓您能夠追蹤發佈要求和回呼。
url	字串	啟動驗證器應用程式並開始發佈程序的 URL。 如果使用者無法掃描 QR 代碼，您可以向使用者顯示此 URL。
expiry	整數	指出回應將到期的時間。
qrCode	字串	使用者可掃描以啟動發佈流程的 QR 代碼。

當您的應用程式接收到回應時，應用程式必須向使用者顯示 QR 代碼。 使用者會掃描 QR 代碼，藉此開啟驗證器應用程式，並開始進行發佈程序。

回覆錯誤

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

回呼事件

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

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

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

{  
    "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 的要求。