Especificación de presentación de la API REST de servicios de solicitudes

Artículo
02/07/2024

Verified ID de Microsoft Entra incluye la API de REST del servicio de solicitudes. Esta API permite emitir y comprobar una credencial. En este artículo se especifica la API de REST del servicio de solicitudes para una solicitud de presentación. La solicitud de presentación pide al usuario que presente una credencial verificable y luego la comprueba. En otro artículo se describe cómo llamar a la API de REST del servicio de solicitudes.

Solicitud HTTP

La solicitud de presentación de la API de REST del servicio de solicitudes admite el siguiente método HTTP:

Método	Notas
POST	Con la carga JSON que se especifica en este artículo.

La solicitud de presentación de la API de REST del servicio de solicitudes requiere los siguientes encabezados HTTP:

Método	Valor
`Authorization`	Adjunte el token de acceso como token de portador al encabezado de autorización de una solicitud HTTP. Por ejemplo, `Authorization: Bearer <token>`.
`Content-Type`	`Application/json`

Cree una solicitud HTTP POST para la API de REST del servicio de solicitudes. tenantId ya no es necesario en la dirección URL, ya que está presente como una notificación en el access_token.

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

En la siguiente solicitud HTTP se muestra una solicitud de presentación a la API de REST del servicio de solicitudes:

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

El siguiente permiso es necesario para llamar a la API de REST del servicio de solicitudes. Si desea más información, consulte Concesión permisos para obtener tokens de acceso.

Tipo de permiso	Permiso
Application	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Carga de la solicitud de presentación

La carga de la solicitud de presentación contiene información sobre su solicitud de presentación de credenciales verificables. En el siguiente ejemplo se muestra una solicitud de presentación de un emisor específico. El resultado de esta solicitud devuelve un código QR con un vínculo para iniciar el proceso de presentación.

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

La carga contiene las siguientes propiedades:

Parámetro	Tipo	Description
`includeQRCode`	Boolean	Opcional. Determina si se incluye un código QR en la respuesta de esta solicitud. Presente el código QR y pida al usuario que lo digitalice. Al digitalizar el código QR, se iniciará la aplicación autenticadora con esta solicitud de presentación. Los valores posibles son `true` (valor predeterminado) o `false`. Si establece el valor en `false`, use la propiedad `url` de devolución para representar un vínculo profundo.
`includeReceipt`	Boolean	Opcional. Determina si se debe incluir un recibo en la respuesta de esta solicitud. Los valores posibles son `true` o `false` (valor predeterminado). El recibo contiene la carga original enviada desde el autenticador al servicio de credenciales verificables. El recibo es útil para solucionar problemas o si tiene la necesidad de obtener los detalles completos de la carga. De lo contrario, no es necesario establecer este valor en `true` de forma predeterminada. En la solicitud `OpenId Connect SIOP`, el recibo contiene el token de identificación de la solicitud original.
`authority`	cadena	Identificador descentralizado (DID) del inquilino de Microsoft Entra de comprobación. Para obtener más información, consulte Recopilación de detalles del inquilino para configurar la aplicación de ejemplo.
`registration`	RequestRegistration	Proporciona información sobre el comprobador.
`callback`	Callback	Mandatory. Permite al desarrollador actualizar la interfaz de usuario durante el proceso de presentación de credenciales verificables. Cuando el usuario complete el proceso, continúe con este una vez que los resultados se devuelvan a la aplicación.
`requestedCredentials`	collection	Colección de objetos RequestCredential.

Tipo RequestRegistration

El tipo RequestRegistration proporciona el registro de información para el emisor. El tipo RequestRegistration contiene las propiedades siguientes:

Propiedad	Tipo	Description
`clientName`	string	Nombre para mostrar del supervisor de la credencial verificable. Este nombre se presentará al usuario en la aplicación autenticadora.
`purpose`	string	Opcional. Cadena que se muestra para informar al usuario del porqué se solicitan las credenciales verificables.
`logoUrl`	URL	Opcional. Dirección URL de un logotipo del supervisor. No se usa por la aplicación Authenticator.
`termsOfServiceUrl`	URL	Opcional. Dirección URL de los términos de servicio para el supervisor. No se usa por la aplicación Authenticator.

En la siguiente captura de pantalla se muestra la propiedad clientName y el nombre para mostrar de authority (el comprobador) en la solicitud de presentación.

