API de administración de credenciales verificables

Artículo
01/12/2024

La API de administración de Verified ID de Microsoft Entra le permite administrar todos los aspectos del servicio de credenciales verificables. Ofrece una manera de configurar un nuevo servicio, administrar y crear contratos de credenciales verificables, revocar credenciales verificables y dejar de participar por completo en el servicio.

La API está diseñada para desarrolladores que se sientan cómodos con las API RESTful y con permisos suficientes en el inquilino de Microsoft Entra para habilitar el servicio

URL base

La API de Administración se sirve mediante HTTPS. Todas las direcciones URL a las que se hace referencia en la documentación tienen la base siguiente: https://verifiedid.did.msidentity.com.

Autenticación

La API está protegida mediante Microsoft Entra ID y usa tokens de portador de OAuth2. El token de acceso puede ser para un usuario o para una aplicación.

Tokens de portador de usuario

El registro de la aplicación debe tener el permiso de API para Verifiable Credentials Service Admin y, a continuación, al adquirir el token de acceso, la aplicación debe usar el ámbito 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access. El token de acceso debe ser para un usuario con el rol de administrador global o de administrador de directivas de autenticación. Un usuario con rol de lector global podrá realizar llamadas API de solo lectura.

Tokens de portador de aplicaciones

El servicio Verifiable Credentials Service Admin admite los siguientes permisos de aplicaciones.

Permiso	Descripción
VerifiableCredential.Authority.ReadWrite	Permiso para leer y escribir objetos de autoridad
VerifiableCredential.Contract.ReadWrite	Permiso para leer y escribir objetos de contrato
VerifiableCredential.Credential.Search	Permiso para buscar una credencial que se vaya a revocar
VerifiableCredential.Credential.Revoke	Permiso para revocar credenciales emitidas anteriormente
VerifiableCredential.Network.Read	Permiso para leer entradas de la red de identificadores comprobados

El registro de la aplicación deberá tener el permiso de API para Verifiable Credentials Service Admin y los permisos necesarios de la tabla anterior. Al adquirir el token de acceso a través del flujo de credenciales de cliente, la aplicación debería usar el ámbito 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default.

Si la aplicación pretende crear una nueva autoridad, necesita dos cosas. En primer lugar, el registro de la aplicación necesita el VerifiableCredential.Authority.ReadWrite permiso. En segundo lugar, la aplicación necesita tener Create Key permiso en las directivas de acceso de Key Vaults. Si la aplicación solo lee y escribe las autoridades existentes, no necesita el permiso de Key Vault.

Incorporación

Esta API está diseñada para ayudar a crear un nuevo entorno para que se puedan configurar nuevas autoridades. Esto también se puede desencadenar manualmente; para ello, vaya a la página Credencial verificable en Azure Portal. Solo tiene que llamar a esta API una vez y solo si desea configurar un entorno nuevo con la API.

Solicitud HTTP

POST /v1.0/verifiableCredentials/onboard

Use este punto de conexión para finalizar el aprovisionamiento del servicio de credenciales verificables en el inquilino. El sistema crea el resto de las entidades de servicio si aún no se han aprovisionado.

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje devuelto

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
    "verifiableCredentialServicePrincipalId": "90e10a26-94cd-49d6-8cd7-cacb10f00686",
    "verifiableCredentialRequestServicePrincipalId": "870e10a26-94cd-49d6-8cd7-cacb10f00fe",
    "verifiableCredentialAdminServicePrincipalId": "760e10a26-94cd-49d6-8cd7-cacb10f00ab",
    "status": "Enabled"
}

Llamar repetidamente a esta API dará como resultado el mismo mensaje devuelvo exacto.

Autoridades

Este punto de conexión se puede usar para crear o actualizar una instancia de servicio de credenciales verificables.

Métodos

