Compartilhar via


API de administrador de credenciais verificáveis

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

Próximas etapas