Captura de pantalla que muestra cómo aprobar la solicitud de presentación.

Tipo de devolución de llamada

La API de REST del servicio de solicitudes genera varios eventos para el punto de conexión de devolución de llamada. Esos eventos permiten actualizar la interfaz de usuario y continuar con el proceso una vez que se devuelven los resultados a la aplicación. El tipo Callback contiene las propiedades siguientes:

Propiedad	Tipo	Description
`url`	string	URI al punto de conexión de devolución de llamada de la aplicación. El URI debe apuntar a un punto de conexión accesible en Internet; de lo contrario, el servicio producirá un error ilegible en la URL de devolución de llamada. Entradas aceptadas IPv4, IPv6 o nombre de host resoluble DNS.
`state`	string	Correlaciona el evento de devolución de llamada con el estado pasado en la carga original.
`headers`	string	Opcional. Puede incluir una colección de encabezados HTTP necesarios para el extremo receptor del mensaje POST. Los valores de encabezado admitidos actuales son los encabezados `api-key` o `Authorization`. Cualquier otro encabezado producirá un error de encabezado de devolución de llamada no válido.

Tipo RequestCredential

RequestCredential proporciona información sobre las credenciales solicitadas que el usuario debe proporcionar. RequestCredential contiene las propiedades siguientes:

Propiedad	Tipo	Description
`type`	string	Tipo de credencial verificable. `type` debe coincidir con el tipo que se define en el manifiesto de credencial verificable `issuer` (por ejemplo, `VerifiedCredentialExpert`). Para obtener el manifiesto del emisor, vea Recopilación de credenciales y detalles del entorno para configurar la aplicación de ejemplo. Copie la dirección URL de emisión de credenciales, ábrala en un explorador web y compruebe la propiedad id.
`purpose`	string	Opcional. Proporciona información sobre el propósito de solicitar esta credencial verificable. No se usa por la aplicación Authenticator.
`acceptedIssuers`	string collection	Opcional. DID de una colección de emisores que podría emitir el tipo de credencial verificable que los sujetos pueden presentar. Para obtener el DID del emisor, vea Recopilación de credenciales y detalles del entorno para configurar la aplicación de ejemplo y copie el valor del identificador descentralizado (DID) . Si la colección `acceptedIssuers` estuviera vacía o no estuviera presente, la solicitud de presentación aceptará un tipo de credencial que emita cualquier emisor.
`configuration.validation`	Configuration.Validation	Configuración opcional para la validación de la presentación.
`constraints`	Restricciones	Opcional. Colección de restricciones de notificaciones.

Tipo de Configuration.Validation

Configuration.Validation proporciona información sobre cómo se deben validar las credenciales presentadas. Este contiene las siguientes propiedades:

Propiedad	Tipo	Description
`allowRevoked`	Boolean	Opcional. Determina si se debe aceptar una credencial revocada. El valor predeterminado es `false` (no se debe aceptar).
`validateLinkedDomain`	Boolean	Opcional. Determina si se debe validar el dominio vinculado. El valor predeterminado es `false`. Si establece esta marca en `false` significará que, como una aplicación de usuario de confianza, aceptará credenciales de un dominio vinculado no comprobado. Establecer esta marca en `true` significa que se validará el dominio vinculado y solo se aceptarán los dominios comprobados.
`faceCheck`	faceCheck	Opcional. Permite solicitar una comprobación de ejecución durante la presentación.

Tipo de restricciones

El tipo constraints contiene una colección de restricciones de notificaciones que se deben cumplir cuando una cartera selecciona las credenciales candidatas. Esto permite solicitar una credencial con un valor de notificación específico. Las restricciones especificadas usarán la lógica AND, es decir, si se especifican tres restricciones, se deben cumplir todas ellas. Para cada restricción de la colección, debe seleccionar un operando de valores, contains o startsWith. Los valores no pueden ser expresiones regulares. En las comparaciones se distingue entre mayúsculas y minúsculas.

