要求服務 REST API 呈現規格

發行項
02/07/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 要求。 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": "11111111-2222-2222-2222-333333333333",
      "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/12345678-0000-0000-0000-000000000000/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	驗證器應用程式擷取要求時所傳回的狀態。可能的值： `request_retrieved`：用戶掃描 QR 代碼，或選取啟動簡報流程的連結。 `presentation_verified`：可驗證的認證驗證已順利完成。 li>`presentation_error`：簡報發生錯誤。
`state`	string	傳回您傳入原始承載的狀態值。
`subject`	string	可驗證的認證使用者 DID。
`verifiedCredentialsData`	陣列	傳回要求的可驗證認證陣列。針對每個可驗證的認證，它提供：可驗證的認證類型（s）。簽發者的 DID 擷取的宣告。可驗證的認證簽發者的網域。可驗證認證簽發者的網域驗證狀態。
`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。