Métodos	Tipo de valor devuelto	Descripción
Obtener autoridad	Autoridad	Leer las propiedades de una autoridad
Enumerar autoridades	Matriz de autoridades	Obtener una lista de todos los servicios de credenciales verificables y autoridades configurados
Crear autoridad	Autoridad	Crear una nueva autoridad
Actualizar autoridad	Autoridad	Actualizar una autoridad
Eliminar autoridad	Autoridad	Eliminar autoridad
Generar una configuración conocida de DID
Generar documento de DID
Validar una configuración conocida de DID
Rotar la clave de firma	Autoridad	Rotación de una clave de firma
Sincronización con el documentación DID	Autoridad	Sincronizar el documento DID con la nueva clave de firma

Obtener autoridad

Recupere las propiedades de una autoridad configurada o una instancia de servicio de credenciales verificables.

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId

Reemplace :authorityId por el valor de una de las autoridades configuradas.

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ffea7eb3-0000-1111-2222-000000000000",
    "name": "ExampleAuthorityName",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vccontosokv",
        "resourceUrl": "https://vccontosokv.vault.azure.net/"
    }
}

La respuesta contiene las siguientes propiedades.

Tipo de autoridad

Propiedad	Tipo	Description
`Id`	string	Identificador único generado automáticamente, que se puede usar para recuperar o actualizar la instancia específica del servicio de credenciales verificables
`name`	string	Nombre descriptivo de esta instancia del servicio de credenciales verificables
`status`	string	Estado del servicio; este valor siempre será `enabled`.
didModel	didModel	Información sobre el DID y las claves
keyVaultMetadata	keyVaultMetadata	Información sobre el almacén de claves utilizado

Tipo de didModel

Web

Propiedad	Tipo	Description
`did`	string	DID de esta instancia de servicio de credenciales verificables
`signingKeys`	matriz de cadenas	Dirección URL a la clave de firma
`linkedDomainUrls`	matriz de cadenas	Dominios vinculados a este DID, se espera una sola entrada.
didModel	didModel	Información sobre el DID y las claves
`didDocumentStatus`	string	Estado del DID, el valor siempre es `published` para este método.

Tipo de keyVaultMetadata

Propiedad	Tipo	Description
`subscriptionId`	string	Suscripción de Azure en la que reside este almacén de claves
`resourceGroup`	string	Nombre del grupo de recursos de este almacén de claves
`resourceName`	string	Nombre del almacén de claves
`resourceUrl`	string	Dirección URL a este almacén de claves

Enumerar autoridades

Obtener todas las autoridades configuradas o los servicios de credenciales verificables de este inquilino

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

El mensaje de respuesta es una matriz de autoridades. Ejemplo:

HTTP/1.1 200 OK
Content-type: application/json
{
    value:

    [
        {
            "id": "ffea7eb3-0000-1111-2222-000000000000",
            "name": "AuthorityName",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid.contoso.com/"
                ],
                "didDocumentStatus": "published"
            },
            "keyVaultMetadata": {
                "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
                "resourceGroup": "verifiablecredentials",
                "resourceName": "vccontosokv",
                "resourceUrl": "https://vccontosokv.vault.azure.net/"
            }
        },
        {
            "id": "cc55ba22-0000-1111-2222-000000000000",
            "name": "AuthorityName2",
            "keyVaultUrl": "https://vccontosokv.vault.azure.net/",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid2.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
                ],
                "recoveryKeys": [],
                "updateKeys": [],
                "encryptionKeys": [],
                "linkedDomainUrls": [
                    "https://verifiedid2.contoso.com/"
                ],
                "didDocumentStatus": "published"
            },
            "keyVaultMetadata": {
                "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
                "resourceGroup": "verifiablecredentials",
                "resourceName": "vccontosokv",
                "resourceUrl": "https://vccontosokv.vault.azure.net/"
            }
        }
    ]
}

Crear autoridad

Esta llamada crea una nueva clave privada, una clave de recuperación y una clave de actualización, las almacena en el almacén de claves de Azure especificado y establece los permisos en este almacén de claves para el servicio de credenciales verificables, y crea un nuevo DID con el documento de DID correspondiente.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de lo siguiente:

Propiedad	Tipo	Description
`name`	string	Nombre para mostrar de esta instancia del servicio
`linkedDomainUrl`	string	Dominio vinculado a este DID
`didMethod`	string	Debe ser `web`
`keyVaultMetadata`	keyVaultMetadata	Metadatos de un almacén de claves específico