Propiedad	Tipo	Description
`claimName`	string	Obligatorio. Nombre de la notificación de la restricción. Este es el nombre de la notificación de la credencial verificable. Consulte outputClaim en el tipo claimMapping.
`values`	string collection	Conjunto de valores que deben coincidir con el valor de notificación. Si especifica varios valores, como ["rojo", "verde", "azul"] será una coincidencia si el valor de notificación de la credencial tiene cualquiera de los valores de la colección.
`contains`	cadena	La restricción se evalúa como true si el valor de notificación contiene el valor especificado.
`startsWith`	cadena	La restricción se evalúa como true si el valor de notificación comienza con el valor especificado.

Tipo faceCheck

El tipo faceCheck contiene información para realizar la comprobación de ejecución durante la presentación de una credencial. La credencial solicitada debe contener una foto del titular en la notificación con el nombre especificado por sourcePhotoClaimName. La presentación se realizará correctamente si la comprobación de ejecución alcanza un nivel de confianza igual o mayor a lo que se especifica en la propiedad matchConfidenceThreshold. Si no se alcanza el umbral, se producirá un error en la presentación.

Propiedad	Tipo	Description
`sourcePhotoClaimName`	string	Mandatory. Nombre de la notificación en la credencial que contiene la foto. Consulte outputClaim en el tipo claimMapping.
`matchConfidenceThreshold`	integer	Opcional. El umbral de confianza para una comprobación correcta entre la foto y los datos de ejecución. Debe ser un número entero entre 50 y 100. El valor predeterminado es 70.

Respuesta correcta

Si se completa correctamente, este método devuelve un código de respuesta (HTTP 201 Created) y una colección de objetos de evento en el cuerpo de la respuesta. En el siguiente código JSON se muestra una respuesta correcta:

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

La respuesta contiene las siguientes propiedades:

Propiedad	Tipo	Description
`requestId`	string	Id. de solicitud generado automáticamente. La devolución de llamada usa la misma solicitud, lo que permite realizar el seguimiento de la solicitud de presentación y sus devoluciones de llamada.
`url`	string	Dirección URL que inicia la aplicación autenticadora y pone en marcha el proceso de presentación. Puede presentar esta dirección URL al usuario si no puede digitalizar el código QR.
`expiry`	integer	Indica cuándo expirará la respuesta.
`qrCode`	string	Código QR que el usuario puede digitalizar para iniciar el flujo de presentación.

Cuando reciba la respuesta, su aplicación debe mostrar el código QR al usuario. El usuario digitaliza el código QR, lo que abre la aplicación autenticadora e inicia el proceso de presentación.

Respuesta de error

Si se produce un error con la solicitud, se devuelve una respuesta de error y la aplicación debe controlarla adecuadamente.

Eventos de devolución de llamada

Se llama al punto de conexión de devolución de llamada cuando un usuario digitaliza el código QR, usa el vínculo profundo de la aplicación autenticadora o finaliza el proceso de presentación.

Propiedad	Tipo	Description
`requestId`	string	Se asigna a la solicitud original cuando la carga se ha publicado en el servicio de credenciales verificables.
`requestStatus`	string	El estado que se devolvió cuando la aplicación autenticadora recuperó la solicitud. Posibles valores: `request_retrieved`: el usuario ha digitalizado el código QR o ha seleccionado el vínculo que inicia el flujo de presentación. `presentation_verified`: la validación de la credencial verificable se ha completado correctamente. li>`presentation_error`: se ha producido un error en la presentación.
`state`	string	Devuelve el valor de estado que ha pasado en la carga original.
`subject`	string	DID de usuario de la credencial verificable.
`verifiedCredentialsData`	array	Devuelve una matriz de credenciales verificables solicitadas. En cada credencial verificable, proporciona: Tipos de credencial verificable. DID del emisor Notificaciones recuperadas Dominio del emisor de la credencial verificable. Estado de validación del dominio del emisor de la credencial verificable.
`receipt`	string	Opcional. El recibo contiene la carga original enviada desde la cartera al servicio de credenciales verificables. El recibo se debe usar solo para solución de problemas y depuración. El formato del recibo no es fijo y puede cambiar en función de la cartera y la versión utilizadas.

En el siguiente ejemplo se muestra una carga de devolución de llamada cuando la aplicación autenticadora inicia la solicitud de presentación:

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

En el siguiente ejemplo se muestra una carga de devolución de llamada después de que se haya completado correctamente la presentación de la credencial verificable:

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

Pasos siguientes

Obtenga información sobre cómo llamar a la API REST del servicio de solicitudes.