API de administrador de credenciais verificáveis

Artigo
01/11/2024

A API de Administrador da ID Verificada do Microsoft Entra permite que você gerencie todos os aspectos do serviço de Credencial Verificável. Ele oferece uma forma de configurar um novo serviço, gerenciar e criar contratos de credencial verificável, revogar credenciais verificáveis e recusar completamente o serviço também.

A API é para 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 do Administrador é servidor sobre HTTPS. Todas as URLs referenciadas na documentação têm a seguinte base: https://verifiedid.did.msidentity.com.

Autenticação

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

Tokens de portador do usuário

O registro do aplicativo precisa ter a Permissão da API para Verifiable Credentials Service Admin e, depois, 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 de administrador da política de autenticação. Um usuário com a função de leitor global pode executar chamadas de API somente leitura.

Tokens de portador do aplicativo

O serviço Verifiable Credentials Service Admin dá suporte às seguintes permissões de aplicativo.

Permissão	Descrição
VerifiableCredential.Authority.ReadWrite	Permissão para ler/gravar objetos de autoridade
VerifiableCredential.Contract.ReadWrite	Permissão para ler/gravar objetos de contrato
VerifiableCredential.Credential.Search	Permissão para pesquisar uma credencial a ser revogada
VerifiableCredential.Credential.Revoke	Permissão para revogar uma credencial emitida anteriormente
VerifiableCredential.Network.Read	Permissão para ler entradas da Rede de ID Verificada

O registro do aplicativo precisa ter a permissão de API para Verifiable Credentials Service Admin e as permissões necessárias 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 permissão VerifiableCredential.Authority.ReadWrite. Em segundo lugar, o aplicativo precisa ter permissão Create Key nas políticas de acesso do Key Vaults. Se o aplicativo apenas ler/gravar autoridades existentes, ele não precisará da permissão do Key Vault.

Integração

Essa API é para ajudar a criar um ambiente para que novas autoridades possam ser configuradas. Isso também pode ser disparado 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 ambiente novo apenas com a API.

Solicitação HTTP

POST /v1.0/verifiableCredentials/onboard

Use esse ponto de extremidade para concluir o provisionamento do serviço de Credencial Verificável no seu locatário. O sistema criará o restante das entidades de serviço se elas ainda não estiverem provisionadas.

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação 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"
}

Chamadas repetidas a essa API resultam 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 credencial verificável.

Métodos

Métodos	Tipo de retorno	Descrição
Obter autoridade	Authority	Ler propriedades de uma autoridade
List Authority	Matriz de autoridade	Obter uma lista de todas as Autoridades/serviços de credencial verificável configurados
Create Authority	Authority	Criar uma autoridade
Atualizar autoridade	Authority	Atualizar autoridade
Excluir autoridade	Autoridade	Excluir autoridade
Gerar configuração de DID bem conhecida
Gerar documento DID
Validar a configuração DID bem conhecida
Girar chave de assinatura	Autoridade	Girar chave de assinatura
Sincronizar com o Documento DID	Autoridade	Sincronizar o documento DID com a nova chave de assinatura

Obter autoridade

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

Solicitação HTTP

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

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da 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 propriedades a seguir.

Tipo de autoridade

Propriedade	Type	Descrição
`Id`	string	Uma ID exclusiva gerada automaticamente, que pode ser usada para recuperar ou atualizar a instância específica do serviço de credencial verificável
`name`	string	O nome amigável dessa instância do serviço de credencial verificável
`status`	string	status do serviço, esse valor sempre será `enabled`
didModel	didModel	Informações sobre o DID e as chaves
keyVaultMetadata	keyVaultMeta data	Informações sobre o Key Vault usado

didModel type

Web

Propriedade	Type	Descrição
`did`	string	O DID para essa instância de serviço de credencial verificável
`signingKeys`	Matriz de cadeia de caracteres	URL para a chave de assinatura
`linkedDomainUrls`	Matriz de cadeia de caracteres	Domínios vinculados a esse DID, esperando uma entrada
didModel	didModel	Informações sobre o DID e as chaves
`didDocumentStatus`	string	status do DID, o valor é sempre `published` para esse método