Mensaje de ejemplo:

{
  "name":"ExampleName",
  "linkedDomainUrl":"https://verifiedid.contoso.com/",
  "didMethod": "web",
  "keyVaultMetadata":
  {
    "subscriptionId":"b593ade1-e353-43ab-9fb8-cccf669478d0",
    "resourceGroup":"verifiablecredentials",
    "resourceName":"vccontosokv",
    "resourceUrl": "https://vccontosokv.vault.azure.net/"
  }
}

Mensaje de respuesta

Cuando se ejecuta correctamente, el mensaje de respuesta contiene el nombre de la autoridad.

Mensaje de ejemplo para did:web:

{
    "id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

Mensaje de ejemplo para did:ion:

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "cc55ba22-0000-1111-2222-000000000000",
    "name": "APItest6",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "submitted"
    },
    "keyVaultMetadata": {
        "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vccontosokv",
        "resourceUrl": "https://vccontosokv.vault.azure.net/"
    }
}

Observaciones

Puede crear varias autoridades con sus propios DID y claves privadas, que no serán visibles en la interfaz de usuario de Azure Portal. Actualmente, solo se admite tener 1 autoridad. No hemos probado completamente todos los escenarios con varias autoridades creadas. Si va a intentarlo, háganoslo saber su experiencia.

Actualizar una autoridad

Este método se puede usar para actualizar el nombre para mostrar de esta instancia específica del servicio de credenciales verificables.

Solicitud HTTP

PATCH /v1.0/verifiableCredentials/authorities/:authorityId

Reemplace el valor de :authorityId por el valor del identificador de autoridad que desea actualizar.

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de lo siguiente.

Propiedad	Tipo	Description
`name`	string	Nombre para mostrar de esta instancia del servicio

Mensaje de ejemplo

{
  "name":"ExampleIssuerName"
}

Eliminar autoridad

Este método se puede usar para eliminar una autoridad. Actualmente solo se pueden eliminar did:ion autoridades. Cuando se elimina una autoridad, las credenciales de ID verificadas emitidas se vuelven inválidas y ya no se pueden verificar a medida que la autoridad emisora ha desaparecido.

Solicitud HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

Reemplace el valor de :authorityId por el valor del ID de autoridad que desee eliminar.

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

Sin cuerpo de la solicitud

Mensaje de respuesta

Mensaje de respuesta de ejemplo:

Respuesta correcta de la autoridad de eliminación.

HTTP/1.1 200 OK

Si la eliminación de la autoridad se realizó correctamente, pero se la limpieza de las claves de Azure Key Vault fue errónea, obtendrá la siguiente respuesta.

HTTP/1.1 400 Bad Request
Content-type: application/json

{
"error": {
        "code": "deleteIssuerSuccessfulButKeyDeletionFailed",
        "message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
    }
}

Configuración conocida de DID

El método generateWellknownDidConfiguration genera el archivo did-configuration.json firmado. El archivo se debe cargar en la carpeta .well-known de la raíz del sitio web hospedado del dominio en el dominio vinculado de esta instancia de credencial verificable. Las instrucciones se pueden encontrar aquí.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

Debe especificar uno de los dominios del elemento linkedDomains de la autoridad especificada.

{
    "domainUrl":"https://atest/"
}

Mensaje de respuesta

Mensaje de respuesta de ejemplo:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbGciOiJFUzI1NksiL...<SNIP>..."
    ]
}

Guarde este resultado con el nombre de archivo did-configuration.json y cargue este archivo en la carpeta y el sitio web correctos. Si especifica un dominio no vinculado a este DID o documento de DID, recibirá un error:

HTTP/1.1 400 Bad Request
Content-type: application/json

{
  "requestId":"079192a95fbf56a661c1b2dd0e012af5",
  "date":"Mon, 07 Feb 2022 18:55:53 GMT",
  "mscv":"AVQh55YiU3FxMipB.0",
  "error":
  {
    "code":"wellKnownConfigDomainDoesNotExistInIssuer",
    "message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
  }
}

Observaciones

Puede apuntar varios DID al mismo dominio. Si elige esta configuración, debe combinar los tokens generados y colocarlos en el mismo archivo did-configuration.json. El archivo contiene una matriz de estos tokens.

