Roles

Asigna usuarios y grupos a roles, y define qué puede hacer cada rol.

  1. El atributo roles
  2. El rol default
  3. Objeto Role
  4. Opciones de rol

El atributo roles

La lista roles de nivel superior de config.yaml:

Atributo Comentarios
roles
array

Roles
🔗 valid role object

The roles provide RBAC. Each role has a name and 1 or more groups (local, ldap or entraid). The admin and default roles are mandatory (public is the old name of default, and still works).
Since version 4.0.11 you can also add users (local, ldap or entraid).
Since version 5.0.8 options are introduced to add specific role-options.

  • showDesigner: The user can see the designer
  • allowFormDesign: The user can edit the forms config in the designer (categories, constants, forms: save, restore, pull and push the forms repositories). Without it the designer shows them read-only. Default true. (Added in 7.3.0)
  • allowPlaybookDesign: The user can edit the playbooks in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.0.0)
  • allowWorkflowDesign: The user can edit the workflows in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • allowInventoryDesign: The user can edit the inventories in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • allowVarsFileDesign: The user can edit the vars files in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • showSettings: The user can see the settings page
  • showDebugButtons: The user can see the debug buttons on a form
  • showExtravars: The user can see the extravars on a form
  • showLogs: The user can see the server log (Settings > Server log)
  • showAuditLog: The user can see the audit log (Settings > Audit log) without the other settings. Default: admins. (Added in 7.3.0)
  • showAppearanceSettings: The user can change Settings > Appearance (defaults, name, logo, icon, links, environment label, announcements) without the other settings. Default false. (Added in 7.3.0)
  • showConnectionsSettings: The user can manage Settings > Connections (repositories, credentials, secret stores, runners, SSH, notifications, chat assistant, MCP, syslog) without the other settings. Default false. (Added in 7.3.0)
  • showJobs: The user can see the jobs page. Default true.
  • showArtifacts: The user can see the artifacts an AWX job returns. Default true.
  • allowFileUploads: The user can upload files through a form’s file fields. Without it the field is read-only and the upload is refused. Default true. (Added in 7.3.0)
  • allowApiTokens: The user can make API tokens (Profile > API token), living up to API_TOKEN_MAX_DAYS. Default false (true for a role that only sets extendedTokenExpiration, as before this option). (Added in 7.3.0)
  • extendedTokenExpiration: With allowApiTokens, the user can also make API tokens that never expire. Default false.
  • showAllJobLogs: The user can see all job logs (not only his own) (Added in 5.0.9)
  • allowLogin: The user can login.
  • allowBackupOps: The user can perform database operations, such as backup and restore.
  • allowVerboseMode: The user can enable verbose mode on ansible forms.
  • allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions.
  • allowJobDeletion: The user can delete jobs (their own ; an admin every job). Without it the job history stays whole. Default true. (Added in 7.3.0)
  • manageAllJobs: The user can abort, delete and relaunch the jobs of every user, not only their own, without the admin role (delete and relaunch also need allowJobDeletion and allowJobRelaunch). Default: admins. (Added in 7.3.0)
  • allowScheduledJobs: The user can create and manage scheduled jobs (recurring cron or one-time). Default for admins only. Grant it only to roles you would trust as admins: every user with this option sees and can change all schedules, not only their own, and a schedule they create runs with admin rights, for any form. (Added in 6.1.5)
  • allowStoredJobs: The user can store and load job data for later use. (Added in 6.1.5)
  • allowPlannedJobs: The user can plan a one-time run of a form they may run (“Run later”). The job runs as that user, not as admin, and they cannot see or change other schedules. (Added in 6.1.5)
  • allowChat: The user can use the chat assistant (when it is enabled). Default true. (Added in 6.5.0)
  • allowMcp: The user can use the MCP server from an AI agent (when it is enabled). Defaults to the role’s allowChat. (Added in 7.0.0)

When options are not set, the admin role will have all options.
When options are set on the default role, they are everyone’s defaults: they have the lowest precedence and only fill the options none of the user’s own roles set.
You can add options on role level, which override the default role’s options. Between a user’s own roles the most restrictive wins (an option false on one of them is false).
The default role is every signed-in user’s ; there is no anonymous access. public is its name before 7 and keeps working (forms listing public still match), but new configs say default.

The allowLogin option is different, that is for the backend. By default everyone can login.
You can set it to false on default and then enable on the roles you want to give access. Watch out you don’t lock yourself out.

Ejemplos:

1) Roles

roles:
- name: admin        # is mandatory
  groups:
  - local/admins
  - ldap/Domain Admins
  - entraid/Domain Admins
- name: operator
  groups:
  - local/operator
