Compartir vía


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:
  • 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.