要求服務 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/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 | 要求傳回的狀態。 可能的值:
|
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。