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

Artículo
02/26/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 REST del servicio de solicitudes para una solicitud de emisión. En otro artículo se describe cómo llamar a la API de REST del servicio de solicitudes.

Solicitud HTTP

La solicitud de emisión de la API de REST del servicio 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 emisión de la API REST de servicios requiere los siguientes encabezados HTTP:

Nombre	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.

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

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

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

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 útil de solicitud de emisión

La carga útil de la solicitud de emisión contiene información sobre la solicitud de emisión de credenciales verificables. En el ejemplo siguiente se muestra una solicitud de emisión mediante un flujo de código PIN con notificaciones de usuario, como el nombre y el apellido. El resultado de esta solicitud devuelve un código QR con un vínculo para iniciar el proceso de emisión.

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

La carga contiene las propiedades siguientes:

Parámetro	Tipo	Description
`includeQRCode`	Boolean	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 analice. Al examinar el código QR, se inicia la aplicación de autenticación con esta solicitud de emisió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.
`callback`	Callback	Mandatory. Permite al desarrollador obtener información de forma asincrónica sobre el flujo durante el proceso de emisión de credenciales verificable. Por ejemplo, es posible que el desarrollador quiera una llamada cuando el usuario haya examinado el código QR o si la solicitud de emisión se realiza correctamente o no.
`authority`	string	Identificador descentralizado del emisor (DID). Para más información, consulte Recopilación de credenciales y detalles del entorno para configurar la aplicación de ejemplo.
`registration`	RequestRegistration	Proporciona información sobre el emisor que se puede mostrar en la aplicación de autenticación.
`type`	string	El tipo de credencial verificable. Debe coincidir con el tipo tal como se define en el manifiesto de credencial verificable. Por ejemplo: `VerifiedCredentialExpert`. Para más información, vea Creación de la tarjeta de experto de credenciales verificables en Azure.
`manifest`	string	Dirección URL del documento de manifiesto de credencial verificable. Para más información, consulte Recopilación de credenciales y detalles del entorno para configurar la aplicación de ejemplo.
`claims`	string	Opcional. Solo se puede usar para el flujo de atestación de sugerencias de token de id. para incluir una colección de aserciones realizadas sobre el asunto en la credencial verificable.
`pin`	PIN	Opcional. El código PIN solo se puede usar con el flujo de atestación de sugerencia de token de identificador. Número de PIN para proporcionar seguridad adicional durante la emisión. Se genera un código PIN y se presenta al usuario en la aplicación. El usuario debe proporcionar el código PIN que ha generado.
`expirationDate`	string	Opcional. ExpirationDate solo se puede usar con el flujo de atestación de sugerencia de token de identificador. Si se especifica, el valor debe ser una fecha expresada en el formato ISO8601. La fecha invalidará el valor de validityInterval en la definición de reglas de credenciales para esta solicitud de emisión. Use este valor para controlar explícitamente cuándo expira una credencial, como al final del día, fin de mes o fin de año, independientemente de cuándo se emita. Tenga en cuenta que la fecha se expresa en formato UTC. Si especifica a final de año, con el tiempo establecido en `23:59:59`, esto es 1 segundo antes de medianoche en hora UTC. Cualquier usuario de una zona horaria diferente obtendrá la fecha de expiración presentada en la zona horaria local en Microsoft Authenticator. Esto significa que si está en la zona horaria CET, se presentará como 1 de enero a la 1 a. m. El contrato de credenciales debe tener la marca allowOverrideValidityOnIssuance establecida en true.

Actualmente hay cuatro tipos de atestación de notificaciones que puede enviar en la carga. Verified ID de Microsoft Entra tiene cuatro maneras de insertar notificaciones en una credencial verificable y atestiguar esa información con el DID del emisor. A continuación, se muestran los cuatro tipos:

token de identificador
Sugerencia de token de identificador
Credenciales verificables mediante una presentación comprobable
Notificaciones con autoatestación