- name: architect
  groups:
  - local/architect
  options:
    showDesigner: true      # architects can see the designer
    showLogs: true          # architects can see the logs
    allowJobRelaunch: true  # architects can relaunch jobs with pre-filled data
- name: demo
  groups:
  - local/demo
- name: usersonly
  users:
  - local/myuser
- name: default        # is mandatory
  groups: []  
  options:
    showDebugButtons: true  # everyone can see the debug buttons
    showExtraVars: true     # everyone can see the extravars

El rol default

Todo usuario con sesión iniciada tiene el rol default, así que un formulario con roles: [default] está abierto a todos los que pueden iniciar sesión. No hay acceso anónimo: nadie recibe este rol sin iniciar sesión.

El rol no contiene grupos ni usuarios, ya que se aplica a todos. Sus options son los valores predeterminados de todos, como se describe en Opciones de rol más abajo. config.yaml debe tener un rol admin y un rol default, y la página de roles muestra ambos como Requerido.

default se llamaba public antes de la 7.0.0, y el nombre antiguo sigue funcionando:

  • En un formulario, roles: [public] sigue coincidiendo con todos los usuarios, así que los formularios de tus repositorios no necesitan cambios.
  • En config.yaml, un rol llamado public se renombra a default en el archivo al cargar la configuración. Solo cambia el nombre, antes se hace una copia de seguridad de la configuración, y una configuración guardada en un repositorio queda con un cambio que hacer push.
  • En una plantilla ytt, la plantilla no se reescribe: se renombra la configuración que produce, y un aviso en el log te pide que renombres también el rol en la plantilla. La versión 8 rechaza ahí un rol public.

Una configuración con un rol default y un rol public a la vez se rechaza, porque son el mismo rol.

Objeto Role

Cada entrada de la lista roles:

A role allows RBAC. Each role has 1 or more groups (local or ldap). Except the default role (public its old name), which has no groups.
The default and admin roles are mandatory.

Atributo Comentarios
name
string / required / unique

The name of the role
alphanumeric + dash + underscore + space

The name of a role has to be unique. The default and admin roles are mandatory.
groups
array / required

Groups
A group (local, ldap or entraid)

A list of groups. They must be in the format of local/groupname or ldap/groupname or entraid/groupname

A Microsoft Entra ID group can be named by its object id, entraid/<object id>: unique, where two groups can share a display name. Both work ; the object id is the one to prefer.

azuread/, the Microsoft Entra ID prefix of before 7.3, still works the same as entraid/ (deprecated, removed in 8.0) ; the roles editor writes entraid/.
users
array / required
added in version 4.0.10

User
A user (local, ldap or entraid)

A list of local or ldap users. They must be in the format of local/username or ldap/username or entraid/username (azuread/username before 7.3, still accepted)
credentials
array
added in version 7.0.0

The credentials this role may use
regular expressions, matching a whole credential name

Limits the credentials a user of this role may use: those a job passes to a playbook or a template (the form’s credentials, ansibleCredentials, vaultCredentials, a credential field), and those a form query or fnCredentials reads while the user fills in a form. Each entry is a regular expression that must match the whole name ; __self__ is AnsibleForms’ own database.

A user none of whose roles lists credentials may use every credential, as before. Once one of their roles lists them, they may use what any of the roles that list them allows. The admin role is never limited. A launch that needs a credential the roles do not allow is refused before the job is created.
secretStores
array
added in version 7.0.0

The secret stores this role may read inline
secret store names

Limits the secret stores a user of this role may read through an inline reference (vault:<path>, secret:<store>:<ref>) in a credential map, a query or fnCredentials. When a role limits the credentials and none limits the stores, an inline reference must match a credential pattern itself: it is no way around them. Combined across roles as credentials.
runners
array
added in version 7.0.0

The runners this role may run jobs on
runner names

Limits the runners a job of a user of this role may run on: the form’s runner, or the default runner when it names none. Combined across roles as credentials.
options
object
added in version 5.0.8

Role options
Key value pairs

