API de administração de credenciais verificáveis

Artigo
02/23/2024

A API de Administração de ID Verificada do Microsoft Entra permite gerenciar todos os aspetos do serviço de Credenciais Verificáveis. Ele oferece uma maneira de configurar um novo serviço, gerenciar e criar contratos de credenciais verificáveis, revogar credenciais verificáveis e desativar completamente o serviço também.

A API destina-se a desenvolvedores confortáveis com APIs RESTful e permissões suficientes no locatário do Microsoft Entra para habilitar o serviço

URL Base

A API Admin é um servidor sobre HTTPS. Todos os URLs referenciados na documentação têm a seguinte base: https://verifiedid.did.msidentity.com.

Autenticação

A API é protegida através do Microsoft Entra ID e usa tokens de portador OAuth2. O token de acesso pode ser para um usuário ou para um aplicativo.

Fichas de utilizador ao portador

O registro do aplicativo precisa ter a permissão da API para Verifiable Credentials Service Admin e, em seguida, ao adquirir o token de acesso, o aplicativo deve usar o escopo 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access. O token de acesso deve ser para um usuário com a função de Administrador Global ou administrador de política de autenticação. Um usuário com leitor global de função pode executar chamadas de API somente leitura.

Tokens de portador de aplicativo

O Verifiable Credentials Service Admin serviço suporta as seguintes permissões de aplicativo.

Permissão	Description
VerifiableCredential.Authority.ReadWrite	Permissão para ler/gravar objeto(s) de autoridade
VerifiableCredential.Contract.ReadWrite	Permissão para ler/gravar objeto(s) de contrato
VerifiableCredential.Credential.Search	Permissão para procurar uma credencial para revogar
VerifiableCredential.Credential.Revoke	Permissão para revogar uma credencial emitida anteriormente
VerifiableCredential.Network.Read	Permissão para ler entradas da Rede de Identificação Verificada

O registro do aplicativo precisa ter a permissão da API e Verifiable Credentials Service Admin as permissões exigidas na tabela acima. Ao adquirir o token de acesso, por meio do fluxo de credenciais do cliente, o aplicativo deve usar o escopo 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default.

Se o aplicativo pretende criar uma nova autoridade, ele precisa de duas coisas. Primeiro, o registro do aplicativo precisa da VerifiableCredential.Authority.ReadWrite permissão. Em segundo lugar, o aplicativo precisa ter Create Key permissão nas Políticas de Acesso aos Cofres de Chaves. Se o aplicativo apenas ler/gravar autoridades existentes, ele não precisará da permissão do Cofre da Chave.

Integração

Esta API destina-se a ajudar a criar um novo ambiente para que possam ser criadas novas autoridades. Isso também pode ser acionado manualmente navegando até a página Credencial Verificável no portal do Azure. Você só precisa chamar essa API uma vez e somente se quiser configurar um novo ambiente apenas com a API.

Pedido HTTP

POST /v1.0/verifiableCredentials/onboard

Use este ponto de extremidade para concluir o provisionamento do serviço de Credenciais Verificáveis em seu locatário. O sistema cria o restante das entidades de serviço se elas ainda não estiverem provisionadas.

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de retorno

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

Chamar repetidamente essa API resulta exatamente na mesma mensagem de retorno.

Autoridades

Esse ponto de extremidade pode ser usado para criar ou atualizar uma instância de serviço de Credenciais Verificáveis.

Métodos

Métodos	Tipo de Retorno	Description
Obter autoridade	Autoridade	Ler propriedades de uma autoridade
Autoridade de lista	Matriz de autoridade	Obtenha uma lista de todas as autoridades/serviços de credenciais verificáveis configurados
Criar Autoridade	Autoridade	Criar uma nova autoridade
Autoridade de atualização	Autoridade	Autoridade de atualização
Suprimir autoridade	Autoridade	Suprimir autoridade
Gerar configuração DID bem conhecida
Gerar documento DID
Validar configuração DID bem conhecida
Girar chave de assinatura	Autoridade	Girar a chave de assinatura
Sincronizar com documento DID	Autoridade	Sincronizar documento DID com nova chave de assinatura

Obtenha autoridade

Recupere as propriedades de uma autoridade configurada ou instância de serviço de credenciais verificável.

Pedido HTTP

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

Substitua o :authorityId pelo valor de uma das autoridades configuradas.

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo de solicitação para este método

Mensagem de resposta

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

A resposta contém as seguintes propriedades.

Tipo de autoridade