Puede encontrar información detallada sobre los tipos de entrada en Personalización de la credencial verificable.

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 emisor de la credencial verificable.
`logoUrl`	string	Opcional. Dirección URL del logotipo del emisor.
`termsOfServiceUrl`	string	Opcional. Dirección URL de los términos de uso de la credencial verificable que se va a emitir.

Nota

En este momento, la información de RequestRegistration no se presenta durante la emisión en la aplicación Microsoft Authenticator. Pero esta información se puede usar en la carga.

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. Formatos aceptados 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 de PIN

El tipo pin define un código PIN que se puede mostrar como parte de la emisión. pin es opcional y, si se usa, siempre se debe enviar fuera de banda. Cuando se usa un código PIN HASH, debe definir las propiedades salt, alg y iterations. pin contiene las propiedades siguientes:

Propiedad	Tipo	Description
`value`	string	Contiene el valor de PIN en texto sin formato. Cuando se usa un PIN con hash, la propiedad value contiene el hash cifrado con sal, codificado en base64.
`type`	string	Tipo del código PIN. Valor posible: `numeric` (predeterminado).
`length`	integer	La longitud del código PIN. La longitud predeterminada es 6, la mínima es 4 y la máxima es 16.
`salt`	string	Sal del código PIN con hash. La sal se antepone durante el cálculo hash. Codificación = UTF-8.
`alg`	string	Algoritmo de hash para el PIN con hash. Algoritmo compatible: `sha256`.
`iterations`	integer	El número de iteraciones de hash. Valor posible: `1`.

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

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 y permite realizar el seguimiento de la solicitud de emisión y sus devoluciones de llamada.
`url`	string	Una dirección URL que inicia la aplicación de autenticación e inicia el proceso de emisión. Puede presentar esta dirección URL al usuario si no puede examinar el código QR.
`expiry`	integer	Indica cuándo expirará la respuesta.
`qrCode`	string	Código QR que el usuario puede examinar para iniciar el flujo de emisión.

Cuando la aplicación recibe la respuesta, la aplicación debe presentar el código QR al usuario. El usuario examina el código QR, que abre la aplicación de autenticación e inicia el proceso de emisión.

Respuesta de error

Si se produce un error con la solicitud, se devolverá 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 examina el código QR, usa el vínculo profundo de la aplicación de autenticación o finaliza el proceso de emisió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 devuelto para la solicitud. Posibles valores: `request_retrieved`: el usuario ha examinado el código QR o ha seleccionado el vínculo que inicia el flujo de emisión. `issuance_successful`: la emisión de las credenciales verificables se ha realizado correctamente. `issuance_error`: error durante la emisión. Para obtener más información, vea la propiedad `error`.
`state`	string	Devuelve el valor de estado que ha pasado en la carga original.
`error`	error	Cuando el valor de propiedad `code` es `issuance_error`, esta propiedad contiene información sobre el error.
`error.code`	string	Código de error devuelto.
`error.message`	string	El mensaje de error.

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

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

En el ejemplo siguiente se muestra una carga de devolución de llamada después de que el usuario haya completado correctamente el proceso de emisión:

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

Errores de devolución de llamada

Es posible llamar al punto de conexión de devolución de llamada con un mensaje de error. En la tabla siguiente se enumeran los códigos de error:

Mensaje	Definición
`fetch_contract_error`	No se puede capturar el contrato de credenciales verificable. Este error se suele producir cuando la API no puede capturar el manifiesto especificado en el objeto RequestIssuance de la carga de la solicitud.
`issuance_service_error`	El servicio de credenciales verificables no puede validar los requisitos, o bien se ha producido un error en Credenciales verificables.
`unspecified_error`	Este error es poco frecuente, pero merece la pena investigarlo.

En el ejemplo siguiente se muestra una carga de devolución de llamada cuando se produce un error:

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

Pasos siguientes

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

Share via