Since version 5.0.8 you can add specific role options. The options are used to enable or disable certain features for a role.
The options are:

  • showDesigner: The user can see the designer
  • allowFormDesign: The user can edit the forms config in the designer (categories, constants, forms: save, restore, pull and push the forms repositories). Without it the designer shows them read-only. Default true. (Added in 7.3.0)
  • allowPlaybookDesign: The user can edit the playbooks in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.0.0)
  • allowWorkflowDesign: The user can edit the workflows in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • allowInventoryDesign: The user can edit the inventories in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • allowVarsFileDesign: The user can edit the vars files in the designer (save, new, remove, push). Without it the designer shows them read-only. Default true. (Added in 7.1.0)
  • showSettings: The user can see the settings page
  • showDebugButtons: The user can see the debug buttons on a form
  • showExtravars: The user can see the extravars on a form
  • showLogs: The user can see the server log (Settings > Server log)
  • showAuditLog: The user can see the audit log (Settings > Audit log) without the other settings. Default: admins. (Added in 7.3.0)
  • showAppearanceSettings: The user can change Settings > Appearance (defaults, name, logo, icon, links, environment label, announcements) without the other settings. Default false. (Added in 7.3.0)
  • showConnectionsSettings: The user can manage Settings > Connections (repositories, credentials, secret stores, runners, SSH, notifications, chat assistant, MCP, syslog) without the other settings. Default false. (Added in 7.3.0)
  • showJobs: The user can see the jobs page. Default true.
  • showArtifacts: The user can see the artifacts an AWX job returns. Default true.
  • allowFileUploads: The user can upload files through a form’s file fields. Without it the field is read-only and the upload is refused. Default true. (Added in 7.3.0)
  • allowApiTokens: The user can make API tokens (Profile > API token), living up to API_TOKEN_MAX_DAYS. Default false (true for a role that only sets extendedTokenExpiration, as before this option). (Added in 7.3.0)
  • extendedTokenExpiration: With allowApiTokens, the user can also make API tokens that never expire. Default false.
  • showAllJobLogs: The user can see all job logs (not only his own) (Added in 5.0.9)
  • allowLogin: The user can login.
  • allowBackupOps: The user can perform database operations, such as backup and restore.
  • allowVerboseMode: The user can enable verbose mode on ansible forms.
  • allowJobRelaunch: The user can relaunch jobs with pre-filled form data from previous submissions.
  • allowJobDeletion: The user can delete jobs (their own ; an admin every job). Without it the job history stays whole. Default true. (Added in 7.3.0)
  • manageAllJobs: The user can abort, delete and relaunch the jobs of every user, not only their own, without the admin role (delete and relaunch also need allowJobDeletion and allowJobRelaunch). Default: admins. (Added in 7.3.0)
  • allowScheduledJobs: The user can create and manage scheduled jobs (recurring cron or one-time). Default for admins only. Grant it only to roles you would trust as admins: every user with this option sees and can change all schedules, not only their own, and a schedule they create runs with admin rights, for any form. (Added in 6.1.5)
  • allowStoredJobs: The user can store and load job data for later use. (Added in 6.1.5)
  • allowPlannedJobs: The user can plan a one-time run of a form they may run (“Run later”). The job runs as that user, not as admin, and they cannot see or change other schedules. (Added in 6.1.5)
  • allowChat: The user can use the chat assistant (when it is enabled). Default true. (Added in 6.5.0)
  • allowMcp: The user can use the MCP server from an AI agent (when it is enabled). Defaults to the role’s allowChat. (Added in 7.0.0)

When options are not set, the admin role will have all options.
When options are set on the default role, they will have the lowest precedence and can be used as default options for all roles.
You can add options on role level, which will override the default role options.
Examples

1) Roles

roles:
- name: admin        # is mandatory
  groups:
  - local/admins
  - ldap/Domain Admins
- name: operator
  groups:
  - local/operator
  users:
  - entraid/mike
- name: architect
  groups:
  - local/architect
  options:
    showDesigner: true # architects can see the designer
    showLogs: true     # architects can see the logs
- name: demo
  groups:
  - local/demo
- name: default        # is mandatory
  groups: []  
  options:
    showDebugButtons: true  # everyone can see the debug buttons
    showExtraVars: true     # everyone can see the extravars

Opciones de rol

Las options de un rol activan o desactivan funciones para sus miembros. Desde la 7.3.0 la página del rol las muestra en cuatro grupos, cada opción con una (i) que dice lo que da, el mismo texto que muestra la vista Permisos del perfil:

