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
A API Admin é um servidor sobre HTTPS. Todos os URLs referenciados na documentação têm a seguinte base: https://verifiedid.did.msidentity.com
.
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.
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.
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.
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.
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çalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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.
Esse ponto de extremidade pode ser usado para criar ou atualizar uma instância de serviço de Credenciais Verificáveis.
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 |
Recupere as propriedades de uma autoridade configurada ou instância de serviço de credenciais verificável.
GET /v1.0/verifiableCredentials/authorities/:authorityId
Substitua o :authorityId
pelo valor de uma das autoridades configuradas.
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo de solicitação para este método
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.
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 |
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 |
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 |
Obtenha todas as autoridades configuradas ou serviços de credenciais verificáveis para este locatário
GET /v1.0/verifiableCredentials/authorities
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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/"
}
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
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/"
}
}
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/"
}
}
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.
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.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Substitua o valor de pelo valor do ID da :authorityId
autoridade que você deseja atualizar.
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
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"
}
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.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Substitua o valor de pelo valor do ID da :authorityId
autoridade que você deseja excluir.
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Sem corpo de solicitação
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"
}
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Você precisa especificar um dos domínios em linkedDomains da autoridade especificada.
{
"domainUrl":"https://atest/"
}
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/"
}
}
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>..."
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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"
]
}
Requer que o chamador tenha as permissões KEY List no cofre de chaves de destino.
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
HTTP/1.1 204 No Content
Content-type: application/json
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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
}
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 | 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 |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Substitua o :authorityId
e :contractId
pelo valor correto da autoridade e do contrato.
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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
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 . |
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.
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 |
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 |
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 |
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 |
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 |
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 amappings
propriedade são:givenName
,displayName
, ,preferredLanguage
,userPrincipalName
,surname
,jobTitle
photo
.
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 |
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"
]
}
}
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 |
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 |
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 |
Propriedade | Type | Description |
---|---|---|
title |
string | Título do consentimento |
instructions |
string | texto suplementar a ser usado ao exibir o consentimento |
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"
}
]
}
]
}
Essa API lista todos os contratos configurados no locatário atual para a autoridade especificada.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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}]
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Pedido de exemplo
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
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://..."
}
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
}
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
}
Este ponto de extremidade permite pesquisar credenciais verificáveis emitidas, verificar o status de revogação e revogar credenciais.
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 |
Essa API permite que você recupere uma credencial específica e verifique o status para ver se ela foi revogada ou não.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
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"
}
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.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
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"
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo do pedido para este método.
HTTP/1.1 204 No Content
Content-type: application/json
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.
POST /v1.0/verifiableCredentials/optout
Cabeçalho | Valor |
---|---|
Autorização | Portador (token). Necessário |
Tipo de Conteúdo | application/json |
Não forneça um corpo de solicitação para este método
Exemplo de mensagem de resposta
HTTP/1.1 200 OK
Content-type: application/json
OK
Nota
Se você não tiver permissões de exclusão no Cofre da Chave, retornaremos uma mensagem de erro e ainda assim desativaremos