Contas e acesso

O Arkvory conhece quatro tipos de credenciais. Pessoas entram com uma senha. Suas próprias ferramentas usam tokens de acesso pessoal. Sistemas de CI e agentes de implantação usam chaves de serviço. O instalador cria mais uma chave, a chave de recuperação, para configuração e emergências. O servidor verifica cada solicitação em relação à credencial com que ela veio.

Quem pode fazer o quê

Credencial	Criada por	Validade	Administração	Acesso ao repositório
Sessão por senha	Entrar	12 horas	Usuários e grupos, se a conta for administradora	Leitura ou escrita por repositório, por grupos
Token de acesso pessoal	Você, a partir de uma sessão por senha	90 dias por padrão, no máximo 365	Nunca	Seus grupos, opcionalmente somente leitura
Chave de serviço	A chave de recuperação ou um operador delegado	90 dias por padrão, no máximo 365	Somente o que o proprietário delegou	A política da conta de serviço, restringida pela chave
Chave de recuperação	O instalador	Até você substituí-la	Usuários, grupos, contas de serviço, backups	Leitura e escrita em releases

Três coisas são fáceis de esquecer:

• Uma conta de administrador gerencia usuários e grupos. Ela não dá acesso a arquivos. Os arquivos são alcançados somente por meio de concessões de grupo.
• Uma chave de serviço é criada pela chave de recuperação ou por uma chave de operador, não por uma sessão por senha. Um administrador que entrou com uma senha não pode criar contas de serviço.
• Um token pessoal ou uma chave de serviço nunca pode criar usuários, grupos ou outros tokens.

O proprietário e a chave de recuperação

A primeira conta é o proprietário. É um administrador. O assistente de configuração do Windows a cria. No Linux e no Docker, você a cria no console com a chave de recuperação, como descreve O console web.

O proprietário é membro do grupo arkvory-owners, que tem acesso de escrita ao repositório releases. Para qualquer outro repositório, conceda acesso a um grupo você mesmo. Consulte Grupos e acesso a repositórios.

A chave de recuperação é o arquivo config/bootstrap-token.txt no diretório de instalação. Somente um administrador do servidor pode lê-lo. Não o copie para o CI nem para máquinas de clientes. As ferramentas de instalação e atualização o leem, então não o exclua. Consulte Segurança.

Criar usuários

Somente administradores criam usuários. Um nome tem de 3 a 64 letras, dígitos, ., _ ou -. Uma senha tem de 12 a 128 caracteres. Uma instalação contém no máximo 1000 contas.

No console:

1. Entre como administrador e abra Usuários e acesso.
2. Expanda Criar usuário.
3. Informe Nome de usuário e Senha. Marque Administrador apenas para pessoas que gerenciam usuários.
4. Selecione Criar usuário.

A tabela Contas lista as contas. Desativar bloqueia uma conta: suas sessões terminam imediatamente e seus tokens pessoais param de funcionar até você selecionar Ativar. Para definir uma nova senha para alguém, expanda Redefinir senha. Isso encerra as sessões da conta e revoga todos os seus tokens pessoais.

Com a API, uma sessão de administrador ou a chave de recuperação chama estas operações: createUser, updateUser e listUsers.

curl -X POST "$ARKVORY/api/v1/users" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"anna","password":"a long password here","administrator":false}'

await client.administration.users.create('anna', 'a long password here', false);

arkvoryctl não tem comandos para contas. Use o console ou a API.

O autocadastro fica desativado por padrão. O administrador do servidor o ativa com ARKVORY_ALLOW_REGISTRATION=true (consulte Variáveis de ambiente). Então Cadastrar-se aparece no cartão de entrada. Uma nova conta não tem acesso a nenhum repositório até que um administrador a adicione a um grupo. O autocadastro para em 900 contas, então 100 lugares ficam livres para administradores.

Grupos e acesso a repositórios

As pessoas obtêm acesso por meio de grupos. Um grupo tem membros e, para cada repositório, um nível de acesso:

Nível no console	Significado
Leitura	Ver e baixar
Leitura e gravação	Tudo de leitura, e enviar, publicar, alterar metadados, promover e restaurar

Um repositório não tem uma etapa separada de criação. Ele existe assim que uma concessão ou uma política de serviço o nomeia. Um nome usa letras latinas minúsculas, dígitos, - e _, começa com uma letra ou um dígito e tem no máximo 64 caracteres. Consulte Repositórios.