Propriedade	Type	Description
`Id`	string	Um ID exclusivo gerado automaticamente, que pode ser usado para recuperar ou atualizar a instância específica do serviço de credenciais verificáveis
`name`	string	O nome amigável desta instância do serviço de credenciais verificáveis
`status`	string	status do serviço, este valor será sempre `enabled`
didModelo	didModelo	Informações sobre o DID e chaves
keyVaultMetadata	keyVaultMetadados	Informações sobre o Cofre da Chave usado

didModel tipo

Web

Propriedade	Type	Description
`did`	string	O DID para esta instância de serviço de credenciais verificável
`signingKeys`	matriz de cadeia de caracteres	URL para a chave de assinatura
`linkedDomainUrls`	matriz de cadeia de caracteres	Domínios ligados a este DID, esperando uma única entrada
didModelo	didModelo	Informações sobre o DID e chaves
`didDocumentStatus`	string	status do DID, o valor é sempre `published` para este método

tipo keyVaultMetadata

Propriedade	Type	Description
`subscriptionId`	string	A assinatura do Azure que este Cofre da Chave reside
`resourceGroup`	string	nome do grupo de recursos deste Cofre da Chave
`resourceName`	string	Nome do Cofre da Chave
`resourceUrl`	string	URL para este Cofre da Chave

Listar autoridades

Obtenha todas as autoridades configuradas ou serviços de credenciais verificáveis para este locatário

Pedido HTTP

GET /v1.0/verifiableCredentials/authorities

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

A mensagem de resposta é uma matriz de Autoridades

Exemplo:

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/"
            }
        }
    ]
}

Criar autoridade

Esta chamada cria uma nova chave privada, chave de recuperação e chave de atualização, armazena essas chaves no Cofre de Chaves do Azure especificado e define as permissões para esse Cofre de Chaves para o serviço de credenciais verificáveis e uma nova criação de DID com o Documento DID correspondente.

Pedido HTTP

POST /v1.0/verifiableCredentials/authorities

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

No corpo da solicitação, forneça uma representação JSON do seguinte

Propriedade	Type	Description
`name`	string	O nome para exibição desta instância do serviço
`linkedDomainUrl`	string	O domínio ligado a este DID
`didMethod`	string	Deve ser `web`
`keyVaultMetadata`	keyVaultMetadata	metadados para cofre de chaves específico

Exemplo de mensagem:

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

Mensagem de resposta

Quando bem-sucedida, a mensagem de resposta contém o nome da autoridade

Exemplo de mensagem 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
}

Exemplo de mensagem 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/"
    }
}

Observações

Você pode criar várias autoridades com suas próprias chaves DID e privadas, elas não serão visíveis na interface do usuário do portal do Azure. Atualmente só apoiamos ter 1 autoridade. Não testamos totalmente todos os cenários com várias autoridades criadas. Se você está tentando isso, por favor, deixe-nos saber sua experiência.

Autoridade de atualização

Esse método pode ser usado para atualizar o nome de exibição dessa instância específica do serviço de credenciais verificáveis.

Pedido HTTP

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

Substitua o valor de pelo valor do ID da :authorityId autoridade que você deseja atualizar.

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

No corpo da solicitação, forneça uma representação JSON do seguinte.

Propriedade	Type	Description
`name`	string	O nome para exibição desta instância do serviço

Mensagem de exemplo

{
  "name":"ExampleIssuerName"
}

Suprimir autoridade

Este método pode ser utilizado para eliminar uma autoridade. Atualmente, apenas did:ion as autoridades podem ser excluídas. Quando elimina uma autoridade, quaisquer credenciais de Identificação Verificada emitidas tornam-se inválidas e não podem mais ser verificadas, uma vez que a autoridade emissora desapareceu.

Pedido HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

Substitua o valor de pelo valor do ID da :authorityId autoridade que você deseja excluir.

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Sem corpo de solicitação

Mensagem de resposta

Exemplo de mensagem de resposta:

Resposta bem-sucedida da autoridade de exclusão.

HTTP/1.1 200 OK

Se a exclusão de autoridade tiver sido bem-sucedida, mas a limpeza das chaves do Cofre de Chaves do Azure tiver falhado, você receberá a resposta abaixo.

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

Configuração DID bem conhecida

O generateWellknownDidConfiguration método gera o arquivo de did-configuration.json assinado. O arquivo deve ser carregado para a .well-known pasta na raiz do site hospedado para o domínio no domínio vinculado desta instância de credencial verificável. As instruções podem ser encontradas aqui.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Você precisa especificar um dos domínios em linkedDomains da autoridade especificada.

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

