Kravspecifikation för rest-API för begärandetjänst

Artikel
12/07/2023

Microsoft Entra – verifierat ID innehåller REST-API:et för begärandetjänsten. Med det här API:et kan du utfärda och verifiera en autentiseringsuppgift. Den här artikeln anger REST-API:et för begärandetjänsten för en utfärdandebegäran. En annan artikel beskriver hur du anropar REST-API:et för begärandetjänsten.

HTTP-begäran

Begäran om rest-API för begärandetjänsten stöder följande HTTP-metod:

Metod	Kommentar
POST	Med JSON-nyttolast enligt beskrivningen i den här artikeln.

Begäran om rest-API för begärandetjänsten kräver följande HTTP-huvuden:

Name	Värde
`Authorization`	Bifoga åtkomsttoken som en ägartoken i auktoriseringshuvudet i en HTTP-begäran. Exempel: `Authorization: Bearer <token>`
`Content-Type`	`application/json`

Skapa en HTTP POST-begäran till REST-API:et för begärandetjänsten.

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

Följande HTTP-begäran visar en begäran till REST-API:et för begärandetjänsten:

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

{
    "includeQRCode": true,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

Följande behörighet krävs för att anropa REST-API:et för begärandetjänsten. Mer information finns i Bevilja behörigheter för att hämta åtkomsttoken.

Behörighetstyp	Behörighet
Program	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Nyttolast för utfärdandebegäran

Nyttolasten för utfärdandebegäran innehåller information om din verifierbara begäran om utfärdande av autentiseringsuppgifter. I följande exempel visas en utfärdandebegäran med hjälp av ett PIN-kodflöde med användaranspråk, till exempel förnamn och efternamn. Resultatet av den här begäran returnerar en QR-kod med en länk för att starta utfärdandeprocessen.

{
  "includeQRCode": false,
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "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"
}

Nyttolast innehåller följande egenskaper: .

Parameter	Typ	Beskrivning
`includeQRCode`	Booleskt	Avgör om en QR-kod ingår i svaret på den här begäran. Presentera QR-koden och be användaren att skanna den. Genom att skanna QR-koden startas autentiseringsappen med den här utfärdandebegäran. Möjliga värden är `true` (standard) eller `false`. När du anger värdet till `false`använder du returegenskapen `url` för att återge en djuplänk.
`callback`	Motringning	Obligatorisk. Gör att utvecklaren asynkront kan hämta information om flödet under den verifierbara utfärdandeprocessen för autentiseringsuppgifter. Utvecklaren kanske till exempel vill ha ett anrop när användaren har skannat QR-koden eller om utfärdandebegäran lyckas eller misslyckas.
`authority`	sträng	Utfärdarens decentraliserade identifierare (DID). Mer information finns i Samla in autentiseringsuppgifter och miljöinformation för att konfigurera exempelprogrammet.
`registration`	Begäranderegistrering	Innehåller information om utfärdaren som kan visas i autentiseringsappen.
`type`	sträng	Den verifierbara typen av autentiseringsuppgifter. Ska matcha den typ som definierats i det verifierbara manifestet för autentiseringsuppgifter. Exempel: `VerifiedCredentialExpert`. Mer information finns i Skapa expertkortet för verifierade autentiseringsuppgifter i Azure.
`manifest`	sträng	URL:en för det verifierbara manifestdokumentet för autentiseringsuppgifter. Mer information finns i Samla in autentiseringsuppgifter och miljöinformation för att konfigurera exempelprogrammet.
`claims`	sträng	Valfritt. Kan endast användas för ID-tokentipsattesteringsflödet för att inkludera en samling intyg som gjorts om ämnet i den verifierbara autentiseringsuppgiften.
`pin`	PIN	Valfritt. PIN-kod kan endast användas med ID-tokentipsattesteringsflödet . Ett PIN-nummer som ger extra säkerhet under utfärdandet. Du genererar en PIN-kod och presenterar den för användaren i din app. Användaren måste ange den PIN-kod som du genererade.
`expirationDate`	sträng	Valfritt. ExpirationDate kan endast användas med ID-tokentipsattesteringsflödet . Om det anges måste värdet vara ett datum som uttrycks i ISO8601 format. Datumet åsidosätter validityInterval i definitionen av autentiseringsuppgifter för den här utfärdandebegäran. Använd den här inställningen om du uttryckligen vill styra när en autentiseringsuppgift upphör att gälla, till exempel slutet av dagen, slutet av månaden eller slutet av året, oavsett när den utfärdas. Observera att datumet uttrycks i UTC-format. Om du anger årets slut, med tiden inställd på `23:59:59`, är det 1 sekund till midnatt i UTC-tid. Alla användare i en annan tidszon får förfallodatumet som visas i den lokala tidszonen i Microsoft Authenticator. Det innebär att om du befinner dig i CET-tidszonen visas den som 1 januari 01.00. Autentiseringskontraktet måste ha flaggan allowOverrideValidityOnIssuance inställd på true.

Det finns för närvarande fyra anspråksattesteringstyper som du kan skicka in nyttolasten. Microsoft Entra – verifierat ID använder fyra sätt att infoga anspråk i en verifierbar autentiseringsuppgift och intyga informationen med utfärdarens DID. Följande är de fyra typerna:

ID-token
ID-tokentips
Verifierbara autentiseringsuppgifter via en verifierbar presentation
Självbetjäningsanspråk

Du hittar detaljerad information om indatatyperna i Anpassa dina verifierbara autentiseringsuppgifter.

Typ av begäranderegistrering

Typen RequestRegistration innehåller informationsregistrering för utfärdaren. Typen RequestRegistration innehåller följande egenskaper:

Property	Type	Description
`clientName`	sträng	Ett visningsnamn för utfärdaren av de verifierbara autentiseringsuppgifterna.
`logoUrl`	sträng	Valfritt. URL:en för utfärdarlogotypen.
`termsOfServiceUrl`	sträng	Valfritt. URL:en för användningsvillkoren för de verifierbara autentiseringsuppgifter som du utfärdar.

Kommentar

För närvarande RequestRegistration visas inte informationen under utfärdandet i Microsoft Authenticator-appen. Den här informationen kan dock användas i nyttolasten.

Motringningstyp

Rest-API:et för begärandetjänsten genererar flera händelser till motringningsslutpunkten. Med dessa händelser kan du uppdatera användargränssnittet och fortsätta processen när resultatet har returnerats till programmet. Typen Callback innehåller följande egenskaper:

Property	Type	Description
`url`	sträng	URI till programmets slutpunkt för motringning. URI:n måste peka på en nåbar slutpunkt på Internet, annars utlöser tjänsten motringnings-URL:en ett oläsbart fel. Accepterade format IPv4, IPv6 eller DNS-matchningsbart värdnamn
`state`	sträng	Korrelerar motringningshändelsen med tillståndet som skickades i den ursprungliga nyttolasten.
`headers`	sträng	Valfritt. Du kan inkludera en samling HTTP-huvuden som krävs i slutet av POST-meddelandet. De aktuella sidhuvudvärdena som stöds är `api-key` rubrikerna `Authorization` eller . Alla andra huvuden utlöser ett ogiltigt motringningshuvudfel

Pin-typ

Typen pin definierar en PIN-kod som kan visas som en del av utfärdandet. pin är valfritt och, om det används, bör alltid skickas out-of-band. När du använder en HASH-PIN-kod måste du definiera saltegenskaperna , algoch iterations . pin innehåller följande egenskaper:

Property	Type	Description
`value`	sträng	Innehåller PIN-kodens värde i oformaterad text. När du använder en hashad PIN-kod innehåller värdeegenskapen den saltade hashen, base64-kodad.
`type`	sträng	Typ av PIN-kod. Möjligt värde: `numeric` (standard).
`length`	integer	Längden på PIN-koden. Standardlängden är 6, minimivärdet är 4 och maxvärdet är 16.
`salt`	sträng	Saltet i den hashade PIN-koden. Saltet förbereds under hashberäkningen. Kodning: UTF-8.
`alg`	sträng	Hashalgoritmen för den hashade PIN-koden. Algoritm som stöds: `sha256`.
`iterations`	integer	Antalet hash-iterationer. Möjligt värde: `1`.

Lyckat svar

Om det lyckas returnerar den här metoden en svarskod (HTTP 201 Skapad) och en samling händelseobjekt i svarstexten. Följande JSON visar ett lyckat svar:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
}