No console, abra Usuários e acesso:

1. Expanda Criar grupo, informe um nome em Grupo de acesso (de 2 a 64 letras, dígitos, ., _ ou -) e selecione Criar grupo.
2. Expanda Gerenciar membros dos grupos, escolha o grupo e a conta e selecione Adicionar ao grupo. Remover do grupo tira a conta do grupo.
3. Expanda Gerenciar acesso a repositórios, escolha o grupo, digite o nome em Repositório, escolha o nível em Acesso e selecione Salvar acesso. Remover acesso remove o acesso.

A tabela abaixo dos formulários mostra os Membros e as Permissões de cada grupo. Remover um membro ou uma concessão tem efeito na próxima solicitação da conta. Os arquivos permanecem onde estão.

Uma instalação contém no máximo 100 grupos, 10 000 associações e 10 000 concessões no total.

Com a API, as operações são createAccessGroup, addGroupMember, removeGroupMember, setGroupGrant e removeGroupGrant:

curl -X PUT "$ARKVORY/api/v1/access-groups/$GROUP_ID/grants/builds" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"access":"write"}'

await client.administration.groups.setGrant(groupId, 'builds', 'write');

Permissões

Por trás dos dois níveis leitura e escrita há 24 ações de repositório. Uma chave de serviço nomeia essas ações uma a uma. arkvoryctl doctor e GET /api/v1/auth/permissions mostram as ações que a credencial atual possui, por repositório.

Ação	Rótulo no console	Permite
repository.read	Descobrir repositórios	Listar repositórios e ver seus próprios direitos. Sem acesso a arquivos.
artifact.list	Listar artefatos	Listar e pesquisar artefatos, ler a lista de estágios e o diário de promoção
artifact.read	Ler detalhes de artefatos	Detalhes do artefato, estágios e histórico de promoção de um artefato
content.read	Baixar arquivos	Baixar bytes, criar links de download, resolver um pacote para download
upload.create	Iniciar uploads	Iniciar um upload
upload.read	Ler o progresso de uploads	Ler o estado e as partes do seu próprio upload
upload.write	Enviar bytes	Enviar os bytes do seu próprio upload
upload.complete	Concluir uploads	Concluir seu próprio upload, iniciar uma tarefa de conclusão
upload.cancel	Cancelar uploads	Cancelar seu próprio upload
job.read	Ler tarefas	Ler sua própria tarefa de conclusão
package.read	Ler pacotes	Listar pacotes UPack e resolver uma versão
package.publish	Publicar pacotes	Registrar um arquivo enviado como pacote
asset.read	Ler vínculos de arquivos	Ler caminhos de arquivo, seu histórico e suas revisões
asset.write	Atribuir vínculos de arquivos	Tornar um artefato o conteúdo atual de um caminho
asset.restore	Restaurar o histórico de arquivos	Restaurar uma revisão anterior de um caminho
annotation.read	Ler metadados	Ler rótulos, metadados, coleções e anexos
annotation.write	Editar metadados	Alterar rótulos, metadados, coleções e anexos
artifact.promote	Promover artefatos e gerenciar estágios	Adicionar e remover estágios, promover para o repositório
reference.write	Gerenciar referências	Adicionar e remover sua própria referência externa em um artefato
audit.read	Ler auditoria	Ler a auditoria do catálogo do repositório
artifact.delete	Excluir artefatos	Verificar e excluir artefatos, pré-visualizar e aplicar retenção
storage.read	Ver política e uso do armazenamento	Ler a política de armazenamento, o uso e as configurações de limpeza
storage.manage	Gerenciar política de armazenamento	Alterar a política de armazenamento e as configurações de limpeza, executá-las
diagnostics.read	Ler diagnósticos	Ler eventos de armazenamento

Como os níveis de um grupo mapeiam para ações:

• Leitura concede repository.read, artifact.list, artifact.read, content.read, package.read, asset.read e annotation.read.
• Escrita concede tudo de leitura, e upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, asset.restore, annotation.write, artifact.promote, reference.write e audit.read.
• Nenhum nível de grupo concede artifact.delete, storage.read, storage.manage e diagnostics.read. Excluir artefatos e gerenciar armazenamento são para chaves de serviço que nomeiam essas ações. Consulte Armazenamento e retenção.

Um espelho é uma cópia somente leitura de outro repositório (Espelhos). Toda ação que o altera é recusada com 409 mirror_read_only, independentemente do que as concessões digam.

Senhas e sessões

Entre com Nome de usuário e Senha no cartão Conexão com o repositório. Uma sessão dura 12 horas. Desconectar a encerra.

Para alterar sua própria senha, use Alterar minha senha no mesmo cartão. Informe a Senha atual e a Nova senha. Todas as suas sessões e tokens pessoais terminam, então você entra novamente e cria novos tokens. Um administrador pode redefinir a senha de outra conta sem saber a antiga.

O servidor retarda a adivinhação:

• Um endereço de rede pode tentar 10 entradas em uma rajada e depois mais uma a cada 15 segundos.
• Após muitas senhas erradas para uma conta, a conta espera cada vez mais, até 2 minutos. Mesmo a senha correta é recusada durante essa espera. A resposta é 429 rate_limited com Retry-After.
• Atrás de um proxy reverso, o administrador lista o proxy em ARKVORY_TRUSTED_PROXIES. Caso contrário, todas as pessoas compartilham um mesmo endereço.

Com a API, login troca um nome e uma senha por uma sessão bearer, e changeOwnPassword altera a senha:

curl -X POST "$ARKVORY/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"name":"anna","password":"a long password here"}'

Tokens de acesso pessoal

Um token de acesso pessoal é uma chave para suas próprias ferramentas: um script no seu computador, o arkvoryctl ou o SDK. Ele age como você, com os repositórios dos seus grupos.

Somente uma sessão por senha cria tokens. Um token não pode criar outro token e não tem direitos de administrador.

1. Entre com sua senha.
2. No cartão Conexão com o repositório, expanda Tokens de acesso pessoal.
3. Informe um Nome do token. Escolha Expira após: 30 dias, 90 dias ou 365 dias.
4. Escolha Acesso: Somente leitura ou Leitura e gravação. Um token de leitura recusa toda alteração com 403 read_only_token.
5. Selecione Gerar token e depois Copiar token. O token é mostrado uma vez. Ele começa com pat_.

A tabela mostra o Prefixo, o Criado em, o Expira em, o Último uso e o Status de cada token: Ativo, Expirado ou Revogado. Para interromper um token, selecione Revogar token e confirme com Revogar. Os clientes que o usam perdem o acesso imediatamente.

Uma conta pode conter 50 tokens ativos. Um administrador pode listar e revogar os tokens de qualquer conta com listAccountTokens e revokeAccountToken.

Com a API, um token tem um nome e, opcionalmente, uma validade (de até 365 dias a partir de agora) e um escopo:

curl -X POST "$ARKVORY/api/v1/auth/tokens" \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"laptop","scope":"read-write","expiresAt":"2027-01-31T00:00:00Z"}'

const created = await client.identity.createToken('laptop', { scope: 'read-write' });
console.log(created.token); // shown once

O escopo padrão da API é read-write. O console pré-seleciona Somente leitura.

Forneça o token ao arkvoryctl em um arquivo privado. Consulte Linha de comando.

Contas de serviço e chaves para CI

Uma conta de serviço é uma identidade para uma ferramenta, não para uma pessoa. Ela tem uma política: os repositórios e as ações que pode usar. Uma conta de serviço tem chaves. Uma chave também tem sua própria lista de repositórios e ações. Os direitos efetivos são a interseção das duas listas, ação por ação. Uma política vazia não dá acesso a arquivos.

Você gerencia o acesso de serviço com a chave de recuperação ou com uma chave de operador à qual o proprietário delegou direitos. No console:

1. Selecione Desconectar se você estiver conectado. Depois abra Conectar com uma chave de serviço ou de automação, cole a chave de recuperação em Chave de serviço e selecione Conectar.
2. Abra Acesso de serviços. A seção aparece somente para a chave de recuperação e para chaves de operador.

Criar uma conta e sua política

1. Em Acesso de serviços, expanda Criar conta de serviço.
2. Informe um Nome da conta (de 3 a 64 letras, dígitos, ., _ ou -).
3. Em Permissões nos repositórios, selecione Adicionar repositório e digite o nome em Repositório.
4. Preencha as permissões: Predefinição de leitura e Predefinição de publicação definem conjuntos típicos, Limpar permissões os limpa, e Permissões individuais lista todas as ações. Selecione Remover repositório para remover um repositório.
5. Selecione Criar conta de serviço.

Os dois predefinidos são:

Predefinido	Ações
Predefinição de leitura	repository.read, artifact.read, artifact.list, content.read, package.read, asset.read, annotation.read
Predefinição de publicação	O conjunto de leitura, e upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, annotation.write

Nenhum predefinido inclui promoção, restauração ou exclusão. Adicione artifact.promote para uma tarefa de promoção. Um agente de implantação que apenas baixa precisa do conjunto de leitura para o arkvoryctl. Para um download HTTP simples de um pacote por nome, só content.read é suficiente.

Uma política tem no máximo 64 repositórios e uma instalação no máximo 1000 contas de serviço. Uma política salva tem uma versão. Se alguém a alterar nesse meio-tempo, o console mostra um conflito e mantém seu rascunho: selecione Recarregar conta e aplique sua alteração novamente. Desativar conta bloqueia todas as chaves da conta. Transferências que já estão em execução podem terminar.

Emitir, salvar e ativar uma chave

1. Abra a conta e suas Chaves de serviço.
2. Expanda Emitir chave. Informe um Nome da chave. Defina a validade em Expira em (horário local, opcional) ou deixe em branco para 90 dias. A validade mais longa é de 365 dias.
3. Restrinja as permissões se a chave precisar de menos que a conta. Selecione Emitir chave.
4. A janela Salve o novo segredo mostra o segredo uma vez. Selecione Copiar segredo e guarde-o no seu armazenamento de segredos de CI. O segredo começa com arkvory_.
5. Marque Salvei o segredo e selecione Ativar chave.

Uma chave que não é ativada é inútil e expira após 15 minutos. Ela aparece como Aguardando ativação até você ativá-la. Uma conta pode conter 3 chaves ativas e 2 chaves pendentes ao mesmo tempo. Os estados são Aguardando ativação, Ativa, Revogada e Expirada; Detalhes da chave lista o id e as permissões de uma chave.

Se a resposta se perder antes de você copiar o segredo, o servidor não poderá mostrá-lo novamente. Revogue a chave e emita outra.

Com a API, a chave de recuperação cria a conta e depois emite a chave. O cabeçalho Idempotency-Key (de 1 a 128 letras, dígitos, ., _, : ou -) torna uma solicitação repetida segura, mas uma repetição não retorna segredo. A chave se ativa quando chama activateServiceKey:

curl -X POST "$ARKVORY/api/v1/service-accounts" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" \
  -d '{"name":"ci-prod","bindings":[{"resource":{"kind":"repository","id":"releases"},"actions":["repository.read","artifact.read","artifact.list","content.read","package.read","upload.create","upload.read","upload.write","upload.complete","job.read","package.publish","asset.read","asset.write"]}]}'

curl -X POST "$ARKVORY/api/v1/service-accounts/$ACCOUNT_ID/keys" \
  -H "Authorization: Bearer $RECOVERY_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-prod-2026-10" \
  -d '{"name":"pipeline-2026","bindings":[{"resource":{"kind":"repository","id":"releases"},"actions":["content.read","package.read","artifact.read"]}]}'

curl -X POST "$ARKVORY/api/v1/auth/activate-key" -H "Authorization: Bearer $NEW_SECRET"

As mesmas etapas no SDK:

const account = await root.administration.services.create('ci-prod', bindings);
const issued = await root.administration.credentials.issue(account.id, requestId, {
  name: 'pipeline-2026',
  bindings,
});
if (!issued.secret) throw new Error('Lost response: revoke the key and issue another');
await saveToSecretStore(issued.secret);
await new ArkvoryClient(url, () => issued.secret ?? '').identity.activateKey();

Forneça a chave ativada à tarefa como ARKVORY_TOKEN_FILE ou ARKVORY_TOKEN. Consulte o exemplo de CI.

Rotacionar e revogar

Rotacione uma chave antes que ela expire, sem lacuna:

1. Ao lado da chave, selecione Rotacionar. O formulário é preenchido com as permissões da chave antiga. Você só pode mantê-las ou reduzi-las.
2. Emita a nova chave, salve seu segredo e ative-a.
3. Migre suas tarefas para o novo segredo.
4. Selecione Revogar na chave antiga.

Ativar a nova chave limita a antiga a no máximo mais 24 horas, então uma chave antiga esquecida não continua viva. Revogar é permanente e pede o nome da chave. Novas solicitações com a chave são recusadas imediatamente. Transferências que já estão em execução podem terminar. Com a API, as operações são rotateServiceKey e revokeServiceKey.