Mensagem de resposta

Exemplo de mensagem de resposta:

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

Salve este resultado com o nome do arquivo did-configuration.json e carregue esse arquivo para a pasta e o site corretos. Se você especificar um domínio não vinculado a este documento DID/DID, receberá um erro:

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

Observações

Você pode apontar vários DIDs para o mesmo domínio. Se você escolher essa configuração, precisará combinar tokens gerados e colocá-los no mesmo arquivo did-configuration.json. O arquivo contém uma matriz desses tokens.

Por exemplo:

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

Gerar documento DID

Esta chamada gera o documento DID usado para identificadores DID:WEB. Depois de gerar este documento DID, o administrador tem que colocar o https://domain/.well-known/did.json arquivo no local.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

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

Observação

Requer que o chamador tenha as permissões KEY List no cofre de chaves de destino.

Validar configuração DID bem conhecida

Esta chamada verifica a configuração do DID. Ele baixa a configuração DID bem conhecida e valida se o DID correto é usado e a assinatura está correta.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

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

Girar a chave de assinatura

A chave de assinatura rotativa cria uma nova chave privada para a autoridade did:web. O documento DID deve ser registado novamente para refletir a atualização. Quando isso é feito, o synchronizeWithDidDocument diz ao sistema para começar a usar a nova chave para assinatura.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do Pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

A didDocumentStatus vontade mudará para 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
}

Sincronizar com documento DID

Depois de girar a chave de assinatura, o documento DID deve ser registrado novamente para refletir a atualização. Quando isso é feito, o synchronizeWithDidDocument diz ao sistema para começar a usar a nova chave para assinatura.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do Pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

A didDocumentStatus vontade mudará de outOfSync para published em uma chamada bem-sucedida.

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

Esse ponto de extremidade permite criar novos contratos e atualizar contratos existentes. Os contratos consistem em duas partes representadas por duas definições JSON. Informações sobre como projetar e criar um contrato manualmente podem ser encontradas aqui.

A definição de exibição é usada pelos administradores para controlar a aparência de uma credencial verificável, por exemplo, cor de plano de fundo, logotipo e título da credencial verificável. Esse arquivo também contém as declarações que precisam ser armazenadas dentro da credencial verificável.
A definição de regras contém as informações sobre como coletar e coletar atestados, como declarações autocertificadas, outra credencial verificável como entrada ou talvez um token de ID recebido depois que um usuário entrou em um provedor de identidade compatível com OIDC.

Métodos

Métodos	Tipo de Retorno	Description
Obter contrato	Contract	Ler propriedades de um contrato
Listar contratos	Cobrança de contratos	Obter uma lista de todos os contratos configurados
Criar contrato	Contract	Criar um novo contrato
Atualizar contrato	Contract	Atualizar contrato

Obter contrato

Pedido HTTP

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

Substitua o :authorityId e :contractId pelo valor correto da autoridade e do contrato.

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

Exemplo de mensagem:

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
}

A resposta contém as seguintes propriedades

Tipo de contrato

Propriedade	Type	Description
`Id`	string	ID do contrato
`name`	string	O nome amigável deste contrato
`status`	string	Sempre `Enabled`
`manifestUrl`	string	URL do contrato utilizado no pedido de emissão
`issueNotificationEnabled`	boolean	definido como true se os utilizadores forem notificados de que este VC está pronto para ser emitido
`issueNotificationAllowedToGroupOids`	matriz de cadeias de caracteres groupId	matriz de IDs de grupo para a qual esta credencial será oferecida
`availableInVcDirectory`	boolean	Este contrato está publicado na Rede de Credenciais Verificáveis?
regras	regrasModelo	definição de regras
Ecrãs	matriz displayModel	definições de exibição
`allowOverrideValidityIntervalOnIssuance`	boolean	Se a chamada da API createIssuanceRequest tiver permissão para substituir a expiração da credencial. Isso só é válido para fluxos idTokenHint .

regrasTipo de modelo