Por ejemplo:

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbG..token1...<SNIP>...",
        "eyJhbG..token2...<SNIP>..."
    ]
}

Generar documento de DID

Esta llamada genera el documento de DID usado para los identificadores DID:WEB. Después de generar este documento de DID, el administrador debe colocar el archivo en la ubicación https://domain/.well-known/did.json.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "did:web:verifiedid.contoso.com",
    "@context": [
        "https://www.w3.org/ns/did/v1",
        {
            "@base": "did:web:verifiedid.contoso.com"
        }
    ],
    "service": [
        {
            "id": "#linkeddomains",
            "type": "LinkedDomains",
            "serviceEndpoint": {
                "origins": [
                    "https://verifiedid.contoso.com/"
                ]
            }
        },
        {
            "id": "#hub",
            "type": "IdentityHub",
            "serviceEndpoint": {
                "instances": [
                    "https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
                ]
            }
        }
    ],
    "verificationMethod": [
        {
            "id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
            "controller": "did:web:verifiedid.contoso.com",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyJwk": {
                "crv": "secp256k1",
                "kty": "EC",
                "x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
                "y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
            }
        }
    ],
    "authentication": [
        "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
    ],
    "assertionMethod": [
        "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
    ]
}

Comentario

Requiere que el autor de llamada tenga los permisos de enumeración de claves en el almacén de claves de destino.

Validar una configuración conocida de DID

Esta llamada comprueba la configuración del DID. Descarga la configuración conocida de DID y valida si se usa el DID correcto y si la firma es correcta.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

HTTP/1.1 204 No Content
Content-type: application/json

Rotación de una clave de firma

La rotación de las claves de firma crea una nueva clave privada de la autoridad did:web. El documento DID debe volver a registrarse para reflejar la actualización. Una vez hecho esto, el synchronizeWithDidDocument indica al sistema que empiece a usar la nueva clave para firmar.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

El didDocumentStatus cambiará a outOfSync.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "outOfSync"
    },
    "keyVaultMetadata": {
        "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

Sincronización con el documentación DID

Después de rotar la clave de firma, el documento DID debe volver a registrarse para reflejar la actualización. Una vez hecho esto, el synchronizeWithDidDocument indica al sistema que empiece a usar la nueva clave para firmar.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

El didDocumentStatus cambiará de outOfSync a published en una llamada correcta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "bacf5333-d68c-01c5-152b-8c9039fbd88d",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "published"
    },
    "keyVaultMetadata": {
        "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

Contratos

Este punto de conexión le permite crear nuevos contratos y actualizar los contratos existentes. Los contratos constan de dos partes representadas por dos definiciones JSON. Aquí encontrará información sobre cómo diseñar y crear un contrato manualmente.

Los administradores usan la definición de presentación para controlar la apariencia de una credencial verificable, por ejemplo, el color de fondo, el logotipo y el título de la credencial verificable. Este archivo también contiene las notificaciones que se deben almacenar dentro de la credencial verificable.
La definición de reglas contiene la información sobre cómo reunir y recopilar atestaciones, como las notificaciones autoatestiguadas, otra credencial verificable como entrada o quizá un token de identificador recibido después de que un usuario haya iniciado sesión en un proveedor de identidades compatible con OIDC.

Métodos

Métodos	Tipo de valor devuelto	Descripción
Obtener contrato	Contrato	Leer las propiedades de un contrato
Enumerar contratos	Colección de contratos	Obtener una lista de todos los contratos configurados
Crear contrato	Contrato	Crear un contenedor nuevo
Actualizar contrato	Contrato	Actualizar contrato

Obtener contrato

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

Reemplace :authorityId y :contractId por el valor correcto de la autoridad y el contrato.

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

Mensaje de ejemplo:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": false,
    "manifestUrl": "...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": <rulesModel>,
    "displays": <displayModel[]>,
    "allowOverrideValidityIntervalOnIssuance": false
}

La respuesta contiene las siguientes propiedades:

Tipo de contrato

