要求服務 REST API 呈現規格 (預覽)

Azure Active Directory (Azure AD) 可驗證的認證包括要求服務 REST API。 此 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} 您的租使用者識別碼或租使用者名稱。

https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request

下列 HTTP 要求會示範要求服務 REST API 的簡報要求:

POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request
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。 如需詳細資訊,請參閱 授與取得存取權杖的許可權

權限類型 權限
應用程式 bbb94529-53a3-4be5-a069-7eaf2712b826/。預設

展示要求承載

展示要求承載包含可驗證認證簡報要求的相關資訊。 下列範例示範來自特定簽發者的簡報要求。 此要求的結果會傳回 QR 代碼,其中含有可啟動展示程式的連結。

{
  "includeQRCode": true,
  "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "presentation": {
    "includeReceipt": true,
    "requestedCredentials": [
      {
        "type": "VerifiedCredentialExpert",
        "purpose": "So we can see that you a veritable credentials expert",
        "acceptedIssuers": [
          "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
        ]
      }
    ]
  }
}

承載包含下列屬性。

參數 類型 Description
includeQRCode Boolean 判斷 QR 代碼是否包含在此要求的回應中。 顯示 QR 代碼,並要求使用者進行掃描。 掃描 QR 代碼會以此展示要求啟動驗證器應用程式。 可能的值為 true (預設) 或 false。 當您將值設定為時 false ,請使用 return url 屬性來呈現深層連結。
authority 字串 您的非集中式識別碼 () 您的 verifier Azure AD 租使用者。 如需詳細資訊,請參閱 收集租使用者詳細資料來設定您的範例應用程式
registration RequestRegistration 提供有關驗證器的資訊。
presentation RequestPresentation 提供可驗證認證簡報要求的相關資訊。
callback 回檔 允許開發人員在可驗證的認證展示程式期間更新 UI。 當使用者完成此程式時,將結果傳回給應用程式之後,請繼續執行此程式。

RequestRegistration 類型

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

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

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

顯示如何核准簡報要求的螢幕擷取畫面。

RequestPresentation 類型

RequestPresentation 類型提供可驗證認證簡報所需的資訊。 RequestPresentation 包含下列屬性:

屬性 類型 Description
includeReceipt Boolean 判斷是否應在此要求的回應中包含接收。 可能的值為 truefalse (預設) 。 收據包含從驗證器傳送到可驗證認證服務的原始承載。 回條適用于疑難排解,而且不應該預設設定。 在 OpenId Connect SIOP 要求中,收據包含來自原始要求的識別碼權杖。
requestedCredentials collection RequestCredential物件的集合。

RequestCredential 類型

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

屬性 類型 Description
type 字串 可驗證的認證類型。 type必須符合可驗證認證資訊清單中所定義的類型 issuer (例如 VerifiedCredentialExpert) 。 若要取得簽發者資訊清單,請參閱 收集認證和環境詳細資料,以設定您的範例應用程式。 複製 問題認證 URL,在網頁瀏覽器中開啟它,然後檢查 id 屬性。
purpose 字串 提供要求此可驗證認證之目的的相關資訊。
acceptedIssuers 字串集合 簽發者的 DIDs 集合,可發出主體可驗證的認證類型。 若要取得您的簽發者,請參閱 收集認證和環境詳細資料來設定您的範例應用程式,並複製 (的非集中式 識別碼值)

回呼類型

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

屬性 類型 Description
url 字串 應用程式之回呼端點的 URI。
state 字串 與原始裝載中傳遞的狀態相關聯。
headers 字串 選擇性。 您可以包含 POST 訊息接收端所需的 HTTP 標頭集合。 標頭應只包含 api-key 授權所需的或任何標頭。

成功的回應

如果成功,這個方法會傳迴響應碼 (建立) 的 HTTP 201 ,以及回應本文中的事件物件集合。 下列 JSON 示範成功的回應:

{  
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid://vc/?request_uri=https://beta.did.msidentity.com/v1.0/87654321-0000-0000-0000-000000000000/verifiablecredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
} 

回應包含下列屬性:

屬性 類型 Description
requestId 字串 自動產生的相互關聯識別碼。 回呼會使用相同的要求,讓您能夠追蹤簡報要求和回呼。
url 字串 啟動驗證器應用程式並開始展示程式的 URL。 如果使用者無法掃描 QR 代碼,您可以向使用者顯示此 URL。
expiry 整數 指出回應將到期的時間。
qrCode 字串 使用者可掃描以啟動展示流程的 QR 代碼。

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

錯誤回應

也可以傳回錯誤回應,讓應用程式能夠適當地處理它們。 下列 JSON 顯示未授權的錯誤訊息:

{
    "requestId": "fb888ac646c96083de83b099b2678de0",
    "date": "Wed, 29 Sep 2021 21:49:00 GMT",
    "error": {
        "code": "unauthorized",
        "message": "Failed to authenticate the request."
    }
}

回應包含下列屬性:

屬性 類型 Description
requestId 字串 自動產生的要求識別碼。
date date 錯誤的時間。
error.code 字串 傳回錯誤碼。
error.message 字串 錯誤訊息。

回呼事件

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

屬性 類型 Description
requestId 字串 當承載張貼至可驗證的認證服務時,對應至原始要求。
code 字串 驗證器應用程式抓取要求時所傳回的程式碼。 可能的值:
  • request_retrieved:使用者已掃描 QR 代碼,或選取了啟動展示流程的連結。
  • presentation_verified:可驗證的認證驗證已順利完成。
state 字串 傳回您在原始裝載中傳遞的狀態值。
subject 字串 可驗證的認證使用者已執行。
issuers array 傳回所要求之可驗證認證的陣列。 針對每個可驗證的認證,它會提供:
  • 可驗證的認證類型。
  • 已取出的宣告。
  • 可驗證的認證簽發者網域。
  • 可驗證的認證簽發者的網域驗證狀態。
  • receipt 字串 選擇性。 收據包含從驗證器傳送到可驗證認證的原始承載。

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

    {  
        "requestId":"aef2133ba45886ce2c38974339ba1057",  
        "code":"request_retrieved",  
        "state":"Wy0ThUz1gSasAjS1"
    } 
    

    下列範例示範成功完成可驗證認證簡報之後的回呼承載:

    {
      "requestId": "87e1cb24-9096-409f-81cb-9e645f23a4ba",
      "code": "presentation_verified",
      "state": "f3d94e35-ca5f-4b1b-a7d7-a88caa05e322",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "issuers": [
        {
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "John",
            "lastName": "Doe"
          },
          "domain": "https://contoso.com/",
          "verified": "DNS",
          "issuer": "did:ion:….."
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>"
      }
    } 
    

    下一步

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