Log de atividades na conta mostra quem emitiu, ativou, rotacionou e revogou chaves, com o horário. Ele não guarda segredos. O servidor mantém os últimos 100 000 eventos de todas as contas.

Administração delegada

No dia a dia, não use a chave de recuperação. O proprietário pode entregar partes da administração de serviço a uma chave de operador e manter a chave de recuperação offline.

1. Com a chave de recuperação, crie uma conta de serviço para o operador com uma política vazia e emita e ative uma chave para ela.
2. Abra Chaves de serviço dessa conta e selecione Administração delegada na chave.
3. Expanda Nova delegação. Informe o ID da conta de destino, a conta que o operador gerenciará.
4. Marque as Ações administrativas e defina o Permissões máximas nos repositórios, o máximo que o operador pode conceder em repositórios.
5. Selecione Salvar delegação.

As sete ações são:

Ação	Rótulo no console	O operador pode
service-account.read	Ler contas	Ver a conta
service-account.manage	Ativar ou desativar contas	Ativá-la e desativá-la
policy.read	Ler políticas de contas	Ler sua política
policy.manage	Gerenciar políticas de contas	Substituir sua política
credential.read	Ler metadados de chaves	Listar suas chaves
credential.manage	Emitir, rotacionar e revogar chaves	Emitir, rotacionar e revogar suas chaves
service-audit.read	Ler auditoria de serviços	Ler seu registro de atividade

Regras:

• Tudo o que o operador define deve permanecer dentro do teto. Uma chave que ele emite expira no máximo junto com sua própria chave.
• Um operador pode emitir chaves para a conta alvo, então trate a delegação como confiança em tudo o que o teto permite.
• Um operador não pode gerenciar sua própria conta e não pode delegar mais adiante. Uma conta não pode ser ao mesmo tempo alvo e operador.
• Remover uma delegação com Remover delegação não revoga as chaves que o operador já ativou. Revogue-as você mesmo.
• O operador vê suas próprias atribuições em Minhas permissões administrativas.

Somente a chave de recuperação define delegações. As operações são listServiceDelegations, setServiceDelegation e removeServiceDelegation.

Auditoria

Administradores podem ler o diário de segurança da instalação: entradas e falhas, registros, alterações e redefinições de senha, alterações de usuário, grupo e concessão, e criação e revogação de tokens. Cada entrada tem o horário, o autor, o tipo de credencial, o endereço do cliente, o alvo e o resultado (success, failure ou denied). Ela não contém senhas nem segredos. O servidor mantém as entradas por 365 dias ou 1 000 000 de entradas, o que ocorrer primeiro.

O console não tem tela para esse diário. Leia-o com a API, com uma sessão de administrador ou a chave de recuperação. As páginas contêm 50 entradas por padrão e no máximo 100, as mais recentes primeiro. Passe next como after para a próxima página.

curl -H "Authorization: Bearer $ADMIN_KEY" "$ARKVORY/api/v1/security/audit?limit=20"

const page = await client.administration.security.audit({ limit: 20 });

O registro de atividade de uma conta de serviço é separado. Consulte Emitir, salvar e ativar uma chave.

Se o proprietário ficar bloqueado

Quando ninguém consegue entrar como administrador, use a chave de recuperação:

1. Leia a chave no servidor: config/bootstrap-token.txt no diretório de instalação. Somente um administrador do servidor pode fazer isso.
2. No console, abra Conectar com uma chave de serviço ou de automação, cole a chave em Chave de serviço e selecione Conectar.
3. Abra Usuários e acesso. Expanda Redefinir senha, escolha a conta, informe uma Nova senha e selecione Redefinir senha. Se a conta aparecer como desativada, selecione Ativar.
4. Entre com a nova senha.

Você também pode criar um novo administrador com Criar usuário e marcar Administrador.

O formulário Criar o primeiro proprietário funciona somente enquanto a instalação não tem contas. Depois, use a chave de recuperação para reparar contas, não para começar de novo.

Se a própria chave de recuperação for perdida, o administrador do servidor substitui o SHA-256 da chave em config/keys.json e reinicia a API. Consulte Segurança.

Páginas relacionadas

• O console web
• Repositórios
• Linha de comando (arkvoryctl)
• Autenticação e a referência da API: Contas e login, Contas de serviço e chaves
• Segurança