Propiedad	Tipo	Description
`Id`	string	Identificador de contrato
`name`	string	Nombre descriptivo de este contrato
`status`	string	Siempre `Enabled`
`manifestUrl`	string	Dirección URL del contrato utilizada en la solicitud de emisión
`issueNotificationEnabled`	boolean	Se establece en true si se va a notificar a los usuarios que esta credencial verificable está lista para su emisión.
`issueNotificationAllowedToGroupOids`	Matriz de cadenas groupId	Matriz de identificadores de grupo a los que se va a ofrecer esta credencial
`availableInVcDirectory`	boolean	¿Este contrato se ha publicado en la red de credenciales verificables?
rules	rulesModel	Definición de reglas
displays	Matriz de displayModel	Definiciones de visualización
`allowOverrideValidityIntervalOnIssuance`	boolean	Si la llamada API createIssuanceRequest puede invalidar la expiración de la credencial. Esto solo es válido para los flujos idTokenHint.

tipo rulesModel

Propiedad	Tipo	Descripción
`attestations`	attestations	Descripción de las entradas admitidas para las reglas
`validityInterval`	number	Este valor muestra la duración de la credencial.
`vc`	selección de vcType	tipos para este contrato
`customStatusEndpoint`	[customStatusEndpoint] (#customstatusendpoint-type) (opcional)	Punto de conexión de estado que se va a incluir en la credencial verificable de este contrato

Si no se especificase la propiedad customStatusEndpoint, se usará el punto de conexión de estado anonymous.

tipo de atestaciones

Propiedad	Tipo	Descripción
`idTokens`	idTokenAttestation (array) (optional)	describe las entradas del token de identificación.
`idTokenHints`	idTokenHintAttestation (array) (optional)	describe las entradas de sugerencia del token de identificación
`presentations`	verifiablePresentationAttestation (array) (optional)	describe las entradas de presentaciones verificables
`selfIssued`	selfIssuedAttestation (array) (optional)	describe las entradas autoemitidas
`accessTokens`	accessTokenAttestation (array) (optional)	describe las entradas del token de acceso

Tipo idTokenAttestation

Propiedad	Tipo	Descripción
`mapping`	claimMapping (opcional)	reglas para asignar notificaciones de entrada a notificaciones de salida en la credencial verificable
`configuration`	string (url)	ubicación del documento de configuración del proveedor de identidades
`clientId`	string	identificador de cliente que se va a usar al obtener el token de identificador
`redirectUri`	string	El URI de redireccionamiento que se usará al obtener el token de identificador DEBE SER vcclient://openid/
`scope`	string	lista delimitada por espacios de ámbitos que se van a usar al obtener el token de identificador
`required`	boleano (valor predeterminado falso)	indica si esta atestación es necesaria o no

tipo idTokenHintAttestation

Propiedad	Tipo	Descripción
`mapping`	claimMapping (opcional)	reglas para asignar notificaciones de entrada a notificaciones de salida en la credencial verificable
`required`	boleano (valor predeterminado falso)	indica si esta atestación es necesaria o no
`trustedIssuers`	cadena (conjunto)	Lista de los DID que pueden emitir la credencial verificable para este contrato

tipo verifiablePresentationAttestation

Propiedad	Tipo	Descripción
`mapping`	claimMapping (opcional)	reglas para asignar notificaciones de entrada a notificaciones de salida en la credencial verificable
`credentialType`	cadena (opcional)	tipo de credencial necesario de la entrada
`required`	boleano (valor predeterminado falso)	indica si esta atestación es necesaria o no
`trustedIssuers`	cadena (conjunto)	Lista de los DID que pueden emitir la credencial verificable para este contrato

tipo selfIssuedAttestation

Propiedad	Tipo	Descripción
`mapping`	claimMapping (opcional)	reglas para asignar notificaciones de entrada a notificaciones de salida en la credencial verificable
`required`	boleano (valor predeterminado falso)	indica si esta atestación es necesaria o no

Tipo accessTokenAttestation

Propiedad	Tipo	Descripción
`mapping`	claimMapping (opcional)	reglas para asignar notificaciones de entrada a notificaciones de salida en la credencial verificable
`required`	boleano (valor predeterminado falso)	indica si esta atestación es necesaria o no

Los valores de inputClaim admitidos para la propiedad mappings son: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, jobTitle y photo.

tipo claimMapping

Propiedad	Tipo	Description
`inputClaim`	string	nombre de la notificación que se va a usar desde la entrada
`outputClaim`	string	nombre de la notificación de la credencial verificable
`indexed`	boleano (valor predeterminado falso)	Indica si se utiliza el valor de esta notificación para la búsqueda; solo se puede indexar un objeto clientMapping para un contrato determinado.
`required`	boleano (valor predeterminado falso)	indica si esta asignación es necesaria o no
`type`	cadena (opcional)	tipo de solicitud

Tipo customStatusEndpoint

Propiedad	Tipo	Descripción
`url`	string (url)	la dirección URL del punto de conexión de estado personalizado
`type`	cadena	el tipo del punto de conexión

ejemplo:

"rules": {
    "attestations": {
        "idTokens": [
            {
                "clientId": "2f670d73-624a-41fe-a139-6f1f8f2d2e47",
                "configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
                "redirectUri": "vcclient://openid/",
                "scope": "openid",
                "mapping": [
                    {
                        "outputClaim": "givenName",
                        "required": false,
                        "inputClaim": "given_name",
                        "indexed": false
                    },
                    {
                        "outputClaim": "familyName",
                        "required": false,
                        "inputClaim": "family_name",
                        "indexed": true
                    }
                ],
                "required": false
            }
        ]
    },
    "validityInterval": 2592000,
    "vc": {
        "type": [
            "BankofWoodgroveIdentity"
        ]
    }
}

tipo displayModel

Propiedad	Tipo	Description
`locale`	string	configuración regional de esta visualización
`credential`	displayCredential	las propiedades de visualización de la credencial verificable
`consent`	displayConsent	datos adicionales cuando se genera la credencial verificable
`claims`	conjunto de displayClaims	etiquetas para las notificaciones incluidas en la credencial verificable

tipo displayCredential

Propiedad	Tipo	Description
`title`	string	título de la credencial
`issuedBy`	string	nombre del emisor de la credencial
`backgroundColor`	número (hexadecimal)	Color de fondo de la credencial en formato hexadecimal, por ejemplo, #FFAABB
`textColor`	número (hexadecimal)	Color del texto de la credencial en formato hexadecimal, por ejemplo, #FFAABB
`description`	string	Texto adicional que se muestra con cada credencial
`logo`	displayCredentialLogo	logotipo que se va a usar para la credencial

tipo displayCredentialLogo

Propiedad	Tipo	Descripción
`uri`	cadena (URI)	identificador URI del logotipo. Si se trata de una dirección URL, debe ser accesible a través de la red pública de Internet de forma anónima.
`description`	string	descripción de logotipo

tipo displayConsent

Propiedad	Tipo	Description
`title`	string	título del consentimiento
`instructions`	string	texto adicional que se va a usar cuando se muestre el consentimiento

tipo displayClaims

Propiedad	Tipo	Description
`label`	string	etiqueta de la solicitud de visualización
`claim`	string	nombre de la solicitud a la que se aplica la etiqueta
`type`	string	tipo de solicitud
`description`	cadena (opcional)	descripción de solicitud

Ejemplo:

{
  "displays": [
        {
            "locale": "en-US",
            "card": {
                "backgroundColor": "#FFA500",
                "description": "ThisisyourBankofWoodgroveIdentity",
                "issuedBy": "BankofWoodgrove",
                "textColor": "#FFFF00",
                "title": "BankofWoodgroveIdentity",
                "logo": {
                    "description": "Defaultbankofwoodgrovelogo",
                    "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
                }
            },
            "consent": {
                "instructions": "Please login with your bankofWoodgrove account to receive this credential.",
                "title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
            },
            "claims": [
                {
                    "claim": "vc.credentialSubject.givenName",
                    "label": "Name",
                    "type": "String"
                },
                {
                    "claim": "vc.credentialSubject.familyName",
                    "label": "Surname",
                    "type": "String"
                }
            ]
        }
    ]
}

Enumerar contratos

Esta API enumera todos los contratos configurados en el inquilino actual para la autoridad especificada.

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

Mensaje de ejemplo:

{
    "value":
    [
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
            "name": "test1",
            "authorityId": "ffea7eb3-0000-1111-2222-000000000000",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
            "name": "test2",
            "authorityId": "cc55ba22-0000-1111-2222-000000000000",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        }
    ]
}