Propriedade	Type	Description
`attestations`	atestados	descrevendo entradas suportadas para as regras
`validityInterval`	Número	Esse valor mostra a vida útil da credencial
`vc`	Matriz vcType	Tipos para este contrato
`customStatusEndpoint`	[customStatusEndpoint] (tipo #customstatusendpoint) (facultativo)	ponto de extremidade de status a ser incluído na credencial verificável para este contrato

Se a propriedade da propriedade customStatusEndpoint não for especificada, o ponto de extremidade de anonymous status será usado.

tipo de atestado

Propriedade	Type	Description
`idTokens`	idTokenAttestation (matriz) (opcional)	descreve entradas de token de ID
`idTokenHints`	idTokenHintAttestation (matriz) (opcional)	descreve entradas de dica de token de ID
`presentations`	verifiablePresentationAttestation (matriz) (opcional)	descreve entradas de apresentações verificáveis
`selfIssued`	selfIssuedAttestation (matriz) (opcional)	descreve entradas auto-emitidas
`accessTokens`	accessTokenAttestation (matriz) (opcional)	descreve entradas de token de acesso

Tipo idTokenAttestation

Propriedade	Type	Description
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`configuration`	string (url)	Local do documento de configuração do provedor de identidade
`clientId`	string	ID do cliente a ser usado ao obter o token de ID
`redirectUri`	string	redirecionar uri para usar ao obter o token de ID DEVE SER vcclient://openid/
`scope`	string	lista delimitada por espaço de escopos a serem usados ao obter o token de ID
`required`	Booleano (falso padrão)	indicando se este atestado é ou não exigido

Tipo idTokenHintAttestation

Propriedade	Type	Description
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`required`	Booleano (falso padrão)	indicando se este atestado é ou não exigido
`trustedIssuers`	string (matriz)	uma lista de DIDs autorizados a emitir a credencial verificável para este contrato

verificablePresentationTipo de atestado

Propriedade	Type	Description
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`credentialType`	string (opcional)	Tipo de credencial necessária da entrada
`required`	Booleano (falso padrão)	indicando se este atestado é ou não exigido
`trustedIssuers`	string (matriz)	uma lista de DIDs autorizados a emitir a credencial verificável para este contrato

selfIssuedAttestation type

Propriedade	Type	Description
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`required`	Booleano (falso padrão)	indicando se este atestado é ou não exigido

tipo accessTokenAttestation

Propriedade	Type	Description
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`required`	Booleano (falso padrão)	indicando se este atestado é ou não exigido

Os valores suportados inputClaim para a mappings propriedade são: givenName, displayName, , preferredLanguage, userPrincipalName, surname, mail, jobTitlephoto.

tipo claimMapping

Propriedade	Type	Description
`inputClaim`	string	O nome da declaração a ser usada a partir da entrada
`outputClaim`	string	o nome da declaração na credencial verificável
`indexed`	Booleano (falso padrão)	indicando se o valor desta reivindicação é utilizado para pesquisar; apenas um objeto clientMapping pode ser indexado para um determinado contrato
`required`	Booleano (falso padrão)	indicando se esse mapeamento é necessário ou não
`type`	string (opcional)	Tipo de sinistro

tipo customStatusEndpoint

Propriedade	Type	Description
`url`	string (url)	A URL do ponto de extremidade de status personalizado
`type`	string	o tipo de parâmetro de avaliação

exemplo:

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

displayTipo de modelo

Propriedade	Type	Description
`locale`	string	A localidade desta exibição
`credential`	displayCredential	As propriedades de exibição da credencial verificável
`consent`	displayConsentimento	dados suplementares quando a credencial verificável é emitida
`claims`	matriz displayClaims	rótulos para as declarações incluídas na credencial verificável

displayTipo de credencial

Propriedade	Type	Description
`title`	string	Título da credencial
`issuedBy`	string	O nome do emissor da credencial
`backgroundColor`	número (hex)	Cor de plano de fundo da credencial no HEX, por exemplo, #FFAABB
`textColor`	número (hex)	Cor do texto da credencial no HEX, por exemplo, #FFAABB
`description`	string	texto suplementar exibido ao lado de cada credencial
`logo`	displayCredentialLogo	o logotipo a ser usado para a credencial

tipo displayCredentialLogo

Propriedade	Type	Description
`uri`	string (uri)	uri do logótipo. Se este for um URL, deve ser acessível através da Internet pública anonimamente.
`description`	string	a descrição do logótipo

displayTipo de consentimento

Propriedade	Type	Description
`title`	string	Título do consentimento
`instructions`	string	texto suplementar a ser usado ao exibir o consentimento

tipo displayClaims

Propriedade	Type	Description
`label`	string	o rótulo da reivindicação em exibição
`claim`	string	o nome da alegação a que o rótulo se aplica
`type`	string	o tipo de crédito
`description`	string (opcional)	a descrição do crédito

exemplo:

{
  "displays": [
        {
            "locale": "en-US",
            "card": {
                "backgroundColor": "#FFA500",
                "description": "ThisisyourBankofWoodgroveIdentity",
                "issuedBy": "BankofWoodgrove",
                "textColor": "#FFFF00",
                "title": "BankofWoodgroveIdentity",
                "logo": {
                    "description": "Defaultbankofwoodgrovelogo",
                    "uri": "https://didcustomerplayground.z13.web.core.windows.net/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"
                }
            ]
        }
    ]
}

Listar contratos

Essa API lista todos os contratos configurados no locatário atual para a autoridade especificada.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

Exemplo de mensagem:

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

Criar contrato

Ao criar um contrato, o nome tem de ser exclusivo no inquilino. No caso de ter criado várias autoridades, o nome do contrato tem de ser único em todas as autoridades. O nome do contrato fará parte do URL do contrato, que é usado nas solicitações de emissão.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Pedido de exemplo

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

Mensagem de resposta

Exemplo de mensagem:

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

Atualizar contrato

Esta API permite que você atualize o contrato.

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

Exemplo de pedido:

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

Mensagem de resposta

Exemplo de mensagem:

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
}

