Specifikation Tjänst-REST-API begärandepresentation (förhandsversion)

Azure Active Directory (Azure AD) Verifieable Credentials (Autentiseringsuppgifter för Azure AD) innehåller Tjänst-REST-API. Med det här API:et kan du utfärda och verifiera autentiseringsuppgifter. Den här artikeln anger begärande Tjänst-REST-API en presentationsbegäran. Presentationsbegäran ber användaren att presentera en verifierbar autentiseringsförfrågan och sedan verifiera autentiseringssuppgifter.

HTTP-begäran

Begäran om Tjänst-REST-API stöder följande HTTP-metod:

Metod Kommentarer
POST Med JSON-nyttolasten som anges i den här artikeln.

Begäran om Tjänst-REST-API kräver följande HTTP-huvuden:

Metod Värde
Authorization Koppla åtkomsttoken som en bearer-token till auktoriseringshuvudet i en HTTP-begäran. Till exempel Authorization: Bearer <token>.
Content-Type Application/json

Skapa en HTTP POST-begäran till Tjänst-REST-API. Ersätt med {tenantID} ditt klientorganisations-ID eller klientnamn.

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

Följande HTTP-begäran visar en presentationsbegäran till Tjänst-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"  
      }  
    },  
    ...
} 

Följande behörighet krävs för att anropa Tjänst-REST-API. Mer information finns i Bevilja behörigheter för att hämta åtkomsttoken.

Behörighetstyp Behörighet
Program bbb94529-53a3-4be5-a069-7eaf2712b826/.default

Nyttolast för presentationsbegäran

Nyttolasten för presentationsbegäran innehåller information om din presentationsbegäran om verifierbara autentiseringsuppgifter. I följande exempel visas en presentationsbegäran från en specifik utfärdare. Resultatet av denna begäran returnerar en QR-kod med en länk för att starta presentationsprocessen.

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

Nyttolasten innehåller följande egenskaper.

Parameter Typ Beskrivning
includeQRCode Boolesk Anger om en QR-kod ingår i svaret på den här begäran. Presentera QR-koden och be användaren att skanna den. Genomsökning av QR-koden startar autentiseringsappen med den här presentationsbegä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 rendera en djuplänk.
authority sträng Din decentraliserade identifierare (DID) för din Verifierare Azure AD-klientorganisation. Mer information finns i Samla in klientinformation för att konfigurera exempelprogrammet.
registration RequestRegistration Innehåller information om verifieraren.
presentation RequestPresentation Innehåller information om presentationsbegäran om verifierbara autentiseringsuppgifter.
callback Motringning Gör att utvecklaren kan uppdatera användargränssnittet under presentationsprocessen för verifierbara autentiseringsuppgifter. När användaren har slutfört processen fortsätter du processen när resultatet har returnerats till programmet.

RequestRegistration-typ

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

Egenskap Typ Description
clientName sträng Ett visningsnamn för utfärdaren av de verifierbara autentiseringssuppgifter. Det här namnet visas för användaren i autentiseringsappen.

Följande skärmbild visar clientName egenskapen och visningsnamnet för authority (verifieraren) i presentationsbegäran.

Skärmbild som visar hur du godkänner presentationsbegäran.

RequestPresentation-typ

Typen RequestPresentation innehåller information som krävs för presentation av verifierbara autentiseringsuppgifter. RequestPresentation innehåller följande egenskaper:

Egenskap Typ Beskrivning
includeReceipt Boolesk Anger om ett kvitto ska tas med i svaret på den här begäran. Möjliga värden är true eller false (standard). Kvittot innehåller den ursprungliga nyttolasten som skickades från autentiseraren till tjänsten För verifierbara autentiseringsuppgifter. Kvittot är användbart för felsökning och bör inte anges som standard. I begäran OpenId Connect SIOP innehåller kvittot ID-token från den ursprungliga begäran.
requestedCredentials samling En samling RequestCredential-objekt.

RequestCredential-typ

RequestCredentialinnehåller information om de begärda autentiseringsuppgifter som användaren måste ange. RequestCredential innehåller följande egenskaper:

Egenskap Typ Description
type sträng Den verifierbara autentiseringstypen. typemåste matcha typen enligt definitionen i det issuer verifierbara autentiseringsmanifestet (till exempel VerifiedCredentialExpert ). Information om hur du hämtar utfärdarmanifestet finns i Samla in information om autentiseringsuppgifter och miljö för att konfigurera exempelprogrammet. Kopiera URL:en för autentiseringsuppgifter för problem, öppna den i en webbläsare och kontrollera id-egenskapen.
purpose sträng Ange information om syftet med att begära den här verifierbara autentiseringsinformationen.
acceptedIssuers strängsamling En samling utfärdarens DID:er som kan utfärda den typ av verifierbara autentiseringsuppgifter som ämnen kan uppvisa. För att få din utfärdare DID, se Samla in information om autentiseringsuppgifter och miljö för att konfigurera exempelprogrammet ochkopiera värdet för den decentraliserade identifieraren (DID).

Typ av återanrop

Begärande-Tjänst-REST-API flera händelser till återanropsslutpunkten. 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:

Egenskap Typ Description
url sträng URI till återanropsslutpunkten för ditt program.
state sträng Associerar med det tillstånd som skickades i den ursprungliga nyttolasten.
headers sträng Valfritt. Du kan inkludera en samling HTTP-huvuden som krävs av det mottagande slutet av POST-meddelandet. Huvudena bör endast innehålla - eller api-key -huvudet som krävs för auktorisering.

Lyckat svar

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

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

Svaret innehåller följande egenskaper:

Egenskap Typ Description
requestId sträng Ett automatiskt genererat korrelations-ID. Motringningen använder samma begäran, så att du kan hålla reda på presentationsbegäran och dess återanrop.
url sträng En URL som startar autentiseringsappen och startar presentationsprocessen. Du kan visa den här URL:en för användaren om de inte kan skanna QR-koden.
expiry heltal Anger när svaret upphör att gälla.
qrCode sträng En QR-kod som användaren kan skanna för att starta presentationsflödet.

När appen tar emot svaret måste appen presentera QR-koden för användaren. Användaren genomsöker QR-koden, som öppnar autentiseringsappen och startar presentationsprocessen.

Felsvar

Felsvar kan också returneras så att appen kan hantera dem på rätt sätt. Följande JSON visar ett felmeddelande om obehöriga:

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

Svaret innehåller följande egenskaper:

Egenskap Typ Description
requestId sträng Ett automatiskt genererat begärande-ID.
date date Tidpunkten för felet.
error.code sträng Returfelkoden.
error.message sträng Felmeddelandet.

Återanropshändelser

Återanropsslutpunkten anropas när en användare skannar QR-koden, använder djuplänken till autentiseringsappen eller slutför presentationsprocessen.

Egenskap Typ Description
requestId sträng Mappas till den ursprungliga begäran när nyttolasten skickades till tjänsten Verifiable Credentials.
code sträng Koden som returnerades när begäran hämtades av autentiseringsappen. Möjliga värden:
  • request_retrieved: Användaren skannade QR-koden eller valde länken som startar presentationsflödet.
  • presentation_verified: Verifieringen av verifierbara autentiseringsuppgifter har slutförts.
state sträng Returnerar det tillståndsvärde som du skickade i den ursprungliga nyttolasten.
subject sträng Den verifierbara autentiseringsanvändaren DID.
issuers matris Returnerar en matris med verifierbara autentiseringsuppgifter som begärts. För varje verifierbar autentiseringsidentifiering tillhandahåller den:
  • Den verifierbara autentiseringstypen.
  • Anspråken hämtades.
  • Den verifierbara utfärdarens domän för autentiseringsuppgifter.
  • Den verifierbara utfärdarens domänvalideringsstatus.
  • receipt sträng Valfritt. Kvittot innehåller den ursprungliga nyttolasten som skickades från autentiseraren till verifierbara autentiseringsuppgifter.

    I följande exempel visas en återanropsnyttolast när autentiseringsappen startar presentationsbegäran:

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

    I följande exempel visas en återanropsnyttolast när presentationen av verifierbara autentiseringsuppgifter har slutförts:

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

    Nästa steg

    Lär dig hur du anropar request-Tjänst-REST-API.