Cuentas y acceso
Arkvory distingue cuatro tipos de credenciales. Las personas inician sesión con una contraseña. Sus propias herramientas usan tokens de acceso personal. Los sistemas de CI y los agentes de despliegue usan claves de servicio. El instalador crea una clave más, la clave de recuperación, para la configuración inicial y las emergencias. El servidor comprueba cada solicitud con la credencial que la acompaña.
Quién puede hacer qué
| Credencial | La crea | Duración | Administración | Acceso a los repositorios |
|---|---|---|---|---|
| Sesión con contraseña | Al iniciar sesión | 12 horas | Usuarios y grupos, si la cuenta es de administrador | Lectura o escritura por repositorio, mediante grupos |
| Token de acceso personal | Usted, desde una sesión con contraseña | 90 días de forma predeterminada, 365 como máximo | Nunca | Sus grupos, opcionalmente solo lectura |
| Clave de servicio | La clave de recuperación o un operador con derechos delegados | 90 días de forma predeterminada, 365 como máximo | Solo lo que el propietario delegó | La política de la cuenta de servicio, restringida por la clave |
| Clave de recuperación | El instalador | Hasta que la reemplace | Usuarios, grupos, cuentas de servicio, copias de seguridad | Lectura y escritura en releases |
Hay tres cosas que es fácil pasar por alto:
- Una cuenta de administrador gestiona usuarios y grupos. No da acceso a los archivos. A los archivos solo se llega mediante los accesos concedidos a los grupos.
- Una clave de servicio la crea la clave de recuperación o una clave de operador, no una sesión con contraseña. Un administrador que inició sesión con una contraseña no puede crear cuentas de servicio.
- Un token personal o una clave de servicio nunca pueden crear usuarios, grupos ni otros tokens.
El propietario y la clave de recuperación
La primera cuenta es la del propietario, que es administrador. La crea el asistente de instalación de Windows. En Linux y Docker se crea en la consola con la clave de recuperación, como describe La consola web.
El propietario es miembro del grupo arkvory-owners, que tiene acceso de escritura al repositorio releases. Para cualquier otro repositorio, conceda usted mismo el acceso a un grupo. Consulte Grupos y acceso a los repositorios.
La clave de recuperación es el archivo config/bootstrap-token.txt del directorio de la instalación. Solo un administrador del servidor puede leerlo. No lo copie a CI ni a los equipos de los clientes. Las herramientas de instalación y de actualización lo leen, así que no lo elimine. Consulte Seguridad.
Crear usuarios
Solo los administradores crean usuarios. El nombre tiene de 3 a 64 caracteres, entre letras, dígitos, ., _ y -. La contraseña tiene de 12 a 128 caracteres. Una instalación admite como máximo 1000 cuentas.
En la consola:
- Inicie sesión como administrador y abra Usuarios y acceso.
- Expanda Crear usuario.
- Rellene los campos Nombre de usuario y Contraseña. Marque la casilla Administrador solo para las personas que administran usuarios.
- Seleccione Crear usuario.
La tabla Cuentas enumera las cuentas. Deshabilitar bloquea una cuenta: sus sesiones terminan de inmediato y sus tokens personales dejan de funcionar hasta que seleccione Habilitar. Para asignar una contraseña nueva a otra persona, expanda Restablecer contraseña. Esto cierra las sesiones de la cuenta y revoca todos sus tokens personales.
Con la API, una sesión de administrador o la clave de recuperación llama a estas operaciones: createUser, updateUser y 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 no tiene comandos para las cuentas. Use la consola o la API.
El autorregistro está desactivado de forma predeterminada. El administrador del servidor lo activa con ARKVORY_ALLOW_REGISTRATION=true (consulte Variables de entorno). Entonces aparece Registrarse en la tarjeta de inicio de sesión. Una cuenta nueva no tiene acceso a ningún repositorio hasta que un administrador la agregue a un grupo. El autorregistro se detiene en 900 cuentas, de modo que quedan 100 plazas libres para los administradores.
Grupos y acceso a los repositorios
Las personas obtienen acceso mediante grupos. Un grupo tiene miembros y, para cada repositorio, un nivel de acceso:
| Nivel en la consola | Significado |
|---|---|
| Lectura | Ver y descargar |
| Lectura y escritura | Todo lo de lectura, y además subir, publicar, cambiar metadatos, promover y restaurar |
Un repositorio no tiene un paso de creación independiente. Existe en cuanto lo nombra una concesión de acceso o una política de servicio. El nombre usa letras latinas minúsculas, dígitos, - y _, empieza por una letra o un dígito y tiene como máximo 64 caracteres. Consulte Repositorios.
En la consola, abra Usuarios y acceso:
- Expanda Crear grupo, escriba el nombre en el campo Grupo de acceso (de 2 a 64 caracteres, entre letras, dígitos,
.,_y-) y seleccione Crear grupo. - Expanda Administrar miembros de grupos, elija el grupo y la cuenta, y seleccione Agregar al grupo. Quitar del grupo quita la cuenta del grupo.
- Expanda Administrar acceso a repositorios, elija el grupo, escriba el nombre del Repositorio, elija el nivel de Acceso y seleccione Guardar acceso. Quitar acceso retira el acceso.
La tabla situada debajo de los formularios muestra los apartados Miembros y Permisos de cada grupo. Quitar un miembro o un acceso surte efecto en la siguiente solicitud de la cuenta. Los archivos permanecen donde están.
Una instalación admite como máximo 100 grupos, 10 000 pertenencias y 10 000 accesos concedidos en total.
Con la API, las operaciones son createAccessGroup, addGroupMember, removeGroupMember, setGroupGrant y 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');Permisos
Detrás de los dos niveles, lectura y escritura, hay 24 acciones de repositorio. Una clave de servicio nombra estas acciones una por una. arkvoryctl doctor y GET /api/v1/auth/permissions muestran las acciones que tiene la credencial actual, por repositorio.
| Acción | Etiqueta en la consola | Qué permite |
|---|---|---|
repository.read | Descubrir repositorios | Enumerar los repositorios y ver los derechos propios. Sin acceso a los archivos. |
artifact.list | Listar artefactos | Enumerar y buscar artefactos, leer la lista de etapas y el diario de promociones |
artifact.read | Leer detalles de artefactos | Detalles, etapas e historial de promociones de un artefacto |
content.read | Descargar archivos | Descargar bytes, crear enlaces de descarga, resolver un paquete para descargarlo |
upload.create | Iniciar subidas | Iniciar una subida |
upload.read | Leer el progreso de subidas | Leer el estado y las partes de su propia subida |
upload.write | Subir bytes | Enviar los bytes de su propia subida |
upload.complete | Finalizar subidas | Terminar su propia subida, iniciar una tarea de finalización |
upload.cancel | Cancelar subidas | Cancelar su propia subida |
job.read | Leer tareas | Leer su propia tarea de finalización |
package.read | Leer paquetes | Enumerar paquetes UPack y resolver una versión |
package.publish | Publicar paquetes | Registrar un archivo subido como paquete |
asset.read | Leer vínculos de archivos | Leer las rutas de archivo, su historial y sus revisiones |
asset.write | Asignar vínculos de archivos | Hacer que un artefacto sea el contenido actual de una ruta |
asset.restore | Restaurar historial de archivos | Restaurar una revisión anterior de una ruta |
annotation.read | Leer metadatos | Leer etiquetas, metadatos, colecciones y adjuntos |
annotation.write | Editar metadatos | Cambiar etiquetas, metadatos, colecciones y adjuntos |
artifact.promote | Promover artefactos y administrar etapas | Agregar y quitar etapas, promover hacia el repositorio |
reference.write | Administrar referencias | Agregar y quitar su propia referencia externa en un artefacto |
audit.read | Leer auditoría | Leer la auditoría del catálogo del repositorio |
artifact.delete | Eliminar artefactos | Comprobar y eliminar artefactos, previsualizar y aplicar la retención |
storage.read | Ver política de almacenamiento y uso | Leer la política de almacenamiento, el uso y la configuración de limpieza |
storage.manage | Administrar política de almacenamiento | Cambiar la política de almacenamiento y la configuración de limpieza, y ejecutarlas |
diagnostics.read | Leer diagnósticos | Leer los eventos de almacenamiento |
Cómo se corresponden los niveles de un grupo con las acciones:
- Lectura da
repository.read,artifact.list,artifact.read,content.read,package.read,asset.readyannotation.read. - Escritura da todo lo de lectura y además
upload.create,upload.read,upload.write,upload.complete,upload.cancel,job.read,package.publish,asset.write,asset.restore,annotation.write,artifact.promote,reference.writeyaudit.read. - Ningún nivel de grupo da
artifact.delete,storage.read,storage.managenidiagnostics.read. La eliminación de artefactos y la administración del almacenamiento corresponden a las claves de servicio que nombran estas acciones. Consulte Almacenamiento y retención.
Un espejo es una copia de solo lectura de otro repositorio (Espejos). Cualquier acción que lo modifique se rechaza con 409 mirror_read_only, sea cual sea el acceso concedido.
Contraseñas y sesiones
Inicie sesión con Nombre de usuario y Contraseña en la tarjeta Conexión al repositorio. Una sesión dura 12 horas. Desconectar la termina.
Para cambiar su propia contraseña, use Cambiar mi contraseña en la misma tarjeta. Rellene los campos Contraseña actual y Nueva contraseña. Todas sus sesiones y todos sus tokens personales terminan, así que debe iniciar sesión de nuevo y crear tokens nuevos. Un administrador puede restablecer la contraseña de otra cuenta sin conocer la anterior.
El servidor dificulta que se adivinen contraseñas:
- Una dirección de red puede intentar 10 inicios de sesión seguidos y, después, uno más cada 15 segundos.
- Tras muchas contraseñas incorrectas para una cuenta, esa cuenta espera cada vez más, hasta 2 minutos. Durante esta espera se rechaza incluso la contraseña correcta. La respuesta es
429 rate_limitedconRetry-After. - Detrás de un proxy inverso, el administrador incluye el proxy en
ARKVORY_TRUSTED_PROXIES. De lo contrario, todas las personas comparten una sola dirección.
Con la API, login intercambia un nombre y una contraseña por una sesión Bearer, y changeOwnPassword cambia la contraseña:
curl -X POST "$ARKVORY/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"name":"anna","password":"a long password here"}'Tokens de acceso personal
Un token de acceso personal es una clave para sus propias herramientas: un script de su equipo, arkvoryctl o el SDK. Actúa en su nombre, con los repositorios de sus grupos.
Solo una sesión con contraseña crea tokens. Un token no puede crear otro token y no tiene derechos de administrador.
- Inicie sesión con su contraseña.
- En la tarjeta Conexión al repositorio, expanda Tokens de acceso personal.
- Rellene el campo Nombre del token. En el campo Caduca tras elija 30 días, 90 días o 365 días.
- En el campo Acceso elija Solo lectura o Lectura y escritura. Un token de solo lectura rechaza cualquier cambio con
403 read_only_token. - Seleccione Generar token y después Copiar token. El token se muestra una sola vez. Empieza por
pat_.
La tabla muestra de cada token las columnas Prefijo, Creado, Caduca, Último uso y Estado, esta última con los valores Activo, Caducado o Revocado. Para anular un token, seleccione Revocar token y confirme con Revocar. Los clientes que lo usan pierden el acceso de inmediato.
Una cuenta puede tener 50 tokens activos. Un administrador puede enumerar y revocar los tokens de cualquier cuenta con listAccountTokens y revokeAccountToken.
Con la API, un token tiene un nombre y, de forma opcional, una caducidad (hasta 365 días a partir de ahora) y un ámbito:
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); // se muestra una sola vezEl ámbito predeterminado de la API es read-write. La consola preselecciona Solo lectura.
Proporcione el token a arkvoryctl en un archivo privado. Consulte Línea de comandos.
Cuentas de servicio y claves para CI
Una cuenta de servicio es una identidad para una herramienta, no para una persona. Tiene una política: los repositorios y las acciones que puede usar. Una cuenta de servicio tiene claves. Cada clave tiene también su propia lista de repositorios y acciones. Los derechos efectivos son la intersección de las dos listas, acción por acción. Una política vacía no da acceso a los archivos.
El acceso de servicio se administra con la clave de recuperación o con una clave de operador a la que el propietario delegó derechos. En la consola:
- Si tiene una sesión iniciada, seleccione Desconectar. Después abra Conectarse con una clave de servicio o de automatización, pegue la clave de recuperación en el campo Clave de servicio y seleccione Conectar.
- Abra Acceso de servicios. La sección aparece solo con la clave de recuperación y con las claves de operador.
Crear una cuenta y su política
- En Acceso de servicios, expanda Crear cuenta de servicio.
- Rellene el campo Nombre de la cuenta (de 3 a 64 caracteres, entre letras, dígitos,
.,_y-). - En Permisos de repositorio, seleccione Agregar repositorio y escriba el nombre del Repositorio.
- Defina los permisos: Conjunto de lectura y Conjunto de publicación establecen conjuntos habituales, Quitar permisos los borra y Permisos individuales enumera todas las acciones. Seleccione Quitar repositorio para descartar un repositorio.
- Seleccione Crear cuenta de servicio.
Los dos conjuntos predefinidos son:
| Conjunto | Acciones |
|---|---|
| Conjunto de lectura | repository.read, artifact.read, artifact.list, content.read, package.read, asset.read, annotation.read |
| Conjunto de publicación | El conjunto de lectura y además upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.publish, asset.write, annotation.write |
Ninguno de los dos conjuntos incluye promoción, restauración ni eliminación. Agregue artifact.promote para una tarea de promoción. Un agente de despliegue que solo descarga necesita el conjunto de lectura para arkvoryctl. Para una descarga HTTP simple de un paquete por nombre, basta con content.read.
Una política tiene como máximo 64 repositorios y una instalación admite como máximo 1000 cuentas de servicio. Una política guardada tiene una versión. Si alguien la cambia entretanto, la consola muestra un conflicto y conserva su borrador: seleccione Recargar cuenta y aplique de nuevo su cambio. Deshabilitar cuenta bloquea todas las claves de la cuenta. Las transferencias que ya están en curso pueden terminar.
Emitir, guardar y activar una clave
- Abra la cuenta y su apartado Claves de servicio.
- Expanda Emitir clave. Rellene el campo Nombre de la clave. Indique la caducidad en Caduca el (hora local, opcional) o déjelo vacío para que sean 90 días. La caducidad máxima es de 365 días.
- Restrinja los permisos si la clave necesita menos que la cuenta. Seleccione Emitir clave.
- La ventana Guarde el nuevo secreto muestra el secreto una sola vez. Seleccione Copiar secreto y guárdelo en el almacén de secretos de su CI. El secreto empieza por
arkvory_. - Marque la casilla He guardado el secreto y seleccione Activar clave.
Una clave que no se activa no sirve y caduca a los 15 minutos. Aparece como Pendiente de activación hasta que la active. Una cuenta puede tener a la vez 3 claves activas y 2 pendientes. Los estados son Pendiente de activación, Activa, Revocada y Caducada; Detalles de la clave muestra el ID y los permisos de una clave.
Si se pierde la respuesta antes de que copie el secreto, el servidor no puede mostrarlo de nuevo. Revoque la clave y emita otra.
Con la API, la clave de recuperación crea la cuenta y después emite la clave. La cabecera Idempotency-Key (de 1 a 128 caracteres, entre letras, dígitos, ., _, : y -) hace que repetir la solicitud sea seguro, pero la repetición no devuelve ningún secreto. La clave se activa a sí misma cuando llama a 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"Los mismos pasos con el 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();Proporcione la clave activada al trabajo como ARKVORY_TOKEN_FILE o ARKVORY_TOKEN. Consulte el ejemplo de CI.
Rotar y revocar
Rote una clave antes de que caduque, sin interrupciones:
- Junto a la clave, seleccione Rotar. El formulario se rellena con los permisos de la clave anterior. Solo puede mantenerlos o reducirlos.
- Emita la clave nueva, guarde su secreto y actívela.
- Cambie sus trabajos al secreto nuevo.
- Seleccione Revocar en la clave anterior.
Al activar la clave nueva, la anterior queda limitada a 24 horas más como máximo, de modo que una clave antigua olvidada no siga vigente. Revocar es permanente y pide el nombre de la clave. Las solicitudes nuevas con esa clave se rechazan de inmediato. Las transferencias que ya están en curso pueden terminar. Con la API, las operaciones son rotateServiceKey y revokeServiceKey.
Registro de actividad, en la cuenta, muestra quién emitió, activó, rotó y revocó claves, con la hora. No guarda secretos. El servidor conserva los últimos 100 000 eventos de todas las cuentas.
Administración delegada
En el uso diario, no utilice la clave de recuperación. El propietario puede ceder partes de la administración de servicios a una clave de operador y mantener la clave de recuperación fuera de línea.
- Con la clave de recuperación, cree para el operador una cuenta de servicio con una política vacía, y emita y active una clave para ella.
- Abra Claves de servicio de esa cuenta y seleccione Administración delegada en la clave.
- Expanda Nueva delegación. Rellene el campo ID de la cuenta de destino con la cuenta que administrará el operador.
- En Acciones administrativas, marque las acciones que correspondan y, en Permisos máximos de repositorio, defina lo máximo que el operador puede conceder en los repositorios.
- Seleccione Guardar delegación.
Las siete acciones son:
| Acción | Etiqueta en la consola | El operador puede |
|---|---|---|
service-account.read | Leer cuentas | Ver la cuenta |
service-account.manage | Habilitar o deshabilitar cuentas | Habilitarla y deshabilitarla |
policy.read | Leer políticas de cuentas | Leer su política |
policy.manage | Administrar políticas de cuentas | Reemplazar su política |
credential.read | Leer metadatos de claves | Enumerar sus claves |
credential.manage | Emitir, rotar y revocar claves | Emitir, rotar y revocar sus claves |
service-audit.read | Leer auditoría de servicios | Leer su registro de actividad |
Reglas:
- Todo lo que establece el operador debe permanecer dentro del límite máximo. Una clave que emite caduca, como muy tarde, cuando caduca la propia clave del operador.
- Un operador puede emitir claves para la cuenta de destino, así que trate la delegación como confianza en todo lo que permite el límite máximo.
- Un operador no puede administrar su propia cuenta ni delegar a su vez. Una cuenta no puede ser a la vez destino y operador.
- Quitar una delegación con Quitar delegación no revoca las claves que el operador ya activó. Revóquelas usted mismo.
- El operador ve sus propias asignaciones en Mis permisos administrativos.
Solo la clave de recuperación establece delegaciones. Las operaciones son listServiceDelegations, setServiceDelegation y removeServiceDelegation.
Auditoría
Los administradores pueden leer el registro de seguridad de la instalación: inicios de sesión y fallos, autorregistros, cambios y restablecimientos de contraseñas, cambios de usuarios, grupos y accesos, y creación y revocación de tokens. Cada entrada tiene la hora, el actor, el tipo de credencial, la dirección del cliente, el destino y el resultado (success, failure o denied). No contiene contraseñas ni secretos. El servidor conserva las entradas durante 365 días o hasta 1 000 000 de entradas, lo que ocurra primero.
La consola no tiene ninguna pantalla para este registro. Léalo con la API, con una sesión de administrador o con la clave de recuperación. Las páginas contienen 50 entradas de forma predeterminada y 100 como máximo, de la más reciente a la más antigua. Pase next como after para obtener la página siguiente.
curl -H "Authorization: Bearer $ADMIN_KEY" "$ARKVORY/api/v1/security/audit?limit=20"const page = await client.administration.security.audit({ limit: 20 });El registro de actividad de una cuenta de servicio es independiente. Consulte Emitir, guardar y activar una clave.
Si el propietario no puede acceder
Cuando nadie puede iniciar sesión como administrador, use la clave de recuperación:
- Lea la clave en el servidor:
config/bootstrap-token.txt, en el directorio de la instalación. Solo un administrador del servidor puede hacerlo. - En la consola, abra Conectarse con una clave de servicio o de automatización, pegue la clave en el campo Clave de servicio y seleccione Conectar.
- Abra Usuarios y acceso. Expanda Restablecer contraseña, elija la cuenta, escriba una Nueva contraseña y seleccione Restablecer contraseña. Si la cuenta aparece como deshabilitada, seleccione Habilitar.
- Inicie sesión con la contraseña nueva.
También puede crear un administrador nuevo con Crear usuario y marcar la casilla Administrador.
El formulario Crear el primer propietario funciona solo mientras la instalación no tiene cuentas. Más adelante, use la clave de recuperación para reparar cuentas, no para empezar de cero.
Si se pierde la propia clave de recuperación, el administrador del servidor sustituye el SHA-256 de la clave en config/keys.json y reinicia la API. Consulte Seguridad.