keyVaultMetadata type

Propriedade	Type	Descrição
`subscriptionId`	string	A assinatura do Azure em que o Key Vault reside
`resourceGroup`	string	nome do grupo de recursos desse Key Vault
`resourceName`	string	Nome do Key Vault
`resourceUrl`	string	URL para este Key Vault

Listar autoridades

Obter todas as autoridades configuradas ou serviços de credencial verificável para esse locatário

Solicitação HTTP

GET /v1.0/verifiableCredentials/authorities

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação 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

Essa chamada cria uma chave privada, uma chave de recuperação e uma chave de atualização novas, armazena essas chaves no Azure Key Vault especificado, define as permissões desse Key Vault para o serviço de credencial verificável, cria um novo DID com o Documento DID.

Solicitação HTTP

POST /v1.0/verifiableCredentials/authorities

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

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

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

Mensagem de exemplo:

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

Mensagem de exemplo 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/"
    }
}

Comentários

Você pode criar várias autoridades com seus DID e suas chaves privadas. Eles não estarão visíveis na interface do usuário do portal do Azure. No momento, só damos suporte a ter uma autoridade. Não testamos totalmente todos os cenários com várias autoridades criadas. Se você estiver experimentando isso, conte-nos da sua experiência.

Atualizar autoridade

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

Solicitação HTTP

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

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

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

Propriedade	Type	Descrição
`name`	string	O nome de exibição dessa instância do serviço

Mensagem de exemplo

{
  "name":"ExampleIssuerName"
}

Excluir autoridade

Esse método pode ser usado para excluir uma autoridade. No momento, apenas did:ion autoridades podem ser excluídas. Quando você exclui uma autoridade, todas as credenciais de ID verificadas emitidas se tornam inválidas e não podem mais ser verificadas, pois a autoridade emissora desaparece.

Solicitação HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Sem corpo da solicitação

Mensagem de resposta

Mensagem de resposta de exemplo:

Resposta bem-sucedida à exclusão de autoridade.

HTTP/1.1 200 OK

Se a exclusão de autoridade foi bem-sucedida, mas a limpeza das chaves do Azure Key Vault falhou, você obterá 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 de DID conhecida

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

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

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

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

Mensagem de resposta

Mensagem de resposta de exemplo:

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 esse resultado com o nome do arquivo did-configuration.json e carregue esse arquivo na pasta e no 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/"
  }
}

Comentários

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

Essa chamada gera o Documento DID usado para identificadores DID:WEB. Depois de gerar esse documento DID, o administrador precisa colocar o arquivo no local https://domain/.well-known/did.json.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação 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"
    ]
}

Comentário

Requer que o chamador tenha as permissões de Lista de CHAVES no cofre de chaves de destino.

Validar a configuração DID bem conhecida

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

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

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

Girar chave de assinatura

As troca das chaves de assinatura cria uma nova chave privada para a autoridade did:web. O documento DID deve ser registrado novamente para que reflita a atualização. Após a conclusão desse processo, o synchronizeWithDidDocument indica ao sistema que deve começar a usar a nova chave para assinatura.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

O didDocumentStatus 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 o documento DID

Depois de trocar a chave de assinatura, o documento DID deve ser registrado novamente para que reflita a atualização. Após a conclusão desse processo, o synchronizeWithDidDocument indica ao sistema que deve começar a usar a nova chave para assinatura.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

O didDocumentStatus 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 que você crie contratos e atualize os contratos existentes. Os contratos consistem em duas partes representadas por duas definições JSON. Informações sobre como elaborar 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, a cor da tela de fundo, o logotipo e o título da credencial verificável. Esse arquivo também contém as declarações que precisam ser armazenadas na credencial verificável.
A definição de regras contém as informações sobre como reunir e coletar atestados como declarações autoatestadas, 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	Descrição
Obter contrato	Contrato	Ler propriedades de um contrato
Listar contratos	Coleção de contratos	Obter uma lista de todos os contratos configurados
Criar contrato	Contrato	Criar um contrato
Atualizar contrato	Contrato	Atualizar contrato