Svaret innehåller följande egenskaper:

Property	Type	Description
`requestId`	sträng	Ett automatiskt genererat begärande-ID. Återanropet använder samma begäran så att du kan hålla reda på utfärdandebegäran och dess återanrop.
`url`	sträng	En URL som startar autentiseringsappen och startar utfärdandeprocessen. Du kan visa den här URL:en för användaren om de inte kan skanna QR-koden.
`expiry`	integer	Anger när svaret upphör att gälla.
`qrCode`	sträng	En QR-kod som användaren kan skanna för att starta utfärdandeflödet.

När din app får svaret måste appen presentera QR-koden för användaren. Användaren söker igenom QR-koden, som öppnar autentiseringsappen och startar utfärdandeprocessen.

Felsvar

Om det uppstår ett fel med begäran returneras ett felsvar och bör hanteras på lämpligt sätt av appen.

Återanropshändelser

Motringningsslutpunkten anropas när en användare söker igenom QR-koden, använder djuplänken i autentiseringsappen eller slutför utfärdandeprocessen.

Property	Type	Description
`requestId`	sträng	Mappad till den ursprungliga begäran när nyttolasten bokfördes till verifierbara autentiseringsuppgifter.
`requestStatus`	sträng	Statusen som returnerades för begäran. Möjliga värden: `request_retrieved`: Användaren skannade QR-koden eller valde länken som startar utfärdandeflödet. `issuance_successful`: Utfärdandet av de verifierbara autentiseringsuppgifterna lyckades. `issuance_error`: Det uppstod ett fel under utfärdandet. Mer information finns i egenskapen `error` .
`state`	sträng	Returnerar det tillståndsvärde som du skickade i den ursprungliga nyttolasten.
`error`	fel	När egenskapsvärdet `code` är `issuance_error`innehåller den här egenskapen information om felet.
`error.code`	sträng	Returfelkoden.
`error.message`	sträng	Felmeddelandet.

I följande exempel visas en nyttolast för återanrop när autentiseringsappen startar utfärdandebegäran:

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

I följande exempel visas en nyttolast för återanrop när användaren har slutfört utfärdandeprocessen:

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

Återanropsfel

Motringningsslutpunkten kan anropas med ett felmeddelande. I följande tabell visas felkoderna:

Meddelande	Definition
`fetch_contract_error`	Det gick inte att hämta det verifierbara autentiseringsuppgiftskontraktet. Det här felet inträffar vanligtvis när API:et inte kan hämta det manifest som du anger i begärandenyttolasten RequestIssuance-objektet.
`issuance_service_error`	Verifierbara autentiseringsuppgifter kan inte verifiera krav, eller så gick något fel i Verifierbara autentiseringsuppgifter.
`unspecified_error`	Det här felet är ovanligt, men värt att undersöka.

I följande exempel visas en återanropsnyttolast när ett fel inträffade:

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

Nästa steg

Lär dig hur du anropar REST-API:et för begärandetjänsten.

Share via