要求服務 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 要求。 tenantId
不再需要在 URL 中,因為它會以 中的access_token
宣告的形式出現。
https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
下列 HTTP 要求示範對要求服務 REST API 的簡報要求:
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer <token>
{
"includeQRCode": true,
"callback": {
"url": "https://contoso.com/api/verifier/presentationCallback",
"state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"headers": {
"api-key": "an-api-key-can-go-here"
}
},
...
}
需要下列許可權才能呼叫要求服務 REST API。 如需詳細資訊,請參閱 授與許可權以取得存取令牌。
權限類型 | 權限 |
---|---|
申請 | 3db474b9-6a0c-4840-96ac-1fceb342124f/.default |
簡報要求承載
簡報要求承載包含可驗證認證簡報要求的相關信息。 下列範例示範來自特定簽發者的簡報要求。 此要求的結果會傳回 QR 代碼,其中包含啟動簡報程式的連結。
{
"includeQRCode": true,
"includeReceipt": true,
"authority": "did:web:verifiedid.contoso.com",
"registration": {
"clientName": "Veritable Credential Expert Verifier"
},
"callback": {
"url": "https://contoso.com/api/verifier/presentationCallback",
"state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
"headers": {
"api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
}
},
"requestedCredentials": [
{
"type": "VerifiedCredentialExpert",
"purpose": "So we can see that you a veritable credentials expert",
"acceptedIssuers": [
"did:web:verifiedid.contoso.com"
],
"configuration": {
"validation": {
"allowRevoked": false,
"validateLinkedDomain": false
}
}
}
]
}
承載包含下列屬性。
參數 | 類型 | 描述 |
---|---|---|
includeQRCode |
布林值 | 選擇性。 判斷 QR 代碼是否包含在此要求的回應中。 顯示 QR 代碼,並要求用戶掃描它。 掃描 QR 代碼會使用此簡報要求啟動驗證器應用程式。 可能的值為 true (預設值) 或 false 。 當您將值設定為 false 時,請使用 return url 屬性來轉譯深層連結。 |
includeReceipt |
布林值 | 選擇性。 判斷收據是否應該包含在此要求的回應中。 可能的值為 true 或 false (預設值)。 收據包含從驗證器傳送至可驗證認證服務的原始承載。 收據對於疑難解答很有用,或者如果您需要取得承載的完整詳細數據。 否則,預設不需要將此值設定為 true 。 在要求中 OpenId Connect SIOP ,收據包含來自原始要求的標識符令牌。 |
authority |
string | 您的驗證器 Microsoft Entra 租使用者的分散式識別碼 (DID)。 如需詳細資訊,請參閱 收集租使用者詳細數據以設定範例應用程式。 |
registration |
RequestRegistration | 提供驗證程序的相關信息。 |
callback |
回調 | 必要。 可讓開發人員在可驗證的認證呈現程式期間更新UI。 當使用者完成此程式時,在結果傳回給應用程式之後繼續程式。 |
requestedCredentials |
collection | RequestCredential 物件的集合。 |
RequestRegistration 類型
此 RequestRegistration
類型會提供簽發者的資訊註冊。 這個 RequestRegistration
類型包含下列屬性:
屬性 | 類型 | 描述 |
---|---|---|
clientName |
string | 可驗證認證之驗證者的顯示名稱。 此名稱會顯示給驗證器應用程式中的使用者。 |
purpose |
string | 選擇性。 顯示的字串,告知使用者要求可驗證認證的原因。 |
logoUrl |
URL | 選擇性。 驗證工具標誌類型的 URL。 驗證器應用程式不會使用此專案。 |
termsOfServiceUrl |
URL | 選擇性。 驗證程式服務條款的 URL。 驗證器應用程式不會使用此專案。 |
下列螢幕快照顯示 clientName
簡報要求中的 屬性和顯示名稱 authority
(驗證器)。
回呼類型
要求服務 REST API 會產生數個事件給回呼端點。 這些事件可讓您更新UI,並在結果傳回應用程式之後繼續程式。 這個 Callback
類型包含下列屬性:
屬性 | 類型 | 描述 |
---|---|---|
url |
string | 應用程式回呼端點的 URI。 URI 必須指向因特網上的可連線端點,否則服務會擲回回呼 URL 無法讀取的錯誤。 接受的輸入 IPv4、IPv6 或 DNS 可解析主機名。 |
state |
string | 將回呼事件與傳入原始承載的狀態相互關聯。 |
headers |
string | 選擇性。 您可以包含 POST 訊息接收端所需的 HTTP 標頭集合。 目前支持的標頭值是 api-key 或 Authorization 標頭。 任何其他標頭都會擲回無效的回呼標頭錯誤。 |
RequestCredential 類型
RequestCredential
提供使用者所需提供之要求認證的相關信息。 RequestCredential
包含下列屬性:
屬性 | 類型 | 描述 |
---|---|---|
type |
string | 可驗證的認證類型。 type 必須符合可驗證認證指令清單中所issuer 定義的型別(例如 , VerifiedCredentialExpert 。 若要取得簽發者指令清單,請參閱 收集認證和環境詳細數據,以設定範例應用程式。 複製 [ 問題認證 URL],在網頁瀏覽器中開啟它,然後檢查 id 屬性。 |
purpose |
string | 選擇性。 提供要求此可驗證認證之目的的相關信息。 驗證器應用程式不會使用此專案。 |
acceptedIssuers |
字串集合 | 選擇性。 簽發者的 DID 集合,可發出主體可以呈現的可驗證認證類型。 若要取得您的簽發者 DID,請參閱收集認證和環境詳細數據來設定範例應用程式,並複製分散式標識碼 (DID) 的值。 acceptedIssuers 如果集合是空的或不存在的,則表示要求會接受任何簽發者所發出的認證類型。 |
configuration.validation |
Configuration.Validation | 簡報驗證的選擇性設定。 |
constraints |
條件約束 | 選擇性。 宣告條件約束的集合。 |
Configuration.Validation 類型
提供 Configuration.Validation
如何驗證所呈現認證的相關信息。 它包含下列屬性:
屬性 | 類型 | 描述 |
---|---|---|
allowRevoked |
布林值 | 選擇性。 判斷是否應接受撤銷的認證。 預設值為 false (不應接受)。 |
validateLinkedDomain |
布林值 | 選擇性。 判斷是否應該驗證連結網域。 預設值為 false 。 設定此旗標表示 false 您作為信賴憑證者應用程式接受來自未驗證連結網域的認證。 將此旗標設定為 true 表示會驗證連結網域,且只會接受已驗證的網域。 |
faceCheck |
faceCheck | 選擇性。 允許在簡報期間要求活躍度檢查。 |
條件約束類型
此 constraints
類型包含宣告條件約束集合,當錢包選取候選認證時,必須符合此條件約束。 這可讓要求具有特定宣告值的認證。 指定的條件約束會使用 AND 邏輯,例如,如果您指定三個條件約束,則所有條件約束都必須符合。 針對集合中的每個條件約束,您必須選取一個值操作數,包含或 startsWith。 值不可以是正則表達式。 所有比較都不區分大小寫。
屬性 | 類型 | 描述 |
---|---|---|
claimName |
string | 必要。 條件約束的宣告名稱。 這是可驗證認證中的宣告名稱。 請參閱 claimMapping 類型中的 outputClaim 。 |
values |
字串集合 | 應符合宣告值的值集合。 如果您指定多個值,例如 [“red”、“green”、“blue”],則如果認證中的宣告值具有集合中的任何值,則為相符值。 |
contains |
string | 如果宣告值包含指定的值,條件約束會評估為 true。 |
startsWith |
string | 如果宣告值以指定的值開頭,條件約束會評估為 true。 |
faceCheck 類型
faceCheck 類型包含認證呈現期間執行活躍度檢查的資訊。 要求的認證必須包含sourcePhotoClaimName所命名之宣告中的持有者相片。 如果實況檢查達到信賴等級等於或大於屬性 matchConfidenceThreshold 中指定的專案,簡報將會成功。 如果不符合閾值,整個簡報將會失敗。
屬性 | 類型 | 描述 |
---|---|---|
sourcePhotoClaimName |
string | 必要。 包含相片之認證中的宣告名稱。 請參閱 claimMapping 類型中的 outputClaim 。 |
matchConfidenceThreshold |
integer | 選擇性。 相片與活躍度數據之間成功檢查的機密閾值。 必須是介於 50 到 100 之間的整數。 預設值為 70。 |
成功的回覆
如果成功,這個方法會傳回回應碼 (HTTP 201 Created),以及響應主體中的事件物件集合。 下列 JSON 示範成功的回應:
{
"requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
"url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
"expiry": 1633017751,
"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 | 驗證器應用程式擷取要求時所傳回的狀態。 可能的值:
presentation_error :簡報發生錯誤。 |
state |
string | 傳回您傳入原始承載的狀態值。 |
subject |
string | 可驗證的認證使用者 DID。 |
verifiedCredentialsData |
陣列 | 傳回要求的可驗證認證陣列。 針對每個可驗證的認證,它提供: |
receipt |
string | 選擇性。 收據包含從錢包傳送至可驗證認證服務的原始承載。 收據應該僅用於疑難解答/偵錯。 收據中的格式無法修正,而且可以根據使用的錢包和版本變更。 |
下列範例示範驗證器應用程式啟動簡報要求時的回呼承載:
{
"requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
"requestStatus":"request_retrieved",
"state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}
下列範例示範可驗證認證簡報成功完成之後的回呼承載:
{
"requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
"requestStatus": "presentation_verified",
"state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
"subject": "did:web:verifiedid.contoso.com",
"verifiedCredentialsData": [
{
"issuer": "did:web:issuer...",
"type": [
"VerifiableCredential",
"VerifiedCredentialExpert"
],
"claims": {
"firstName": "Megan",
"lastName": "Bowen"
},
"credentialState": {
"revocationStatus": "VALID"
},
"domainValidation": {
"url": "https://contoso.com/"
},
"issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
"expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
}
],
"receipt": {
"id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
"vp_token": "...",
"state": "..."
}
}
下一步
瞭解如何 呼叫要求服務 REST API。
意見反映
https://aka.ms/ContentUserFeedback。
即將推出:我們會在 2024 年淘汰 GitHub 問題,並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊,請參閱:提交及檢視以下的意見反映: