Ler em inglês

Partilhar via


API de administração de credenciais verificáveis

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

Próximos passos