Specyfikacja prezentacji interfejs API REST usługi żądania (wersja zapoznawcza)

Azure Active Directory (Azure AD) Weryfikowalne poświadczenia obejmują żądanie interfejs API REST usługi. Ten interfejs API umożliwia wystawienie i zweryfikowanie poświadczeń. W tym artykule określono interfejs API REST usługi żądania prezentacji. Żądanie prezentacji prosi użytkownika o przedstawienie weryfikowalnych poświadczeń, a następnie zweryfikowanie poświadczeń.

Żądanie HTTP

Żądanie interfejs API REST usługi prezentacji obsługuje następującą metodę HTTP:

Metoda Uwagi
POST Z ładunkiem JSON określonym w tym artykule.

Żądanie interfejs API REST usługi prezentacji wymaga następujących nagłówków HTTP:

Metoda Wartość
Authorization Dołącz token dostępu jako token okaziciela do nagłówka autoryzacji w żądaniu HTTP. Na przykład Authorization: Bearer <token>.
Content-Type Application/json

Skonstruuj żądanie HTTP POST do żądania interfejs API REST usługi. Zastąp {tenantID} identyfikator dzierżawy lub nazwę dzierżawy.

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

Następujące żądanie HTTP demonstruje żądanie prezentacji do żądania interfejs API REST usługi:

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"  
      }  
    },  
    ...
} 

Następujące uprawnienie jest wymagane do wywołania żądania interfejs API REST usługi. Aby uzyskać więcej informacji, zobacz Udzielanie uprawnień w celu uzyskania tokenów dostępu.

Typ uprawnienia Uprawnienie
Aplikacja bbb94529-53a3-4be5-a069-7eaf2712b826/.default

Ładunek żądania prezentacji

Ładunek żądania prezentacji zawiera informacje o żądaniu prezentacji weryfikowalnych poświadczeń. W poniższym przykładzie pokazano żądanie prezentacji od określonego wystawcy. Wynik tego żądania zwraca kod QR z linkiem do rozpoczęcia procesu prezentacji.

{
  "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..."
        ]
      }
    ]
  }
}

Ładunek zawiera następujące właściwości.

Parametr Typ Opis
includeQRCode Wartość logiczna Określa, czy kod QR jest uwzględniony w odpowiedzi na to żądanie. Prezentuj kod QR i poproś użytkownika o jego zeskanowanie. Skanowanie kodu QR uruchamia aplikację authenticator z tym żądaniem prezentacji. Możliwe wartości to true (wartość domyślna) lub false . Po ustawisz wartość false na , użyj właściwości url return, aby renderować link głęboki.
authority ciąg Zdecentralizowany identyfikator dzierżawy usługi Azure AD weryfikatora . Aby uzyskać więcej informacji, zobacz Zbieranie szczegółów dzierżawy w celu skonfigurowania przykładowej aplikacji.
registration RequestRegistration Zawiera informacje o weryfikatorze.
presentation RequestPresentation Zawiera informacje o żądaniu prezentacji poświadczeń weryfikowalnych.
callback Wywołania zwrotnego Umożliwia deweloperowi aktualizowanie interfejsu użytkownika podczas procesu prezentacji weryfikowalnych poświadczeń. Gdy użytkownik ukończy proces, kontynuuj proces po zwróceniu wyników do aplikacji.

RequestRegistration, typ

Typ RequestRegistration zapewnia rejestrację informacji dla wystawcy. Typ RequestRegistration zawiera następujące właściwości:

Właściwość Typ Opis
clientName ciąg Nazwa wyświetlana wystawcy weryfikowalnych poświadczeń. Ta nazwa zostanie przedstawiona użytkownikowi w aplikacji authenticator.

Poniższy zrzut ekranu przedstawia clientName właściwość i nazwę wyświetlaną authority (weryfikatora) w żądaniu prezentacji.

Zrzut ekranu przedstawiający sposób zatwierdzania żądania prezentacji.

Typ requestPresentation

Typ RequestPresentation zawiera informacje wymagane do weryfikowania prezentacji poświadczeń. RequestPresentation Zawiera następujące właściwości:

Właściwość Typ Opis
includeReceipt Wartość logiczna Określa, czy potwierdzenie powinno zostać uwzględnione w odpowiedzi na to żądanie. Możliwe wartości to true lub false (wartość domyślna). Potwierdzenie zawiera oryginalny ładunek wysłany od wystawcy uwierzytelnienia do usługi Poświadczenia weryfikowalne. Paragon jest przydatny do rozwiązywania problemów i nie powinien być ustawiany domyślnie. W OpenId Connect SIOP żądaniu paragon zawiera token identyfikatora z oryginalnego żądania.
requestedCredentials — kolekcja Kolekcja obiektów RequestCredential.

Typ RequestCredential

Zawiera RequestCredential informacje o żądanych poświadczeniach, które użytkownik musi podać. RequestCredential Zawiera następujące właściwości:

Właściwość Typ Opis
type ciąg Weryfikowalny typ poświadczeń. Musi type być zgodne z typem zdefiniowanym w issuer manifeście weryfikowalnych poświadczeń (na przykład VerifiedCredentialExpert ). Aby uzyskać manifest wystawcy, zobacz Zbieranie poświadczeń i szczegółów środowiska w celu skonfigurowania przykładowej aplikacji. Skopiuj adres URL poświadczenia problemu, otwórz go w przeglądarce internetowej i sprawdź właściwość id.
purpose ciąg Podaj informacje o celu żądania tego weryfikowalnych poświadczeń.
acceptedIssuers kolekcja ciągów Kolekcja identyfikatorów DID wystawców, które mogą wystawiać typ weryfikowalnych poświadczeń, które podmioty mogą przedstawić. Aby uzyskać identyfikator DID wystawcy, zobacz Zbieranie poświadczeń i szczegółów środowiska, aby skonfigurować przykładową aplikację,i skopiuj wartość identyfikatora zdecentralizowanego (DID).

Typ wywołania zwrotnego

Żądanie interfejs API REST usługi generuje kilka zdarzeń do punktu końcowego wywołania zwrotnego. Te zdarzenia umożliwiają zaktualizowanie interfejsu użytkownika i kontynuowanie procesu po zwróceniu wyników do aplikacji. Typ Callback zawiera następujące właściwości:

Właściwość Typ Opis
url ciąg URI do punktu końcowego wywołania zwrotnego aplikacji.
state ciąg Kojarzy ze stanem przekazanym w oryginalnym ładunku.
headers ciąg Opcjonalny. Możesz dołączyć kolekcję nagłówków HTTP wymaganych przez koniec odbierania komunikatu POST. Nagłówki powinny zawierać tylko nagłówek api-key lub wymagany do autoryzacji.

Pomyślna odpowiedź

W przypadku powodzenia ta metoda zwraca kod odpowiedzi (HTTP 201 Created) oraz kolekcję obiektów zdarzeń w treści odpowiedzi. Następujący kod JSON przedstawia pomyślną odpowiedź:

{  
    "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>"
} 

Odpowiedź zawiera następujące właściwości:

Właściwość Typ Opis
requestId ciąg Automatycznie wygenerowany identyfikator korelacji. Wywołanie zwrotne używa tego samego żądania, co umożliwia śledzenie żądania prezentacji i jego wywołań zwrotnych.
url ciąg Adres URL, który uruchamia aplikację wystawcy uwierzytelnień i rozpoczyna proces prezentacji. Możesz przedstawić ten adres URL użytkownikowi, jeśli nie może zeskanować kodu QR.
expiry liczba całkowita Wskazuje, kiedy odpowiedź wygaśnie.
qrCode ciąg Kod QR, który użytkownik może zeskanować w celu uruchomienia przepływu prezentacji.

Gdy aplikacja otrzyma odpowiedź, musi przedstawić użytkownikowi kod QR. Użytkownik skanuje kod QR, co powoduje otwarcie aplikacji authenticator i rozpoczęcie procesu prezentacji.

Odpowiedź o błędzie

Można również zwrócić odpowiedzi na błędy, aby aplikacja może je odpowiednio obsłużyć. Następujący kod JSON przedstawia komunikat o błędzie z nieautoryzowanym dostępem:

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

Odpowiedź zawiera następujące właściwości:

Właściwość Typ Opis
requestId ciąg Automatycznie wygenerowany identyfikator żądania.
date data Czas błędu.
error.code ciąg Kod błędu powrotu.
error.message ciąg Komunikat o błędzie.

Zdarzenia wywołania zwrotnego

Punkt końcowy wywołania zwrotnego jest wywoływany, gdy użytkownik skanuje kod QR, korzysta z linku głębokiego aplikacji authenticator lub kończy proces prezentacji.

Właściwość Typ Opis
requestId ciąg Mapowany na oryginalne żądanie, gdy ładunek został opublikowany w usłudze Poświadczeń weryfikowalnych.
code ciąg Kod został zwrócony, gdy żądanie zostało pobrane przez aplikację authenticator. Możliwe wartości:
  • request_retrieved: użytkownik zeskanował kod QR lub wybrał link, który uruchamia przepływ prezentacji.
  • presentation_verified: weryfikacja weryfikowalnych poświadczeń została ukończona pomyślnie.
state ciąg Zwraca wartość stanu przekazaną w oryginalnym ładunku.
subject ciąg Weryfikowalny użytkownik poświadczeń ZOSTAŁ.
issuers array Zwraca tablicę żądanych poświadczeń weryfikowalnych. Każde weryfikowalne poświadczenie zapewnia:
  • Weryfikowalny typ poświadczeń.
  • Pobrane oświadczenia.
  • Domena weryfikowanego wystawcy poświadczeń.
  • Stan weryfikacji domeny wystawcy poświadczeń weryfikowalnych.
  • receipt ciąg Opcjonalny. Potwierdzenie zawiera oryginalny ładunek wysłany od wystawcy uwierzytelnienia do weryfikowalnych poświadczeń.

    W poniższym przykładzie pokazano ładunek wywołania zwrotnego, gdy aplikacja authenticator uruchamia żądanie prezentacji:

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

    W poniższym przykładzie pokazano ładunek wywołania zwrotnego po pomyślnym zakończeniu weryfikowania prezentacji poświadczeń:

    {
      "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>"
      }
    } 
    

    Następne kroki

    Dowiedz się, jak wywołać żądanie interfejs API REST usługi.