API de administración de credenciales verificables
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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
"verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"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-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"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 propiedadmappings
son:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
yphoto
.
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": "00001111-aaaa-2222-bbbb-3333cccc4444",
"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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"name": "test1",
"authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
"name": "test2",
"authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
"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.