要求服務 REST API 展示規格

發行項
10/24/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 要求。 URL 中不再需要 tenantId，因為其在 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>

{
    "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 代碼，其中含有可啟動展示程序的連結。

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "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 代碼便會以此展示要求啟動 Authenticator 應用程式。可能的值為 `true` 或 `false` (預設)。當您將值設定為 `false` 時，請使用傳回 `url` 屬性來呈現深層連結。
`includeReceipt`	布林值	選擇性。判斷是否應在此要求的回應中包含回條。可能的值為：`true` 或 `false` (預設)。回條包含從驗證器傳送到可驗認證服務的原始承載。針對疑難排解，或您需要取得承載的完整詳細資料時，回條十分有用。否則，預設不需要將此值設定為 `true` 。在 `OpenId Connect SIOP` 要求中，回條包含來自原始要求的識別碼權杖。
`authority`	字串	您驗證器 Microsoft Entra 租用戶的分散式識別碼 (DID)。如需詳細資訊，請參閱收集租用戶詳細資料來設定您的範例應用程式。
`registration`	RequestRegistration	提供驗證器的相關資訊。
`callback`	回呼	必要。允許開發人員在可驗認證展示程序期間更新 UI。當使用者完成此程式時，將結果傳回給應用程式之後繼續執行程序。
`requestedCredentials`	collection	RequestCredential 物件的集合。

RequestRegistration 類型

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

屬性	類型	描述
`clientName`	字串	可驗認證驗證器的顯示名稱。此名稱將會向驗證器應用程式中的使用者顯示。
`purpose`	字串	選擇性。顯示的字串，告知使用者要求可驗認證的原因。
`logoUrl`	URL	選擇性。驗證器商標的 URL。 Authenticator 應用程式不會使用此項目。
`termsOfServiceUrl`	URL	選擇性。驗證器服務條款的 URL。 Authenticator 應用程式不會使用此項目。

下列螢幕擷取畫面顯示展示要求中的 clientName 屬性和 authority (驗證器) 顯示名稱。

螢幕擷取畫面，其中顯示如何核准出示要求。

回呼類型

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

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

RequestCredential 類型

RequestCredential 提供使用者需要提供的要求認證相關資訊。 RequestCredential 包含下列屬性：

屬性	類型	描述
`type`	字串	可驗認證類型。 `type` 必須符合 `issuer` 可驗認證資訊清單中所定義的類型 (例如 `VerifiedCredentialExpert`)。若要取得簽發者資訊清單，請參閱收集認證和環境詳細資料，以設定您的範例應用程式。複製問題認證 URL，在網頁瀏覽器中開啟，然後檢查識別碼屬性。
`purpose`	字串	選擇性。提供要求此可驗認證的目的相關資訊。 Authenticator 應用程式不會使用此項目。
`acceptedIssuers`	字串集合	選擇性。簽發者的分散式識別碼集合，可發出主體可驗認證類型。若要取得您的簽發者，請參閱收集認證和環境詳細資料來設定您的範例應用程式，並複製分散式識別碼 (DID)值。如果 `acceptedIssuers` 集合為空或不存在，則出示要求會接受由任何簽發者發出的認證類型。
`configuration.validation`	Configuration.Validation	出示驗證的選用設定。
`constraints`	條件約束	選擇性。宣告條件約束的集合。

Configuration.Validation 類型

Configuration.Validation 提供應該如何驗證所出示認證的相關資訊。它包含下列屬性：

屬性	類型	描述
`allowRevoked`	布林值	選擇性。判斷是否應該接受已撤銷的認證。預設值為 `false` (不應該接受)。
`validateLinkedDomain`	布林值	選擇性。判斷是否應該驗證已連結網域。預設值為 `false`。將此旗標設定為 `false` 表示您作為信賴憑證者應用程式接受來自未驗證連結網域的認證。將此旗標設定為 `true` 表示將會驗證已連結網域，並且只接受已驗證網域。
`faceCheck`	faceCheck	選擇性。允許在出示期間要求活躍度檢查。

條件約束類型

constraints 類型包含宣告條件約束的集合，在電子錢包選取候選認證時，必須符合此條件約束。如此便可要求具有特定宣告值的認證。指定的條件約束會使用 AND 邏輯，例如，如果您指定三個條件約束，則所有條件約束都必須符合。針對集合中的每個條件約束，您必須選取一個運算元：values、contains 或 startsWith。值不可以是規則運算式。所有比較皆不區分大小寫。

屬性	類型	描述
`claimName`	字串	必要。條件約束的宣告名稱。這是可驗認證中的宣告名稱。請參閱 claimMapping 類型中的 outputClaim。
`values`	字串集合	應符合宣告值的值集合。如果您指定多個值，例如 ["red", "green", "blue"]，則如果認證中的宣告值具有集合中的任何值，即為相符。
`contains`	字串	如果宣告值包含指定的值，條件約束會評估為 true。
`startsWith`	字串	如果宣告值以指定的值開頭，條件約束會評估為 true。

faceCheck 類型

faceCheck 類型包含認證出示期間執行活躍度檢查的資訊。要求的認證必須在名稱 sourcePhotoClaimName 的宣告中包含持有者相片。如果活躍度檢查達到的信賴等級等於或大於屬性 matchConfidenceThreshold 中指定的內容，出示將會成功。如果不符合閾值，整個出示將會失敗。

屬性	類型	描述
`sourcePhotoClaimName`	字串	必要。認證中包含相片的宣告名稱。請參閱 claimMapping 類型中的 outputClaim。
`matchConfidenceThreshold`	integer	選擇性。相片與活躍度資料之間成功檢查的機密閾值。必須為介於 50 到 100 之間的整數。預設值為 70。

成功回應

如果成功，這個方法會傳回回應碼 (已建立 HTTP 201)，以及回應本文中的事件物件集合。下列 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`	字串	自動產生的要求識別碼。回呼會使用相同的要求，讓您能夠追蹤展示要求和回呼。
`url`	字串	啟動驗證器應用程式並開始展示程序的 URL。如果使用者無法掃描 QR 代碼，您可以向使用者顯示此 URL。
`expiry`	整數	指出回應將到期的時間。
`qrCode`	字串	使用者可掃描以啟動展示流程的 QR 代碼。

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

回覆錯誤

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

回呼事件

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

屬性	類型	描述
`requestId`	字串	當承載張貼至可驗認證服務時，對應至原始要求。
`requestStatus`	字串	驗證器應用程式擷取要求時所傳回的狀態。可能的值： `request_retrieved`：使用者已掃描 QR 代碼，或已選取啟動展示流程的連結。 `presentation_verified`：可驗認證驗證已順利完成。 li>`presentation_error`：出示時發生錯誤。
`state`	字串	傳回您在原始裝載中傳遞的狀態值。
`subject`	字串	可驗認證使用者分散式識別碼。
`verifiedCredentialsData`	陣列	傳回所要求可驗認證的陣列。針對每個可驗認證，會提供：可驗認證類型。簽發者的 DID 已擷取的宣告。可驗認證簽發者網域。可驗認證簽發者的網域驗證狀態。
`receipt`	字串	選擇性。回條包含從錢包傳送到可驗認證服務的原始承載。回條應僅用於疑難排解/偵錯工具。回條中的格式無法進行修正，而且可能會根據使用的錢包和版本而變更。

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

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

共用方式為