Crear contrato

Al crear un contrato, el nombre debe ser único en el inquilino. En caso de que haya creado varias autoridades, el nombre del contrato debe ser único en todas las autoridades. El nombre del contrato formará parte de la dirección URL del contrato, el cual se usa en las solicitudes de emisión.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

Solicitud de ejemplo

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

Mensaje de respuesta

Mensaje de ejemplo:

HTTP/1.1 201 Created
Content-type: application/json

{
    "id": "GUID",
    "name": "ExampleContractName1",
    "issuerId": "cc55ba22-0000-1111-2222-000000000000",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
    "manifestUrl": "https://..."
}

Actualizar contrato

Esta API permite actualizar el contrato.

PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid

Solicitud de ejemplo:

{
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],}
    "availableInVcDirectory": true
    "allowOverrideValidityIntervalOnIssuance": true
}

Mensaje de respuesta

Mensaje de ejemplo:

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": true,
    "manifestUrl": "https://...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": rulesModel,
    "displays": displayModel[],
    "allowOverrideValidityIntervalOnIssuance": true
}

Credenciales

Este punto de conexión permite buscar las credenciales verificables emitidas, comprobar el estado de revocación y revocar las credenciales.

Métodos

Métodos	Tipo de valor devuelto	Descripción
Obtener credencial	Credential:	Leer las propiedades de una credencial
Buscar credenciales	Colección de credenciales	Buscar una lista de credenciales con un valor de notificación específico
Revocar credencial		Revocar una credencial específica

