Versão 1.0.0-alpha.1mais recente
Capítulo 2.13
Licenças
O que contém um ficheiro de licença do Nexus, como a instalação o verifica offline, os seis estados em que se pode encontrar e como solicitar, importar, renovar e retirar uma licença.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

A Harrow Port Authority executa o Nexus Enterprise no seu próprio cluster Kubernetes em harrow.example, sem rota do cluster para a internet. Todos os anos, Aoife Brennan, diretora de TI, renova o contrato, e Tomás Reilly, o engenheiro de plataforma, transporta um pequeno ficheiro JSON através do isolamento de rede e importa-o. Nada reinicia e a página da licença apresenta uma nova data de fim.
Este capítulo é sobre esse ficheiro. Em suma, uma licença é um documento JSON assinado e vinculado a uma instalação. A instalação verifica-o por si mesma, com chaves públicas integradas na imagem, e não faz qualquer chamada de rede para o efeito. Uma licença nunca é um valor Helm e nunca é um ficheiro montado. Importa-a através da consola, de nexusctl ou da interface de programação de aplicações (API), e em mais nenhum local.
O documento de licença
Uma licença é um objeto JSON no formato nexus-licence/v1. Aqui está a de Harrow, com os dois valores de assinatura abreviados.
{
"format": "nexus-licence/v1",
"licence_id": "8c1e4f2a-6b0d-4e7a-9f31-2d5c7a9e0b14",
"issued_at": "2026-12-14T10:20:00Z",
"type": "alpha",
"channel": "alpha",
"licensee": { "name": "Harrow Port Authority", "customer_id": "harrow-port-authority" },
"scope": {
"deployment": { "installation_id": "4b7d2e90-1c5a-4f8e-a3d6-7e0b9c2f5a18" },
"tenants": []
},
"edition": "enterprise",
"grants": [
{ "feature_group": "enterprise-base", "scope": "deployment" },
{ "feature_group": "map-and-geoai", "scope": "deployment" }
],
"add_ons": ["mail"],
"domain_packs": ["logistics-and-maritime"],
"metric": { "kind": "per-environment", "quantity": 1 },
"term": { "starts_on": "2027-01-01", "ends_on": "2027-12-31", "warn_days": 30, "grace_days": 30 },
"matrix": { "version": 1, "sha256": "<64 lower-case hexadecimal characters>" },
"signatures": {
"ed25519": { "key_id": "licence-ed-2026a", "sig": "<86 characters>" },
"p256": { "key_id": "licence-p256-2026a", "sig": "<86 characters>" }
}
}Todos os campos são obrigatórios e todos os objetos no documento são fechados. Um membro que o formato não liste é recusado, pelo que nada pode ser incluído fora da assinatura.
| Campo | O que contém |
|---|---|
format |
Exatamente nexus-licence/v1. Qualquer outro valor, incluindo uma versão posterior, é recusado. |
licence_id |
Um UUID (identificador único universal) em minúsculas. Uma instalação importa cada ID de licença uma única vez. |
issued_at |
O instante em que a Adverant a emitiu, como YYYY-MM-DDThh:mm:ssZ. |
type |
alpha, evaluation ou commercial. |
channel |
O canal de lançamento para o qual foi emitida, tal como alpha. Assinado e transportado; a verificação não depende dele. |
licensee.name |
1 a 200 caracteres, assinados exatamente como escritos. Brennan e Brennán são dois nomes diferentes com duas assinaturas diferentes. |
licensee.customer_id |
O seu ID de cliente na Adverant: minúsculas, dígitos, ., _ e -. |
scope.deployment.installation_id |
A identidade da instalação, gerada pelo respetivo serviço de chaves na primeira instalação. |
scope.tenants |
IDs de organização, até 1.000. Vazio, a menos que alguma concessão seja de âmbito de inquilino (tenant-scoped). |
edition |
enterprise ou team. Uma licença Enterprise concede sempre enterprise-base. |
grants |
1 a 500 pares {feature_group, scope}, cada grupo nomeado uma vez. |
add_ons |
IDs de suplementos (add-ons) da matriz de edições, até 100. Pode estar vazio. |
domain_packs |
IDs de pacotes de domínio da matriz de edições, até 100. Pode estar vazio. |
metric |
kind é per-environment, per-core ou named-seat; quantity é um número inteiro a partir de 1. |
term |
starts_on e ends_on são datas; warn_days e grace_days são números inteiros de 0 a 365. |
matrix |
A versão da matriz de edições para a qual os grupos foram escritos e o SHA-256 desse ficheiro de matriz, mantidos para auditoria. |
signatures |
Duas assinaturas, ed25519 e p256. O único campo que não é assinado. |
As datas são datas de calendário em UTC, e o dia tem de existir: 2028-02-29 é aceite e 2027-02-29 é recusado.
Duas assinaturas, ambas obrigatórias
A Adverant assina cada licença com duas chaves independentes. Uma assinatura é Ed25519. A outra é ECDSA (Elliptic Curve Digital Signature Algorithm) na curva P-256 do NIST (o National Institute of Standards and Technology dos EUA), que os compradores que necessitam de algoritmos federais dos EUA solicitam. Ambas são efetuadas sobre os mesmos bytes e ambas têm de ser validadas. Um documento com uma metade em falta, ou com qualquer uma das metades incorreta, equivale a não ter licença alguma.
Os bytes assinados são a forma canónica RFC 8785 do documento sem signatures, pelo que os espaços em branco e a ordem dos membros no seu ficheiro não fazem diferença. Um único carácter alterado no nome do licenciado, nas datas ou numa concessão constitui um documento diferente, e falha.
As chaves públicas que a verificação utiliza residem num ficheiro de raízes de confiança (trust-roots) integrado em cada imagem durante a compilação da versão. Nenhuma variável de ambiente, flag ou montagem indica outro ficheiro. Quando a Adverant substitui uma chave de assinatura, a chave antiga assina a nova e a versão assinada seguinte transporta a nova chave. Uma licença assinada com uma nova chave é validada numa versão que a transporte, pelo que, após uma alteração de chave, poderá precisar de atualizar antes de importar (consulte o capítulo 2.17, Resolução de problemas).
Tipos, edições e como uma licença é contabilizada
O type indica de que tipo de acordo provém a licença:
alpha: uma licença para o canal de lançamento alpha, que é o tipo que Harrow detém.evaluation: uma avaliação alojada localmente do Enterprise. É executada durante, no máximo, 30 dias, para, no máximo, 5 pessoas nomeadas (métricanamed-seat), comgrace_daysdefinido como 0. O formato recusa uma avaliação com qualquer período de tolerância.commercial: uma licença contratada.
O metric regista como a licença é contabilizada: per-environment (o cluster de produção de Harrow é um ambiente), per-core ou named-seat. A Adverant apresenta o preço; a licença transporta apenas a medida e a quantidade.
A edition da licença é enterprise para todas as instalações Enterprise. O formato também aceita team, onde a licença concede o grupo team e nunca enterprise-base.
Grupos de funcionalidades, suplementos e pacotes de domínio
O que uma licença permite que as pessoas utilizem é listado por grupo de funcionalidades, utilizando os IDs da matriz de edições. A licença de Harrow concede enterprise-base (funções personalizadas, aprovações de quatro olhos, retenção longa de auditoria, início de sessão da empresa com imposição e sincronização de diretório, unidades de negócio, as páginas de operador e o resto da base Enterprise) e map-and-geoai. Transporta o suplemento mail e o pacote de domínio logistics-and-maritime.
A matriz tem regras sobre o que funciona em conjunto, e o sistema de emissão da Adverant verifica-as antes de uma licença ser assinada. Todos os suplementos e todos os pacotes precisam de enterprise-base. Alguns pacotes precisam de suplementos: o pacote Logistics and maritime precisa de Map and GeoAI, o pacote Insurance e o pacote Capital markets and asset management precisam de Decision rooms and sealed records, e o pacote Legal and professional services precisa de Decision rooms e Mail. Os ecrãs de telemóvel de todos os pacotes também precisam do suplemento Mobile apps.
Cada concessão tem um âmbito:
deployment: o grupo aplica-se a toda a instalação, para todas as organizações nela existentes.tenant: o grupo aplica-se apenas às organizações listadas emscope.tenants. Uma licença com uma concessão de âmbito de inquilino tem de listar pelo menos uma organização, e uma lista de organizações sem qualquer concessão de âmbito de inquilino é recusada.
Suponha que a equipa de pilotagem de Harrow operava como uma segunda organização na mesma instalação, e apenas essa organização deveria deter Ideas. A concessão seria { "feature_group": "ideas", "scope": "tenant" }, com o ID da organização de pilotagem em scope.tenants. Se a licença fosse importada antes de essa organização existir, a resposta da importação contabilizá-la-ia em tenants_without_organisation, e a concessão chegaria até ela assim que a organização fosse criada.
Um administrador pode restringir o alcance de um grupo. Apenas uma licença da Adverant adiciona um grupo.
O prazo: aviso e período de tolerância
O term define quatro datas no calendário. De starts_on a ends_on a licença está em vigor. warn_days define com que antecedência começa o aviso, e grace_days durante quanto tempo tudo continua a funcionar após o fim. As licenças que a Adverant emite incluem 30 dias de cada, a menos que o contrato indique o contrário. Uma avaliação tem sempre grace_days 0.
Para a licença de Harrow acima, o calendário funciona da seguinte forma:
| Datas | Estado |
|---|---|
| 1 de janeiro de 2027 a 1 de dezembro de 2027 | VALID |
| 2 de dezembro de 2027 a 31 de dezembro de 2027 | WARN |
| 1 de janeiro de 2028 a 30 de janeiro de 2028 | GRACE |
| A partir de 31 de janeiro de 2028 | RESTRICT |
O último dia do prazo, ends_on, ainda é um dia WARN. O dia seguinte é GRACE, ou RESTRICT quando não há período de tolerância.
Os seis estados
Sempre que a licença é lida, a instalação recalcula o seu estado a partir do documento e da data atual. Nada é guardado em cache após a mudança de dia, pelo que uma expiração ocorre a tempo sem necessidade de uma tarefa agendada.
| Estado | Quando | O que as pessoas podem fazer |
|---|---|---|
| ABSENT | Nenhuma licença importada, ou o documento foi recusado | A base Community. As áreas Enterprise aparecem como demonstrações (teasers) indicando quem as pode ativar. |
| VALID | starts_on a ends_on menos warn_days |
Todos os grupos concedidos estão autorizados. |
| WARN | Os últimos warn_days dias do prazo |
Autorizado, e os administradores veem uma faixa no produto com a data de fim. |
| GRACE | Após ends_on, durante grace_days dias |
Autorizado, com o aviso LICENCE_IN_GRACE em Today e na página da licença. |
| RESTRICT | Após o período de tolerância | Nenhum trabalho novo pode começar sob um grupo licenciado. O trabalho em execução termina, as leituras e exportações continuam a funcionar e as correções de segurança continuam a chegar. |
| TERMINATE | A Adverant revogou a licença | Os artefactos Enterprise deixam de ser disponibilizados. A base Community e a exportação de dados permanecem. |
Em todos os estados, o trabalho em execução continua a decorrer, as correções de segurança continuam a chegar, as exportações permanecem legíveis e nada é eliminado. Em RESTRICT, uma pessoa que tente iniciar novo trabalho Enterprise vê uma placa de recusa com o código LICENCE_LOCKED e o nome de quem pode renovar.
Como é calculada a data atual
Um relógio pode estar errado e pode ser atrasado de propósito. Por isso, a instalação nunca lê apenas o relógio. A data atual é o mais tardio de dois instantes: o relógio do sistema e um limite mínimo armazenado, que é o instante mais recente que a instalação já viu. O limite mínimo avança em cada importação e em cada leitura de estado, e nunca recua por si só. Atrasar o relógio um mês não traz uma licença expirada de volta para VALID; uma licença RESTRICT permanece RESTRICT.
Quando o relógio apresenta uma hora anterior ao limite mínimo, o estado inclui o aviso LICENCE_CLOCK_BEHIND_FLOOR e é lido no dia do limite mínimo. Se o relógio tiver realmente adiantado (um nó arrancou com a data errada e o limite mínimo foi avançado), peça à Adverant um token de reposição de hora. É um pequeno documento assinado, vinculado ao ID da sua instalação e a um nonce de utilização única, com um instante floor_to. Importa-o através da API com este pedido:
curl --fail-with-body -X POST https://auth.harrow.example/api/v1/installation/licence/time-reset \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
--data-binary @harrow-time-reset.json<access-token> é o token de acesso de um administrador da instalação. Um token é aplicado quando ambas as assinaturas são validadas, o ID da instalação é o seu e o respetivo nonce não foi utilizado. Um token recusado não altera nada, pelo que nunca pode ser utilizado para recusar uma licença válida. Um token cujo nonce já tenha sido utilizado é recusado com LICENCE_CLOCK_BEHIND_FLOOR.
Solicitar uma licença
As licenças são solicitadas e transferidas a partir da sua conta Adverant em https://account.adverant.ai. Quem na sua organização pode reivindicar implementações e transferir licenças é definido na página Organisation and team roles da conta.
A Adverant precisa de saber a que instalação se destina a licença, e existem três formas de o indicar.
Um código de utilização única, para uma instalação com ecrã. A instalação apresenta um código de utilização única e a respetiva impressão digital. Na página Claim a deployment, cola o código e, em seguida, compara a impressão digital grupo a grupo com o que a instalação apresenta. Quando todos os grupos coincidem, reivindica-a para a sua organização e a licença chega à conta.
Uma chave de reivindicação, para um appliance ou um dispositivo de periferia (edge). Estes não têm ecrã para apresentar um código. O número de série e uma chave de reivindicação estão impressos na caixa e na encomenda do fabricante do equipamento. Introduza-os na página Enter a claim key um de cada vez, ou largue o ficheiro de encomenda do fabricante para reivindicar vários de uma só vez. Cada chave é verificada em relação ao registo da Adverant do que lhe foi enviado, e uma chave da encomenda de outra pessoa é recusada.
Um pedido de licença assinado, para uma instalação sem ligação ao exterior. Esta é a via de Harrow. Na instalação, um administrador cria um ficheiro de pedido em This installation, Licence. É uma declaração do tipo licence-request que indica o ID da instalação, assinada com a própria chave Ed25519 da instalação. Tomás transporta-o num suporte aprovado, larga-o na página Offline exchange e transfere o ficheiro de licença que é devolvido. A licença funciona apenas na instalação que efetuou o pedido.
Importar uma licença
Existem três vias de entrada, e todas chegam ao mesmo endpoint no nexus-auth. Apenas um administrador da instalação pode importar: um proprietário ou administrador de toda a organização que detém a instalação, com sessão iniciada na mesma, ou um administrador total da plataforma. Qualquer outra pessoa é recusada antes de o ficheiro ser lido.
Na consola
Numa nova instalação, Import the licence é uma das seis verificações em Six things before anyone signs in. Quando larga o ficheiro na página, a consola verifica-o na instalação, offline, e lista os respetivos grupos de funcionalidades com a forma como cada um está protegido e o prazo.
As importações posteriores são feitas através de This installation, Licence: utilize Import a new licence, ou Import a renewed licence quando a atual tiver terminado. Uma instalação Community que mude para Enterprise utiliza From Community to Enterprise. Essa página lê primeiro a licença e mostra o que será obtido e o que muda, antes de algo acontecer. Nada é obtido até que alguém escolha Fetch and switch on. As partes Enterprise vêm então de registry.adverant.ai com o pull token da instalação, sendo cada uma verificada em relação à chave de lançamento da Adverant, e os grupos são ativados um de cada vez. Depois disso, continua a ser a mesma instalação, com as mesmas pessoas, ficheiros, fluxos de trabalho e canais.
Com o nexusctl
nexusctl licence import harrow-2027.licence.jsonO comando importa o ficheiro inalterado e imprime o estado atual da licença. Adicione --explain para imprimir as operações que executaria sem as executar.
Através da API
curl --fail-with-body -X POST https://auth.harrow.example/api/v1/installation/licence \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
--data-binary @harrow-2027.licence.jsonEnvie o ficheiro exatamente como a Adverant lho entregou. Não o reformate e não o envolva noutro objeto: o corpo é o documento. A rota não aceita query string, e um corpo com mais de 1 MiB é recusado. Um membro de nível superior que indique uma organização ou uma pessoa é recusado com TENANT_NOT_A_PARAMETER ou ACTOR_NOT_A_PARAMETER, porque a licença da instalação pertence à instalação que a organização do token detém.
Uma importação bem-sucedida responde 201. O corpo contém a vista da licença (o seu ID, o seu estado atual, o licenciado, a edição, o prazo, as concessões e os grupos de funcionalidades), quantas organizações a detêm agora e quantos inquilinos listados ainda não têm organização. A licença, o respetivo resumo SHA-256 e as linhas de registo (ledger) para cada organização são escritos numa única transação, e a importação é registada no registo de auditoria.
Duas rotas de leitura acompanham-na:
GET /api/v1/installation/licence/stateresponde com o estado, recalculado em cada leitura. Um administrador obtém a vista completa. Qualquer outro membro de uma organização na instalação obtém apenas o aviso: o estado, o código de aviso (LICENCE_ENDS_SOON,LICENCE_IN_GRACEouLICENCE_CLOCK_BEHIND_FLOOR) e as datas que o aviso indica. Um membro nunca vê o licenciado, o prazo ou os grupos, porque esses dados pertencem ao proprietário da instalação.GET /api/v1/installation/licence/documentresponde com o documento importado, em bruto, para os administradores. Cada módulo Enterprise obtém-no e verifica novamente as assinaturas com o seu próprio verificador compilado, para que um serviço de identidade modificado não possa ativar um grupo que a licença não concede.
Todas as recusas
Uma importação recusada não altera nada, nem mesmo o limite mínimo do relógio, e a recusa é registada no registo de auditoria.
| Código | HTTP | Significado | O que fazer |
|---|---|---|---|
LICENCE_FORMAT_INVALID |
422 | O ficheiro não é uma licença que esta compilação consiga ler: não é JSON, não corresponde ao esquema, tem datas fora de ordem ou um grupo nomeado duas vezes. | Envie o ficheiro exatamente como a Adverant lho entregou. |
LICENCE_SIGNATURE_INVALID |
422 | Falta uma das duas assinaturas, ou o ficheiro foi alterado após a assinatura. | Peça novamente o ficheiro à Adverant e não o edite. |
LICENCE_ROOT_UNKNOWN |
422 | Está assinada com uma chave que as raízes de confiança desta versão não detêm. | Peça uma licença assinada para as raízes desta versão, ou atualize. |
LICENCE_MATRIX_MISMATCH |
422 | Foi escrita para uma matriz de edições que esta compilação não lê, ou concede um grupo que o catálogo da compilação não conhece. | Atualize para uma versão que a leia, ou peça uma licença escrita para esta versão. |
LICENCE_OTHER_INSTALLATION |
409 | Foi emitida para outro ID de instalação. | Peça uma licença para a identidade desta instalação. |
LICENCE_REVOKED |
403 | A Adverant retirou esta licença. | Peça uma nova licença à Adverant. |
LICENCE_LOCKED |
403 | A licença ainda não começou: a data atual é anterior a starts_on. |
Importe-a novamente no primeiro dia ou após essa data. |
TRANSITION_NOT_PERMITTED |
409 | Já foi importada uma licença com este ID. | Peça uma nova licença à Adverant se os termos tiverem de mudar. |
RECORD_NOT_FOUND |
404 | A instalação ainda não foi declarada, pelo que não tem identidade para verificação. | Conclua o primeiro passo de administrador e, em seguida, importe. |
VALIDATION_FAILED |
400 | Não foi possível ler o corpo, tem mais de 1 MiB ou o pedido tinha uma query string. | Envie apenas o ficheiro como corpo, sem consulta (query). |
A instalação verifica numa ordem fixa, e a primeira falha define o código. Uma metade em falta é comunicada antes de uma chave desconhecida, e um documento cujas assinaturas falhem nunca continua a ser lido, pelo que um ficheiro adulterado que também indique outra instalação continua a responder LICENCE_SIGNATURE_INVALID.
Renovação
Uma renovação é uma nova licença com um novo licence_id. Importe-a da mesma forma que a primeira. Produz efeito imediato, independentemente do estado que a antiga tivesse atingido: a partir de WARN, GRACE ou RESTRICT, a instalação volta diretamente a estar licenciada e nada precisa de ser reinstalado. A Adverant também pode emitir uma licença alterada a meio do prazo, por exemplo para adicionar Decision rooms, e importa-a da mesma forma.
Importar a mesma licença duas vezes é recusado com TRANSITION_NOT_PERMITTED.
Revogação
A Adverant retira uma licença assinando uma lista de revogação. A lista tem um número sequence e indica cada ID de licença retirado, com a data e o motivo. As listas são cumulativas: cada uma transporta todos os IDs revogados antes dela. Importa-a da mesma forma que uma licença:
curl --fail-with-body -X POST https://auth.harrow.example/api/v1/installation/licence/revocations \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
--data-binary @revocations-12.jsonUma lista cuja sequência não seja superior à última importada é recusada com TRANSITION_NOT_PERMITTED, pelo que uma lista antiga não pode voltar a ser colocada no lugar de uma mais recente. Uma lista que não seja lida ou não seja validada é recusada com os mesmos códigos de uma licença. Assim que uma lista indica a sua licença, o respetivo estado passa a ser TERMINATE.
Uma instalação sem ligação ao exterior apenas toma conhecimento de uma revogação quando alguém importa a lista. Para Harrow, a revogação é uma questão tanto de contrato como de software, e Tomás importa cada lista que a Adverant envia na travessia seguinte.
Utilizadores acima da licença
A quantidade da licença é um compromisso sobre a utilização, e o Nexus trata o facto de a exceder como um aviso, nunca como um bloqueio. Quando mais pessoas utilizam o Nexus do que a licença abrange, os administradores veem a placa SEATS_OVER_LICENCE na página People. Todos continuam a trabalhar. A placa indica até quando deve regularizar a situação (30 dias), mostra de onde vieram as pessoas extra e oferece as duas soluções: remover pessoas que não precisam do Nexus ou pedir mais lugares (seats) à Adverant. Adicionar lugares é uma alteração sensível que requer uma segunda pessoa, e os lugares extra são contabilizados na declaração anual de utilização.
A declaração de utilização contém apenas contadores, e pode ler todas as linhas antes de ser enviada. Harrow guarda-a como um ficheiro e transporta-a através da troca offline.
Avaliações
Uma avaliação é uma licença do tipo evaluation, iniciada a partir da página Trials da conta para uma implementação reivindicada. Dura, no máximo, 30 dias, abrange, no máximo, 5 pessoas nomeadas e não tem período de tolerância. No dia seguinte a ends_on, passa diretamente para RESTRICT: as áreas Enterprise voltam a ser demonstrações (teasers) e nada do que foi criado durante a avaliação é eliminado. As execuções de Ideas, as políticas em rascunho e as regras de correio são mantidas exatamente como estavam e abrem novamente assim que uma licença é importada.
Uma organização executa uma avaliação alojada localmente de cada vez.