Opción Permite al usuario Predeterminado
Configuración    
showSettings Ver y cambiar todas las páginas de configuración; el registro del servidor y las copias de seguridad tienen sus propias opciones Solo admins
showAppearanceSettings Cambiar la configuración de apariencia, sin el resto de la configuración (desde la 7.3.0) Desactivado
showConnectionsSettings Gestionar la configuración de conexiones (credenciales, runners y más), sin el resto de la configuración (desde la 7.3.0) Desactivado
showLogs Ver el registro del servidor Solo admins
showAuditLog Ver el registro de auditoría, sin el resto de la configuración (desde la 7.3.0) Solo admins
allowBackupOps Hacer copias de seguridad de la base de datos y restaurarla Solo admins
Diseñador    
showDesigner Ver y usar el diseñador Solo admins
allowFormDesign Editar la configuración de formularios en el diseñador: categorías, constantes y formularios. Sin ella, solo lectura (desde la 7.3.0) Activado
allowPlaybookDesign Editar los playbooks en el diseñador: guardarlos, crearlos, quitarlos y hacer push. Sin ella, solo lectura Activado
allowWorkflowDesign Editar los workflows en el diseñador: guardarlos, crearlos, quitarlos y hacer push. Sin ella, solo lectura Activado
allowInventoryDesign Editar los inventories en el diseñador: guardarlos, crearlos, quitarlos y hacer push. Sin ella, solo lectura Activado
allowVarsFileDesign Editar los archivos de variables en el diseñador: guardarlos, crearlos, quitarlos y hacer push. Sin ella, solo lectura Activado
Trabajos    
showJobs Ver la página de trabajos Activado
showAllJobLogs Ver los trabajos de todos los usuarios, no solo los suyos Solo admins
manageAllJobs Abortar, eliminar y relanzar los trabajos de todos los usuarios; eliminar y relanzar también necesitan las dos opciones siguientes (desde la 7.3.0) Solo admins
showExtravars Ver las extravars de un formulario y de un trabajo Activado
showDebugButtons Ver los botones de depuración de un formulario Activado
showArtifacts Ver los artefactos de un trabajo: lo que devuelve un trabajo en AWX, o lo que un playbook recogió con set_stats Activado
allowVerboseMode Ejecutar trabajos en modo detallado Activado
allowJobRelaunch Relanzar un trabajo con los datos del formulario de una ejecución anterior Solo admins
allowJobDeletion Eliminar trabajos: los suyos, o los de todos los usuarios con manageAllJobs. Sin ella, el historial de trabajos se conserva completo (desde la 7.3.0) Activado
allowScheduledJobs Crear y gestionar programaciones recurrentes y puntuales, en la página Programaciones (consulta el aviso más abajo) Solo admins
allowPlannedJobs Planificar un trabajo para que se ejecute una vez a una hora fijada (Ejecutar más tarde) Activado
allowStoredJobs Guardar los datos de un formulario y volver a cargarlos más tarde Activado
Acceso e integraciones    
allowLogin Iniciar sesión en AnsibleForms Activado
allowChat Usar el asistente de chat, cuando está habilitado Activado
allowMcp Usar el servidor MCP desde un agente de IA, cuando está habilitado El allowChat del rol
allowFileUploads Subir archivos mediante los campos de archivo de un formulario (desde la 7.3.0) Activado
allowApiTokens Crear tokens de API para scripts, hasta la duración máxima que permite la instancia (desde la 7.3.0) Desactivado
extendedTokenExpiration Crear también tokens de API que no caducan nunca; necesita allowApiTokens Desactivado

Algunas opciones incluyen otras, y la página del rol muestra las incluidas activadas y en gris:

  • showSettings da también showAppearanceSettings, showConnectionsSettings y showAuditLog.
  • manageAllJobs da también showAllJobLogs, ya que actuar sobre los trabajos de todos los usuarios implica verlos.
  • Las opciones de diseño solo cuentan con showDesigner, y extendedTokenExpiration solo con allowApiTokens.

Hasta la 7.2.0, showAllJobLogs también permitía al usuario abortar y eliminar los trabajos que mostraba; desde la 7.3.0 eso requiere manageAllJobs. Un rol de antes de la 7.3.0 con extendedTokenExpiration y sin allowApiTokens recibe allowApiTokens, así que conserva sus tokens.

Solo admins significa activado para los usuarios que tienen el rol admin, y desactivado para todos los demás. Cuando un usuario coincide con varios roles, las opciones se combinan así:

  • Entre los roles del usuario, una opción solo está activada cuando todos los roles que la definen están de acuerdo: un false explícito gana.
  • El rol default completa las opciones que no define ninguno de los demás roles del usuario, así que puede contener valores predeterminados para todos.
  • Las opciones que no se definen en ningún sitio toman el valor predeterminado de la tabla.

showExtraVars, con V mayúscula, se acepta como otra forma de escribir showExtravars; cuando cualquiera de las dos es false, la opción está desactivada.

Trata allowScheduledJobs como una opción de nivel de admin. Las programaciones no pertenecen al usuario que las creó: todo usuario con la opción ve y puede cambiar todas las programaciones. Una programación además se ejecuta con derechos de admin, para cualquier formulario, sea cual sea el acceso del creador. Concédela solo a roles en los que confiarías como admins.

allowLogin: false en el rol default deja fuera a todo usuario cuyos otros roles no definan allowLogin: true, incluidos los admins. Vuelve a concederla en los roles que deben iniciar sesión antes de guardar.