Specyfikacja wystawiania interfejsu API REST usługi Request Service

Artykuł
10/24/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 wystawiania. W innym artykule opisano sposób wywoływania interfejsu API REST usługi żądań.

Żądanie systemu HTTP

Żądanie wystawiania 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 wystawiania interfejsu API REST usługi Żądań wymaga następujących nagłówków HTTP:

Nazwa/nazwisko	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ń.

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

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

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest
Content-Type: application/json
Authorization: Bearer <token>

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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 wystawiania

Ładunek żądania wystawiania zawiera informacje o weryfikowalnym żądaniu wystawiania poświadczeń. W poniższym przykładzie pokazano żądanie wystawiania przy użyciu przepływu kodu PIN z oświadczeniami użytkownika, takimi jak imię i nazwisko. Wynik tego żądania zwraca kod QR z linkiem, aby rozpocząć proces wystawiania.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

Ł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 wystawiania. Możliwe wartości to `true` lub `false` (wartość domyślna). Po ustawieniu wartości na `false`wartość użyj właściwości return `url` , aby renderować link bezpośredni.
`callback`	Wywołania zwrotnego	Obowiązkowy. Umożliwia deweloperowi asynchroniczne uzyskiwanie informacji o przepływie podczas weryfikowalnego procesu wystawiania poświadczeń. Na przykład deweloper może chcieć wywołać, gdy użytkownik przeskanował kod QR lub jeśli żądanie wystawiania zakończy się powodzeniem lub niepowodzeniem.
`authority`	string	Identyfikator zdecentralizowany wystawcy (DID). Aby uzyskać więcej informacji, zobacz Zbieranie poświadczeń i szczegółów środowiska w celu skonfigurowania przykładowej aplikacji.
`registration`	RequestRegistration	Zawiera informacje o wystawcy, który może być wyświetlany w aplikacji wystawcy uwierzytelniania.
`type`	string	Weryfikowalny typ poświadczeń. Powinien być zgodny z typem zdefiniowanym w manifeście poświadczeń weryfikowalnych. Na przykład: `VerifiedCredentialExpert`. Aby uzyskać więcej informacji, zobacz Tworzenie zweryfikowanego eksperta poświadczeń na platformie Azure.
`manifest`	string	Adres URL dokumentu manifestu poświadczeń weryfikowalnych. Aby uzyskać więcej informacji, zobacz Zbieranie poświadczeń i szczegółów środowiska w celu skonfigurowania przykładowej aplikacji.
`claims`	string	Opcjonalny. Można użyć tylko dla przepływu zaświadczania o tokenie identyfikatora, aby uwzględnić kolekcję asercji dotyczących tematu w poświadczeniach weryfikowalnych.
`pin`	SZPILKA	Opcjonalny. Kod PIN może być używany tylko z przepływem zaświadczania o tokenie identyfikatora. Numer PIN zapewniający dodatkowe zabezpieczenia podczas wystawiania. Wygenerujesz kod PIN i przedstawisz go użytkownikowi w aplikacji. Użytkownik musi podać wygenerowany kod PIN.
`expirationDate`	string	Opcjonalny. Data wygaśnięcia może być używana tylko z przepływem zaświadczania o tokenie identyfikatora. Jeśli zostanie określona, wartość musi być datą wyrażoną w formacie ISO8601 . Data zastąpi ważnośćInterval w definicji reguł poświadczeń dla tego żądania wystawiania. Użyj tego ustawienia, aby jawnie kontrolować, kiedy poświadczenie wygaśnie, na przykład koniec dnia, koniec miesiąca lub koniec roku, niezależnie od tego, kiedy zostanie wystawiony. Należy pamiętać, że data jest wyrażona w formacie UTC. Jeśli określisz koniec roku, z ustawionym czasem na `23:59:59`, czyli od 1 sekundy do północy w czasie UTC. Każdy użytkownik w innej strefie czasowej otrzyma datę wygaśnięcia przedstawioną w lokalnej strefie czasowej w aplikacji Microsoft Authenticator. Oznacza to, że jeśli jesteś w strefie czasowej CET, zostanie on przedstawiony jako 1 stycznia 1 rano. Kontrakt poświadczeń musi mieć flagę allowOverrideValidityOnIssuance ustawioną na true.

Obecnie istnieją cztery typy zaświadczania oświadczeń, które można wysłać w ładunku. Zweryfikowany identyfikator Microsoft Entra używa czterech sposobów wstawiania oświadczeń do weryfikowalnego poświadczenia i potwierdzania tych informacji z did wystawcy. Poniżej przedstawiono cztery typy:

Token identyfikatora
Wskazówka tokenu identyfikatora
Weryfikowalne poświadczenia za pośrednictwem weryfikowalnej prezentacji
Oświadczenia z certyfikatami własnymi

Szczegółowe informacje na temat typów danych wejściowych można znaleźć w temacie Dostosowywanie poświadczeń weryfikowalnych.

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 wystawcy poświadczenia weryfikowalnego.
`logoUrl`	string	Opcjonalny. Adres URL logo wystawcy.
`termsOfServiceUrl`	string	Opcjonalny. Adres URL warunków użytkowania weryfikowalnego poświadczenia wystawianego przez Ciebie.

Uwaga

W tej chwili RequestRegistration informacje nie są prezentowane podczas wystawiania w aplikacji Microsoft Authenticator. Te informacje mogą być jednak używane w ładunku.

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 zwróci nieczytelny adres URL wywołania zwrotnego. Zaakceptowane formaty IPv4, IPv6 lub DNS rozpoznawalne nazwy hosta. Aby wzmocnić bezpieczeństwo sieci, zobacz Często zadawane pytania.
`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 pinezki

Typ pin definiuje kod PIN, który może być wyświetlany w ramach wystawiania. pin jest opcjonalny i, jeśli jest używany, zawsze powinien być wysyłany poza pasmem. W przypadku używania kodu PIN skrótu skrótu saltnależy zdefiniować właściwości , algi iterations . pin zawiera następujące właściwości:

Właściwość	Type	opis
`value`	string	Zawiera wartość numeru PIN w postaci zwykłego tekstu. Jeśli używasz skrótu kodu PIN, właściwość value zawiera skrót, zakodowany w formacie base64.
`type`	string	Typ kodu PIN. Możliwa wartość: `numeric` (wartość domyślna).
`length`	integer	Długość kodu PIN. Domyślna długość to 6, wartość minimalna to 4, a maksymalna to 16.
`salt`	string	Sól skrótowego kodu PIN. Sól jest poprzedzana podczas obliczeń skrótu. Kodowanie: UTF-8.
`alg`	string	Algorytm tworzenia skrótów dla skrótu numeru PIN. Obsługiwany algorytm: `sha256`.
`iterations`	integer	Liczba iteracji skrótów. Możliwa wartość: `1`.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 pozwala śledzić żądanie wystawiania i jego wywołania zwrotne.
`url`	string	Adres URL, który uruchamia aplikację authenticator i uruchamia proces wystawiania. 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 wystawiania.

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

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 wystawcy lub kończy proces wystawiania.

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 dla żądania. Możliwe wartości: `request_retrieved`: użytkownik zeskanował kod QR lub wybrał link, który uruchamia przepływ wystawiania. `issuance_successful`: Wystawianie zweryfikowanych poświadczeń zakończyło się pomyślnie. `issuance_error`: Wystąpił błąd podczas wystawiania. Aby uzyskać szczegółowe informacje, zobacz `error` właściwość .
`state`	string	Zwraca wartość stanu przekazaną w oryginalnym ładunku.
`error`	error	`code` Gdy wartość właściwości to `issuance_error`, ta właściwość zawiera informacje o błędzie.
`error.code`	string	Kod błędu zwracanego.
`error.message`	string	Komunikat o błędzie.

W poniższym przykładzie pokazano ładunek wywołania zwrotnego, gdy aplikacja wystawcy uwierzytelniania uruchamia żądanie wystawiania:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

W poniższym przykładzie pokazano ładunek wywołania zwrotnego po pomyślnym ukończeniu procesu wystawiania przez użytkownika:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Błędy wywołania zwrotnego

Punkt końcowy wywołania zwrotnego może być wywoływany z komunikatem o błędzie. W poniższej tabeli wymieniono kody błędów:

Komunikat	Definicja
`fetch_contract_error`	Nie można pobrać weryfikowalnego kontraktu poświadczeń. Ten błąd zwykle występuje, gdy interfejs API nie może pobrać manifestu określonego w obiekcie RequestIssuance ładunku żądania.
`issuance_service_error`	Usługa Weryfikowalne poświadczenia nie jest w stanie zweryfikować wymagań lub wystąpił problem w weryfikowaniu poświadczeń.
`unspecified_error`	Ten błąd jest nietypowy, ale warto go zbadać.

W poniższym przykładzie pokazano ładunek wywołania zwrotnego po wystąpieniu błędu:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
}

Następne kroki

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

Udostępnij za pośrednictwem