Credenciais

Este ponto de extremidade permite pesquisar credenciais verificáveis emitidas, verificar o status de revogação e revogar credenciais.

Métodos

Métodos	Tipo de Retorno	Description
Obter credencial	Credencial	Ler propriedades de uma credencial
Pesquisar credenciais	Coleção de credenciais	Pesquisar uma lista de credenciais com um valor de declaração específico
Revogar credencial		Revogar credencial específica

Obter credencial

Essa API permite que você recupere uma credencial específica e verifique o status para ver se ela foi revogada ou não.

Solicitação HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Mensagem de resposta

Mensagem de exemplo

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

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

Pesquisar credenciais

Você pode pesquisar credenciais verificáveis com declarações de índice específicas. Como apenas um hash é armazenado, você precisa procurar o valor calculado específico. O algoritmo que você precisa usar é: Base64Encode(SHA256(contractid + claim value)) Um exemplo em C# tem esta aparência:

  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 );
  }

A solicitação a seguir mostra como adicionar o valor calculado ao parâmetro de filtro da solicitação. Neste momento, apenas o formato filter=indexclaimhash eq é suportado.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

Mensagem de exemplo

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

Revogar credencial

Essa API permite que você revogue uma credencial específica, depois de pesquisar a credencial usando a API de pesquisa, a credencial pode ser revogada especificando a ID de credencial específica.

Pedido HTTP

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

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo do pedido para este método.

Mensagem de resposta

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

Optar por não participar

Esse método removerá completamente todas as instâncias do serviço de credenciais verificáveis neste locatário. Ele remove todos os contratos configurados. Todas as credenciais verificáveis emitidas não podem ser verificadas para revogação. Esta ação não pode ser anulada.

Aviso

Esta ação não pode ser desfeita e invalidará todas as credenciais verificáveis emitidas e os contratos criados.

Solicitação HTTP

POST /v1.0/verifiableCredentials/optout

Cabeçalhos do pedido

Cabeçalho	Valor
Autorização	Portador (token). Necessário
Tipo de Conteúdo	application/json

Corpo do pedido

Não forneça um corpo de solicitação para este método

Mensagem de resposta

Exemplo de mensagem de resposta

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

OK

Observação

Nota

Se você não tiver permissões de exclusão no Cofre da Chave, retornaremos uma mensagem de erro e ainda assim desativaremos

Partilhar via

API de administração de credenciais verificáveis

URL Base

Autenticação

Fichas de utilizador ao portador

Tokens de portador de aplicativo

Integração

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de retorno

Autoridades

Métodos

Obtenha autoridade

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Tipo de autoridade

didModel tipo

Web

tipo keyVaultMetadata

Listar autoridades

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Criar autoridade

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Observações

Autoridade de atualização

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Suprimir autoridade

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Configuração DID bem conhecida

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Observações

Gerar documento DID

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Observação

Validar configuração DID bem conhecida

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Girar a chave de assinatura

Pedido HTTP

Cabeçalhos do pedido

Corpo do Pedido

Mensagem de resposta

Sincronizar com documento DID

Pedido HTTP

Cabeçalhos do pedido

Corpo do Pedido

Mensagem de resposta

Contratos

Métodos

Obter contrato

Pedido HTTP

Cabeçalhos do pedido

Corpo do pedido

Mensagem de resposta

Tipo de contrato

regrasTipo de modelo

tipo de atestado

Tipo idTokenAttestation