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
inputClaimcom suporte para a propriedademappingssão:givenName,displayName,preferredLanguage,userPrincipalName,surname,jobTitleephoto.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de