Specyfikacja prezentacji interfejsu API REST usługi Request Service

Artykuł
02/06/2024

Zweryfikowany identyfikator Microsoft Entra zawiera interfejs API REST usługi żądań. Ten interfejs API umożliwia wystawianie i weryfikowanie poświadczeń. W tym artykule określono interfejs API REST usługi żądań dla żądania prezentacji. Żądanie prezentacji prosi użytkownika o przedstawienie zweryfikowanych poświadczeń, a następnie zweryfikowanie poświadczeń. W innym artykule opisano sposób wywoływania interfejsu API REST usługi żądań.

Żądanie systemu HTTP

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

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

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

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

Skonstruuj żądanie HTTP POST do interfejsu API REST usługi żądań. Element tenantId nie jest już potrzebny w adresie URL, ponieważ jest obecny jako oświadczenie w pliku access_token.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

Następujące żądanie HTTP demonstruje żądanie prezentacji do interfejsu API REST usługi żądań:

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

Do wywołania interfejsu API REST usługi żądań wymagane jest następujące uprawnienie. Aby uzyskać więcej informacji, zobacz Udzielanie uprawnień do uzyskiwania tokenów dostępu.

Typ uprawnienia	Uprawnienie
Aplikacja	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Ładunek żądania prezentacji

Ładunek żądania prezentacji zawiera informacje o weryfikowalnym żądaniu prezentacji poświadczeń. W poniższym przykładzie pokazano żądanie prezentacji od określonego wystawcy. Wynik tego żądania zwraca kod QR z linkiem, aby rozpocząć proces prezentacji.

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

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

Parametr	Type	Opis
`includeQRCode`	Logiczny	Opcjonalny. Określa, czy kod QR jest uwzględniony w odpowiedzi tego żądania. Przedstawi kod QR i poproś użytkownika o jego zeskanowanie. Skanowanie kodu QR powoduje uruchomienie aplikacji authenticator przy użyciu tego żądania prezentacji. Możliwe wartości to `true` (wartość domyślna) lub `false`. Po ustawieniu wartości na `false`wartość użyj właściwości return `url` , aby renderować link bezpośredni.
`includeReceipt`	Wartość logiczna	Opcjonalny. 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 wysyłany z wystawcy uwierzytelniającego do usługi Weryfikowalne poświadczenia. Potwierdzenie przydaje się do rozwiązywania problemów lub jeśli musisz uzyskać pełne szczegóły ładunku. W przeciwnym razie nie trzeba ustawiać tej wartości na `true` wartość domyślną. W żądaniu `OpenId Connect SIOP` potwierdzenie zawiera token identyfikatora z oryginalnego żądania.
`authority`	string	Identyfikator zdecentralizowany (DID) weryfikatora firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz Zbieranie szczegółów dzierżawy w celu skonfigurowania przykładowej aplikacji.
`registration`	RequestRegistration	Zawiera informacje o weryfikatorze.
`callback`	Wywołania zwrotnego	Obowiązkowy. Umożliwia deweloperowi aktualizowanie interfejsu użytkownika podczas weryfikowania procesu prezentacji poświadczeń. Gdy użytkownik ukończy proces, kontynuuj proces po powrocie wyników do aplikacji.
`requestedCredentials`	— kolekcja	Kolekcja obiektów RequestCredential .

Typ żądaniaRegistration

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

Właściwość	Type	opis
`clientName`	string	Nazwa wyświetlana weryfikatora poświadczenia weryfikowalnego. Ta nazwa zostanie wyświetlona użytkownikowi w aplikacji authenticator.
`purpose`	string	Opcjonalny. Zostanie wyświetlony ciąg informujący użytkownika o tym, dlaczego żądane są weryfikowalne poświadczenia.
`logoUrl`	URL	Opcjonalny. Adres URL logora weryfikatora. Nie jest to używane przez aplikację Authenticator.
`termsOfServiceUrl`	URL	Opcjonalny. Adres URL warunków świadczenia usługi dla weryfikatora. Nie jest to używane przez aplikację Authenticator.

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

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

Typ wywołania zwrotnego

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