Obtener credencial

Esta API le permite recuperar una credencial específica y comprobar el estado para ver si se ha revocado o no.

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Mensaje de respuesta

Mensaje de ejemplo

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
    "contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
    "status": "valid",
    "issuedAt": "2017-09-13T21:59:23.9868631Z"
}

Buscar credenciales

Puede buscar credenciales verificables con notificaciones de índice específicas. Dado que solo se almacena un hash, debe buscar el valor calculado específico. El algoritmo que debe usar es: Base64Encode(SHA256(contractid + valor de notificación)). Un ejemplo en C# tiene este aspecto:

  string claimvalue = "Bowen";
  string contractid = "<...your-contract-id-value...>";
  string output;

  using (var sha256 = SHA256.Create())
  {
    var input = contractid + claimvalue;
    byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
    hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
    output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
  }

La siguiente solicitud muestra cómo agregar el valor calculado al parámetro de filtro de la solicitud. En este momento, solo se admite el formato filter=indexclaimhash eq.

Solicitud HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

Mensaje de ejemplo

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
            "status": "valid",
            "issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
        }
    ]
}

Revocar credencial

Esta API le permite revocar una credencial específica; después de buscar la credencial mediante la API de búsqueda, la credencial se puede revocar especificando el identificador de credencial específico.

Solicitud HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

HTTP/1.1 204 No Content
Content-type: application/json

Dejar de participar

Este método quitará completamente todas las instancias del servicio de credenciales verificables de este inquilino. Quita todos los contratos configurados. No se pueden comprobar todas las credenciales verificables emitidas para la revocación. Esta acción no se puede deshacer.

Advertencia

Esta acción no se puede deshacer e invalidará todas las credenciales verificables emitidas y los contratos creados.

Solicitud HTTP

POST /v1.0/verifiableCredentials/optout

Encabezados de solicitud

Encabezado	Valor
Authorization	Bearer (token de portador). Requerido
Content-Type	application/json

Cuerpo de la solicitud

No proporcione un cuerpo de la solicitud para este método.

Mensaje de respuesta

Mensaje de respuesta de ejemplo

HTTP/1.1 200 OK
Content-type: application/json

OK

Comentario

Nota

Si no tiene permisos de eliminación en el almacén de claves, se devolverá un mensaje de error y se dejará de participar.