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
A API do Administrador é servidor sobre HTTPS. Todas as URLs referenciadas na documentação têm a seguinte base: https://verifiedid.did.msidentity.com
.
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.
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 a função de administrador de política de autenticação. Um usuário com a função de leitor global pode executar chamadas de API somente leitura.
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.
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.
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çalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação 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"
}
Chamadas repetidas a essa API resultam exatamente na mesma mensagem de retorno.
Esse ponto de extremidade pode ser usado para criar ou atualizar uma instância de serviço de credencial verificável.
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 |
Recupere as propriedades de uma autoridade configurada ou instância de serviço de credencial verificável.
GET /v1.0/verifiableCredentials/authorities/:authorityId
Substitua o :authorityId
pelo valor de uma das autoridades configuradas.
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da 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 propriedades a seguir.
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 |
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 |
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 |
Obter todas as autoridades configuradas ou serviços de credencial verificável para esse locatário
GET /v1.0/verifiableCredentials/authorities
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação 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/"
}
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
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/"
}
}
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/"
}
}
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.
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.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Substitua o valor de :authorityId
pelo valor da ID de autoridade que você deseja atualizar.
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
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"
}
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.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Substitua o valor de :authorityId
pelo valor da ID de autoridade que você deseja excluir.
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Sem corpo da solicitação
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"
}
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Você precisa especificar um dos domínios nos linkedDomains da autoridade especificada.
{
"domainUrl":"https://atest/"
}
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/"
}
}
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>..."
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação 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 de Lista de CHAVES no cofre de chaves de destino.
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método.
HTTP/1.1 204 No Content
Content-type: application/json
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método.
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
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método.
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
}
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 | 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 |
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 | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método.
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
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. |
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.
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 |
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 |
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 |
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 |
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 |
Propriedade | Type | Descrição |
---|---|---|
mapping |
claimMapping (opcional) | regras para mapear declarações de entrada em declarações de saída na credencial verificável |
required |
booleano (padrão falso) | indicando se esse atestado é necessário ou não |
Os valores de
inputClaim
com suporte para a propriedademappings
são:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
ephoto
.
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 |
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"
]
}
}
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 |
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 |
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 |
Propriedade | Type | Descrição |
---|---|---|
title |
string | título do consentimento |
instructions |
string | texto complementar a ser usado ao exibir consentimento |
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.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 | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método.
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}]
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Solicitação de exemplo
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
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://..."
}
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 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
}
Esse ponto de extremidade permite que você pesquise credenciais verificáveis emitidas, verifique o status de revogação e revogue as credenciais.
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 |
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 | Token (de portador). Obrigatório |
Tipo de conteúdo | aplicativo/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 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.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação 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 | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação 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 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.
POST /v1.0/verifiableCredentials/optout
Cabeçalho | Valor |
---|---|
Autorização | Token (de portador). Obrigatório |
Tipo de conteúdo | application/json |
Não forneça o corpo da solicitação para este método
Mensagem de resposta de exemplo
HTTP/1.1 200 OK
Content-type: application/json
OK
Observação
Se você não tiver permissões de exclusão no Key Vault retornaremos uma mensagem de erro e ainda recusaremos