Właściwość	Type	opis
`url`	string	Identyfikator URI do punktu końcowego wywołania zwrotnego aplikacji. Identyfikator URI musi wskazywać osiągalny punkt końcowy w Internecie. W przeciwnym razie usługa zgłosi nieczytelny adres URL wywołania zwrotnego. Zaakceptowane dane wejściowe IPv4, IPv6 lub DNS rozpoznawalne nazwy hosta.
`state`	string	Koreluje zdarzenie wywołania zwrotnego ze stanem przekazanym w oryginalnym ładunku.
`headers`	string	Opcjonalny. Możesz dołączyć kolekcję nagłówków HTTP wymaganych przez koniec odbierania komunikatu POST. Bieżące obsługiwane wartości nagłówków `api-key` to nagłówki lub `Authorization` . Każdy inny nagłówek zgłosi nieprawidłowy błąd nagłówka wywołania zwrotnego.

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ść	Type	opis
`type`	string	Weryfikowalny typ poświadczeń. Element `type` musi być zgodny z typem zdefiniowanym `issuer` w manifeście poświadczeń weryfikowalnych (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świadczeń problemu, otwórz go w przeglądarce internetowej i sprawdź właściwość id.
`purpose`	string	Opcjonalny. Podaj informacje o celu żądania tego weryfikowalnego poświadczenia. Nie jest to używane przez aplikację Authenticator.
`acceptedIssuers`	kolekcja ciągów	Opcjonalny. Kolekcja identyfikatorów DID wystawców, które mogą wystawiać typ weryfikowalnych poświadczeń, które podmioty mogą przedstawić. Aby uzyskać wystawcę DID, zobacz Zbieranie poświadczeń i szczegółów środowiska w celu skonfigurowania przykładowej aplikacji i skopiowanie wartości zdecentralizowanego identyfikatora (DID). `acceptedIssuers` Jeśli kolekcja jest pusta lub nie istnieje, żądanie prezentacji zaakceptuje typ poświadczeń wystawiony przez dowolnego wystawcę.
`configuration.validation`	Configuration.Validation	Opcjonalne ustawienia weryfikacji prezentacji.
`constraints`	Ograniczenia	Opcjonalny. Kolekcja ograniczeń oświadczeń.

Configuration.Validation, typ

Zawiera Configuration.Validation informacje o sposobie weryfikacji prezentowanych poświadczeń. Zawiera on następujące właściwości:

Właściwość	Type	Opis
`allowRevoked`	Logiczny	Opcjonalny. Określa, czy należy zaakceptować odwołane poświadczenia. Wartość domyślna to `false` (nie powinna być akceptowana).
`validateLinkedDomain`	Wartość logiczna	Opcjonalny. Określa, czy domena połączona ma zostać zweryfikowana. Wartość domyślna to `false`. Ustawienie tej flagi `false` oznacza, że jako aplikacja jednostki uzależnionej akceptuje poświadczenia z niezweryfikowanej połączonej domeny. Ustawienie tej flagi oznacza `true` , że połączona domena zostanie zweryfikowana i zostaną zaakceptowane tylko zweryfikowane domeny.
`faceCheck`	faceCheck	Opcjonalny. Umożliwia żądanie sprawdzenia aktualności podczas prezentacji.

Typ ograniczeń

Typ constraints zawiera kolekcję ograniczeń oświadczeń, które muszą zostać spełnione, gdy portfel wybiera poświadczenia kandydata. Umożliwia to żądanie poświadczeń z określoną wartością oświadczenia. Określone ograniczenia będą używać logiki AND, tj. jeśli określisz trzy ograniczenia, wszystkie z nich muszą zostać spełnione. Dla każdego ograniczenia w kolekcji należy wybrać jeden operand wartości, zawiera lub startsWith. Wartości nie mogą być wyrażeniami regularnymi. Wszystkie porównania są bez uwzględniania wielkości liter.

Właściwość	Type	opis
`claimName`	string	Obowiązkowy. Nazwa oświadczenia dla ograniczenia. Jest to nazwa oświadczenia w weryfikowalnym poświadczeniu. Zobacz outputClaim in claimMapping type (Dane wyjścioweUzyzywzywanie w typie claimMapping).
`values`	kolekcja ciągów	Zestaw wartości, które powinny być zgodne z wartością oświadczenia. Jeśli określisz wiele wartości, takich jak ["red", "green", "blue"] jest to dopasowanie, jeśli wartość oświadczenia w poświadczeniu zawiera dowolną z wartości w kolekcji.
`contains`	string	Ograniczenie daje wartość true, jeśli wartość oświadczenia zawiera określoną wartość.
`startsWith`	string	Ograniczenie daje wartość true, jeśli wartość oświadczenia zaczyna się od określonej wartości.

faceCheck, typ

Typ faceCheck zawiera informacje dotyczące przeprowadzania sprawdzania aktualności podczas prezentacji poświadczeń. Żądane poświadczenie musi zawierać zdjęcie właściciela w oświadczeniu o nazwie sourcePhotoClaimName. Prezentacja powiedzie się, jeśli sprawdzanie dostępności osiągnie poziom ufności równy lub większy niż określony w właściwości matchConfidenceThreshold. Jeśli próg nie zostanie osiągnięty, cała prezentacja zakończy się niepowodzeniem.

Właściwość	Type	opis
`sourcePhotoClaimName`	string	Obowiązkowy. Nazwa oświadczenia w poświadczeniu zawierającym zdjęcie. Zobacz outputClaim in claimMapping type (Dane wyjścioweUzyzywzywanie w typie claimMapping).
`matchConfidenceThreshold`	integer	Opcjonalny. Próg poufny dla pomyślnego sprawdzenia między zdjęciem a danymi na żywo. Musi być liczbą całkowitą z zakresu od 50 do 100. Wartość domyślna to 70.

Odpowiedź pomyślna

Jeśli ta metoda powiedzie się, zwraca kod odpowiedzi (UTWORZONY PRZEZ HTTP 201) i kolekcję obiektów zdarzeń w treści odpowiedzi. Poniższy kod JSON demonstruje pomyślną odpowiedź:

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

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

Właściwość	Type	opis
`requestId`	string	Automatycznie wygenerowany identyfikator żądania. Wywołanie zwrotne używa tego samego żądania, co umożliwia śledzenie żądania prezentacji i jego wywołań zwrotnych.
`url`	string	Adres URL, który uruchamia aplikację authenticator i uruchamia proces prezentacji. Ten adres URL można przedstawić użytkownikowi, jeśli nie może zeskanować kodu QR.
`expiry`	integer	Wskazuje, kiedy odpowiedź wygaśnie.
`qrCode`	string	Kod QR, który użytkownik może skanować w celu uruchomienia przepływu prezentacji.

Gdy aplikacja otrzyma odpowiedź, aplikacja musi przedstawić użytkownikowi kod QR. Użytkownik skanuje kod QR, który otwiera aplikację authenticator i uruchamia proces prezentacji.

Odpowiedź błędna

Jeśli wystąpi błąd żądania, zostanie zwrócona odpowiedź o błędzie i powinna zostać odpowiednio obsłużona przez aplikację.

Zdarzenia wywołania zwrotnego

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

Właściwość	Type	opis
`requestId`	string	Zamapowane na oryginalne żądanie, gdy ładunek został opublikowany w usłudze Weryfikowalne poświadczenia.
`requestStatus`	string	Stan zwrócony po pobraniu żądania 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 poświadczeń weryfikowalnych zakończyła się pomyślnie. li>`presentation_error`: Wystąpił błąd w prezentacji.
`state`	string	Zwraca wartość stanu przekazaną w oryginalnym ładunku.
`subject`	string	Weryfikowalny użytkownik poświadczeń NIE.
`verifiedCredentialsData`	tablica	Zwraca tablicę żądanych poświadczeń weryfikowalnych. Dla każdego weryfikowalnego poświadczenia zapewnia: Weryfikowalne typy poświadczeń. Did wystawcy Pobrane oświadczenia. Weryfikowalna domena wystawcy poświadczeń. Weryfikowalny stan weryfikacji domeny wystawcy poświadczeń.
`receipt`	string	Opcjonalny. Potwierdzenie zawiera oryginalny ładunek wysyłany z portfela do usługi Weryfikowalne poświadczenia. Potwierdzenie powinno być używane tylko do rozwiązywania problemów/debugowania. Format paragonu nie jest poprawiony i może ulec zmianie na podstawie używanego portfela i wersji.

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

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

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

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

Następne kroki

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