Especificación de la emisión de la API REST de servicios de solicitudes
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>
{
"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.
{
"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"
}
La carga contiene las propiedades siguientes:
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 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 o false (valor predeterminado). 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 que se puede resolver en DNS. Para proteger la red, consulte Preguntas más frecuentes. |
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:
|
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.