Obter contrato

Solicitação HTTP

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

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

mensagem de exemplo:

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	Descrição
`Id`	string	ID do Contrato
`name`	string	O nome amigável deste contrato
`status`	string	Sempre `Enabled`
`manifestUrl`	string	URL para o contrato usado na solicitação de emissão
`issueNotificationEnabled`	booleano	definido como true se os usuários forem notificados de que esta VC está pronta para ser emitida
`issueNotificationAllowedToGroupOids`	matriz de cadeias de caracteres groupId	matriz das IDs de grupo para a qual essa credencial será oferecida
`availableInVcDirectory`	booleano	Este contrato é publicado na Rede de Credenciais Verificáveis
rules	rulesModel	definição de regras
displays	displayModel array	exibir definições
`allowOverrideValidityIntervalOnIssuance`	boolean	Se a chamada à API createIssuanceRequest tem permissão para substituir o prazo de validade da credencial. Isso só é válido para fluxos idTokenHint.

tipo rulesModel

Propriedade	Type	Descrição
`attestations`	attestations	descrevendo entradas com suporte para as regras
`validityInterval`	número	esse valor mostra o tempo de vida da credencial
`vc`	matriz vcType	tipos para este contrato
`customStatusEndpoint`	[customStatusEndpoint] (#customstatusendpoint-type) (opcional)	ponto de extremidade de status a ser incluído na credencial verificável para este contrato

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

tipo de atestados

Propriedade	Type	Descrição
`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 as entradas de apresentações verificáveis
`selfIssued`	selfIssuedAttestation (matriz) (opcional)	descreve entradas autoemitidas
`accessTokens`	accessTokenAttestation (matriz) (opcional)	descreve entradas de token de acesso

Tipo de idTokenAttestation

Propriedade	Type	Descrição
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`configuration`	string (url)	localização do documento de configuração do provedor de identidade
`clientId`	string	ID do cliente a ser usada ao obter o token de ID
`redirectUri`	string	uri de redirecionamento a ser usado 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 (padrão falso)	indicando se esse atestado é necessário ou não

Tipo de idTokenHintAttestation

Propriedade	Type	Descrição
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`required`	booleano (padrão falso)	indicando se esse atestado é necessário ou não
`trustedIssuers`	cadeia de caracteres (matriz)	uma lista de DIDs permitidos para emitir a credencial verificável para este contrato

tipo de verifiablePresentationAttestation

Propriedade	Type	Descrição
`mapping`	claimMapping (opcional)	regras para mapear declarações de entrada em declarações de saída na credencial verificável
`credentialType`	cadeia de caracteres (opcional)	tipo de credencial necessário da entrada
`required`	booleano (padrão falso)	indicando se esse atestado é necessário ou não
`trustedIssuers`	cadeia de caracteres (matriz)	uma lista de DIDs permitidos para emitir a credencial verificável para este contrato

tipo de selfIssuedAttestation

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

accessTokenAttestation type

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

Os valores de inputClaim com suporte para a propriedade mappings são: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, jobTitle e photo.

tipo de claimMapping

Propriedade	Type	Descrição
`inputClaim`	string	o nome da declaração a ser usada da entrada
`outputClaim`	string	o nome da declaração na credencial verificável
`indexed`	booleano (padrão falso)	indicando se o valor dessa declaração é usado para pesquisa; apenas um objeto clientMapping pode ser indexável para um determinado contrato
`required`	booleano (padrão falso)	indicando se esse mapeamento é necessário ou não
`type`	cadeia de caracteres (opcional)	tipo de declaração

customStatusEndpoint type

Propriedade	Type	Descrição
`url`	string (url)	a URL do ponto de extremidade de status personalizado
`type`	string	o tipo do ponto de extremidade

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

Tipo de displayModel

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

tipo de displayCredential

Propriedade	Type	Descrição
`title`	string	título da credencial
`issuedBy`	string	o nome do emissor da credencial
`backgroundColor`	número (hexa)	cor da tela de fundo da credencial no formato hexa, por exemplo, #FFAABB
`textColor`	número (hexa)	cor do texto da credencial no formato hexa, por exemplo, #FFAABB
`description`	string	texto complementar exibido junto com cada credencial
`logo`	displayCredentialLogo	o logotipo a ser usado para a credencial

tipo de displayCredentialLogo

Propriedade	Type	Descrição
`uri`	cadeia de caracteres (uri)	URI do logotipo. Se essa for uma URL, ela precisará ser acessível pela Internet pública anonimamente.
`description`	string	a descrição do logotipo

tipo de displayConsent

Propriedade	Type	Descrição
`title`	string	título do consentimento
`instructions`	string	texto complementar a ser usado ao exibir consentimento

tipo de displayClaims

Propriedade	Type	Descrição
`label`	string	o rótulo da declaração em exibição
`claim`	string	o nome da declaração à qual o rótulo se aplica
`type`	string	o tipo da declaração
`description`	cadeia de caracteres (opcional)	a descrição da declaração

Exemplo:

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

Listar contratos

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

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

mensagem de exemplo:

{
    "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 deve ser exclusivo no locatário. Caso você tenha criado várias autoridades, o nome do contrato deve ser exclusivo em todas as autoridades. O nome do contrato fará parte da URL do contrato e será usado nas solicitações de emissão.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Solicitação de exemplo

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

Mensagem de resposta

Mensagem de exemplo:

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

Essa API permite que você atualize o contrato.

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

Solicitação de exemplo:

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

Mensagem de resposta

Mensagem de exemplo:

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

Esse ponto de extremidade permite que você pesquise credenciais verificáveis emitidas, verifique o status de revogação e revogue as credenciais.

Métodos

Métodos	Tipo de retorno	Descrição
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 da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	aplicativo/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 pesquisar o valor calculado específico. O algoritmo que você precisa usar é: Base64Encode(SHA256(contractid + valor de declaração)) 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 somente o formato filter=indexclaimhash eq tem suporte.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação 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.

Solicitação HTTP

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

Cabeçalhos da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

Não forneça o corpo da solicitação para este método.

Mensagem de resposta

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

Recusa

Esse método removerá completamente todas as instâncias do serviço de credencial verificável neste locatário. Ele remove todos os contratos configurados. Não é possível verificar todas as credenciais verificáveis emitidas quanto à revogação. Essa ação não pode ser desfeita.

Aviso

Essa 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 da solicitação

Cabeçalho	Valor
Autorização	Token (de portador). Obrigatório
Tipo de conteúdo	application/json

Corpo da solicitação

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

Mensagem de resposta

Mensagem de resposta de exemplo

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

OK

Comentário

Observação

Se você não tiver permissões de exclusão no Key Vault retornaremos uma mensagem de erro e ainda recusaremos

Compartilhar via

API de administrador de credenciais verificáveis

URL base

Autenticação

Tokens de portador do usuário

Tokens de portador do aplicativo

Integração

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de retorno

Autoridades

Métodos

Obter autoridade

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Tipo de autoridade

didModel type

Web

keyVaultMetadata type

Listar autoridades

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Criar autoridade

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Comentários

Atualizar autoridade

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Excluir autoridade

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Configuração de DID conhecida

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Comentários

Gerar documento DID

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Comentário

Validar a configuração DID bem conhecida

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Girar chave de assinatura

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Sincronizar com o documento DID

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Contratos

Métodos

Obter contrato

Solicitação HTTP

Cabeçalhos da solicitação

Corpo da solicitação

Mensagem de resposta

Tipo de contrato

tipo rulesModel

tipo de atestados

Tipo de idTokenAttestation