要求服務 REST API 展示規格

發行項
12/05/2022

注意

Azure Active Directory 可驗認證現在是 Microsoft Entra 驗證識別碼，並且是 Microsoft Entra 系列產品的一部分。深入了解 Microsoft Entra 系列身分識別解決方案，並開始使用統一的 Microsoft Entra 系統管理中心。

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>

{
    "includeQRCode": true,
    "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",
    "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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

承載包含下列屬性。

參數	類型	描述
`includeQRCode`	Boolean	判斷 QR 代碼是否包含在此要求的回應中。顯示 QR 代碼，並要求使用者進行掃描。掃描 QR 代碼便會以此展示要求啟動驗證器應用程式。可能的值為 `true` (預設) 或 `false`。當您將值設定為 `false` 時，請使用傳回 `url` 屬性來呈現深層連結。
`includeReceipt`	Boolean	判斷是否應在此要求的回應中包含回條。可能的值為：`true` 或 `false` (預設)。回條包含從驗證器傳送到可驗認證服務的原始承載。針對疑難排解，或您需要取得承載的完整詳細資料時，回條十分有用。否則，預設不需要將此值設定為 `true` 。在 `OpenId Connect SIOP` 要求中，回條包含來自原始要求的識別碼權杖。
`authority`	字串	您驗證器 Azure AD 租用戶的分散式識別碼 (DID)。如需詳細資訊，請參閱收集租用戶詳細資料來設定您的範例應用程式。
`registration`	RequestRegistration	提供驗證器的相關資訊。
`callback`	回呼	Mandatory。允許開發人員在可驗認證展示程序期間更新 UI。當使用者完成此程式時，將結果傳回給應用程式之後繼續執行程序。
`requestedCredentials`	collection	RequestCredential 物件的集合。

RequestRegistration 類型

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

屬性	類型	描述
`clientName`	字串	可驗認證簽發者的顯示名稱。此名稱將會向驗證器應用程式中的使用者顯示。

下列螢幕擷取畫面顯示展示要求中的 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`	字串	提供要求此可驗認證的目的相關資訊。
`acceptedIssuers`	字串集合	簽發者的分散式識別碼集合，可發出主體可驗認證類型。若要取得您的簽發者，請參閱收集認證和環境詳細資料來設定您的範例應用程式，並複製分散式識別碼 (DID)值。如果 `acceptedIssuers` 集合是空的，則表示要求會接受由任何簽發者發出的認證類型。
`configuration.validation`	Configuration.Validation	出示驗證的選用設定。

Configuration.Validation 類型

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

屬性	類型	描述
`allowRevoked`	Boolean	判斷是否應該接受已撤銷的認證。預設值為 `false` (不應該接受)。
`validateLinkedDomain`	Boolean	判斷是否應該驗證已連結網域。預設為 `false`。將此旗標設定為 `false` 表示您作為信賴憑證者應用程式接受來自未驗證連結網域的認證。將此旗標設定為 `true` 表示將會驗證已連結網域，並且只接受已驗證網域。

成功的回應

如果成功，這個方法會傳回回應碼 (已建立 HTTP 201)，以及回應本文中的事件物件集合。下列 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/request/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`：可驗認證驗證已順利完成。
`state`	字串	傳回您在原始裝載中傳遞的狀態值。
`subject`	字串	可驗認證使用者分散式識別碼。
`issuers`	array	傳回所要求可驗認證的陣列。針對每個可驗認證，會提供：可驗認證類型。簽發者的 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:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
  "verifiedCredentialsData": [
    {
      "issuer": "did:ion:issuer",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      }
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

後續步驟

瞭解如何呼叫服務 REST API 的要求。