Saltar a contenido

Secretos

Los secretos son configuraciones del proyecto que se almacenan de forma segura y cifrada. Los trabajos tendrán acceso automático a los secretos del proyecto, lo que permite conexiones seguras con servicios externos sin exponer las credenciales en los archivos del proyecto.

Tipos de secretos

Hay dos tipos de secretos que puedes crear en QFieldCloud:

  • Variables de entorno: Estas estarán disponibles para QGIS como variables de entorno mientras se ejecutan los trabajos de su proyecto. Debe proporcionar un nombre (sólo en mayúsculas) y un valor.

  • Configuraciones de pg_service: Esto le permite agregar una conexión PostgreSQL/PostGIS como se define en un archivo de configuración pg_service.conf.

Página del secreto del proyecto tras pulsar el botón **Añadir un nuevo secreto**..
Página del secreto del proyecto tras pulsar el botón Añadir un nuevo secreto..

!!! advertencia! QFieldCloud garantiza que sus credenciales se almacenen de forma segura y cifrada. Recomendamos encarecidamente asignar a los usuarios los privilegios mínimos en entornos compartidos para evitar posibles filtraciones. Los usuarios con permiso para subir archivos también podrían tener acceso a las credenciales correspondientes.

Variable de entorno

Las variables de entorno estarán disponibles para QGIS mientras se ejecuten los trabajos del proyecto.

Debe rellenar el nombre de la variable de entorno (sólo en mayúsculas) y el valor de la variable de entorno como texto libre.

Añadir una variable de entorno.
Añadir una variable de entorno.

Secretos y precedencia

Para proporcionar un control granular sobre el acceso a los datos, los secretos en QFieldCloud se pueden definir en tres niveles jerárquicos diferentes. Al iniciar un nuevo trabajo, QFieldCloud accederá a los secretos disponibles y seguirá el siguiente orden jerárquico de precedencia:

  1. User-Assigned Secret (Highest Precedence): A secret defined within a project and assigned to a specific user. This is the most specific level and overrides all others for that user.

  2. Project-Level Secret: A general secret defined for a specific project. It applies to all project members unless a user-assigned secret is present.

  3. Organization-Level Secret (Lowest Precedence): A secret defined at the organization level. It is used as a fallback for all projects within the organization that require it, provided no project or user-level secret has been set.

Este sistema jerárquico permite a un administrador establecer un rol de base de datos general con privilegios bajos a nivel de la organización, mientras asigna roles más privilegiados para proyectos específicos o usuarios individuales de confianza.

Configuración de secreto

Para agregar un nuevo secreto, primero debes decidir qué tipo de secreto se necesita para tu proyecto.

Secreto de nivel de organización

Accede a la configuración de tu organización y selecciona la pestaña Secretos. Los secretos añadidos aquí estarán disponibles para todos los proyectos de la organización, a menos que se anulen.

Secreto de nivel de proyecto

Accede a la configuración de tu proyecto y selecciona la pestaña Secretos. Los secretos añadidos aquí anularán cualquier secreto de la organización con el mismo nombre.

Nivel asignado por el usuario

En la pestaña Secretos de un proyecto, puedes agregar un nuevo secreto y asignarlo explícitamente a un miembro específico del proyecto. Esto proporciona el mayor nivel de precedencia.

Añadiendo un secreto

Para agregar un nuevo secreto y dar acceso a su base de datos Postgres/PostGIS, siga el mismo formato definido en el archivo de configuración pg_service.conf. Puede hacerlo manualmente como texto sin formato o mediante el "Editor avanzado". El "Editor avanzado" le permite pegar el contenido del archivo pg_service.conf directamente.

Puede agregar la siguiente información:

  • nombre de servicio
  • nombre de base de datos
  • usuario de base de datos
  • contraseña de la base de datos
  • host de la base de datos
  • puerto de base de datos
  • conexión SSL de la base de datos

Para otras configuraciones de servicio, puede utilizar el botón Agregar campo pgservice adicional para agregar configuraciones adicionales y sus valores.

Si utiliza varias definiciones de servicio, debe agregar varios secretos para cada una de ellas.

Nota

Una vez añadido, un secreto sólo puede ser eliminado, pero no puede ser editado.

Note

QFieldCloud secrets are available only during project's job runs, which allows you to configure your PostgreSQL layers as "Offline editing". You cannot use QFieldCloud secrets to distribute pg_service.conf files across devices. For security reasons, you have to do this manually. You can read how to configuring QField to use a pg_service.conf file.

Añadir un servicio PostgreSQL - Editor simple.
Añadir un servicio PostgreSQL - Editor simple.

El "Editor avanzado" permite editar la configuración directamente como texto sin formato. Esto resulta práctico si se desea copiar y pegar la configuración directamente desde el archivo pg_service.conf.

Añadir un servicio PostgreSQL - Editor avanzado.
Añadir un servicio PostgreSQL - Editor avanzado.

Ejemplo

El siguiente ejemplo explicará el proceso de adición y verificación de la jerarquía explicada anteriormente. Puede agregar atributos adicionales a su tabla para comprobar y confirmar que solo los usuarios con los roles correspondientes puedan agregar nuevas funciones.

Parte 1: Configuración de la base de datos PostgreSQL

Primero, es necesario configurar la base de datos y definir los roles de usuario. A continuación, se debe agregar un activador automático para rellenar la columna de usuario asignada dentro de la base de datos.

1. Instanciación de bases de datos y extensiones

Comience creando una nueva base de datos y habilite las extensiones postgis y uuid-ossp necesarias.

-- Cree una nueva base de datos con un nombre, un propietario y una codificación específicos.
CREATE DATABASE db-og-secrets OWNER qfield ENCODING 'UTF8';

-- Conecte a la base de datos recién creada.
\c db-og-secrets

-- Instale las extensiones necesarias si aún no existen.
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

2. Establecimiento de roles

Cree tres roles de usuario distintos para simular la estructura de permisos escalonados que administrarán los secretos de QFieldCloud.

-- Cree tres roles, cada uno con privilegios de inicio de sesión y una contraseña asignada.
CREATE ROLE ninja_org LOGIN PASSWORD 'your_strong_password_for_org';
CREATE ROLE ninja_project LOGIN PASSWORD 'your_strong_password_for_project';
CREATE ROLE ninja_user LOGIN PASSWORD 'strong_password_for_user_001';

3. Definición de esquema y tabla

Cree un esquema y una tabla para las geometrías de puntos. La tabla incluirá un campo pg_user para registrar automáticamente el rol responsable de la inserción de datos.

-- Crea un esquema llamado 'ninja' si aún no existe.
CREATE SCHEMA IF NOT EXISTS ninja;

-- Crea una tabla dentro del esquema 'ninja' con las columnas especificadas.
CREATE TABLE IF NOT EXISTS ninja.ninja_point (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  pg_user TEXT,
  some_value TEXT NOT NULL,
  geom GEOMETRY(POINT, 4326)
);

4. Implementación de un disparador automatizado de atribución de usuarios

Este disparador rellena automáticamente el campo pg_user con el identificador del current_user cada vez que se inserta o actualiza un registro.

-- Defina una función de activación para actualizar el campo pg_user.
BEGIN;
SET LOCAL SEARCH_PATH TO ninja, public;

CREATE OR REPLACE FUNCTION update_pg_user() RETURNS TRIGGER AS $$
BEGIN
  NEW.pg_user := current_user;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SET search_path FROM CURRENT;

COMMIT;

Y asigne el disparador a la tabla ninja_point para eventos INSERT o UPDATE.

BEGIN;
SET LOCAL SEARCH_PATH TO ninja, public;

DROP TRIGGER IF EXISTS trg_ninja_point_update_pg_user ON ninja.ninja_point;

CREATE TRIGGER trg_ninja_point_update_pg_user
  BEFORE INSERT OR UPDATE ON ninja_point
  FOR EACH ROW EXECUTE FUNCTION update_pg_user();

COMMIT;

5. Concesión de permisos

Para garantizar la seguridad y el acceso adecuado a los datos, otorgue a cada rol únicamente los permisos necesarios para su función. Este enfoque sigue el principio del mínimo privilegio.

En primer lugar, todos los roles necesitan permiso de USO en el esquema ninja para acceder a cualquier tabla dentro de él.

GRANT USAGE ON SCHEMA ninja TO ninja_org, ninja_project, ninja_user;
Acceso basado en roles

  • ninja_user (solo lectura): esta función es para usuarios generales que solo necesitan ver datos.

  • Permisos: SELECT

  • ninja_project (Lectura/Escritura): Esta función es para los miembros del proyecto que necesitan ver, agregar y modificar datos.

  • Permisos: SELECT, INSERT, UPDATE

  • ninja_org (Admin): Este rol es para propietarios de organizaciones que requieren control total sobre los datos, incluida la eliminación de registros y la gestión de relaciones de claves externas.

  • Permisos: SELECT, INSERT, UPDATE, DELETE, REFERENCES

-- Otorgar permisos de tabla según las responsabilidades del rol

-- Acceso de solo lectura para usuarios generales
GRANT SELECT ON TABLE ninja.ninja_point TO ninja_user;

-- Acceso de lectura y escritura para los miembros del proyecto
GRANT SELECT, INSERT, UPDATE ON TABLE ninja.ninja_point TO ninja_project;

-- Acceso administrativo completo para propietarios de organizaciones
GRANT ALL PRIVILEGES ON TABLE ninja.ninja_point TO ninja_org;

Parte 2: Configuración del proyecto QFieldCloud y QGIS

Vaya directamente a QFieldCloud para configurar los secretos en diferentes niveles en QFieldCloud.

Escenario 1: Aplicación secreta a nivel de organización

  1. Adición secreta: Vaya a la página de configuración de su organización y seleccione Secretos desde allí. Agregue un nuevo secreto pg_service usando las credenciales para el rol ninja_org.

  2. Verificación: Para garantizar que el secreto esté configurado en el nivel correcto, ahora puede crear una nueva entidad en la capa ninja_point dentro de QField. Una vez sincronizado con QFieldCloud, se espera que el atributo pg_user para la nueva función sea ninja_org.

Escenario 2: Aplicación de secreto a nivel de proyecto (precedencia sobre la organización)

  1. Adición secreta: Navega a la página de configuración de tu proyecto y selecciona los Secretos desde allí. Agregue un nuevo secreto pg_service con el mismo nombre de servicio que el anterior, pero esta vez use las credenciales para el rol ninja_project.

  2. Verificación: Para garantizar que el secreto esté configurado en el nivel correcto, puede crear una nueva entidad en la capa ninja_point dentro de QField. Una vez sincronizado con QFieldCloud, se espera que el atributo pg_user para la nueva función sea ninja_project Esto demuestra que el secreto a nivel de proyecto reemplaza correctamente al secreto a nivel de organización.

Escenario 3: Aplicación secreta a nivel de usuario (máxima prioridad)

  1. Creación de secretos: Navega a la página de configuración de tu proyecto y selecciona la pestaña Secretos. Agregue un nuevo secreto pg_service. Utilice las credenciales para el rol ninja_user y asigne explícitamente este secreto a su cuenta de usuario.

  2. Verificación: Cree una nueva característica en QField. Se espera que el atributo pg_user para esta función sea ninja_user, lo que confirma que el secreto asignado por el usuario tiene el nivel más alto de precedencia en la jerarquía.

Overriding PostgreSQL Session Role

In order to override the connecting PostgreSQL user during packaging and delta applying Jobs, you need to create a specific Environment Variable Secret called QFC_PG_EFFECTIVE_USER.

This Secret instructs QFieldCloud to use a SET ROLE command immediately after connecting to the database. This effectively allows the PostgreSQL role used to perform data operations to be changed from a generic service account to a role that is unique for every QFieldCloud user and reflects that user's username and specific permissions.

Ejemplo

Use Case: Simplified User Management & Auditing (Proxy Authentication)

In an organization with many field workers, managing unique database passwords for every user and updating them in QFieldCloud Secrets is inefficient. Instead, you can use a Proxy Authentication approach where a single powerful role handles connections, but specific roles are used for actual data operations.

1. The Setup

  • Generic Connection User (qfield_admin): You create one database role that handles the actual password/SSL connection. This role should have the necessary USAGE or CONNECT privileges and crucially must be a member of the specific user roles in PostgreSQL/PostGIS.
  • Specific User Roles (user_mielena, ninja_user_001): You can create roles for your actual users without passwords. Those rules will correspond to QFieldCloud users.
  • Grant Permissions: You allow the generic service to "become" the specific users.
-- 1. Create the Roles
-- 'qfield_admin': The generic service account (has the password)
-- 'user_mielena': The specific field worker (no password needed)
CREATE ROLE qfield_admin WITH LOGIN PASSWORD 'strong_password';
CREATE ROLE user_mielena WITH NOLOGIN;

-- 2. Proxy Configuration
-- Allow qfield_admin to switch identity to user_mielena
GRANT user_mielena TO qfield_admin;

-- 3. Create the Data Table
CREATE TABLE field_observations (
    id SERIAL PRIMARY KEY,
    geom GEOMETRY(Point, 4326),
    note TEXT,
    surveyor_name TEXT DEFAULT current_user -- Auto-fill with the effective user
);

-- 4. Grant Table Permissions
-- The specific user needs permission to read/write the table
GRANT ALL ON field_observations TO user_mielena;
GRANT USAGE, SELECT ON SEQUENCE field_observations_id_seq TO user_mielena;

-- 5. Enable Row-Level Security
ALTER TABLE field_observations ENABLE ROW LEVEL SECURITY;

-- 6. Create the Security Policy
-- This policy ensures users can only see and edit rows where
-- the 'surveyor_name' matches their current effective role.
CREATE POLICY surveyor_isolation_policy ON field_observations
    FOR ALL
    -- The USING clause determines which rows are visible
    USING (surveyor_name = current_user)
    -- The WITH CHECK clause ensures they can't create data for others
    WITH CHECK (surveyor_name = current_user);

2. QGIS Configuration (The Generic Connection)

In your QGIS Project, configure your PostgreSQL/PostGIS connection to authenticate as the generic qfield_admin.

Note

You do not need to hardcode the "Session role" in the QGIS connection settings for this workflow. Leave it blank, as QFieldCloud is responsible for injecting the role dynamically through the secret. Although QGIS allows setting a "Session role" manually, for QFieldCloud workflows, it is often better to manage this via Secrets to keep the QGIS project file generic, unless the field worker needs to perform reviews directly in QGIS.

Setting session ROLE in QGIS
Setting session ROLE in QGIS

3. QFieldCloud Configuration (The Override)

When QFieldCloud runs a job (packaging or syncing), it will read the QFC_PG_EFFECTIVE_USER secret. Even though the project connects as qfield_admin, QFieldCloud will switch the active session to the user defined in the secret.

To configure this:

  1. Create a new secret with the type Environment variable.
  2. Name the secret QFC_PG_EFFECTIVE_USER (the name must be exact).
  3. Set the value to the desired role name.

Important

This secret must be explicitly assigned to a User, within a Project or an Organization.

Overriding Session ROLE in QFieldCloud
Overriding Session ROLE in QFieldCloud

The Result:

  • Auditing: When data is synced, database triggers utilizing current_user will record user_mielena as the author, rather than the generic service account.
  • Security: If you use PostgreSQL Row-Level Security (RLS) to restrict users to specific regions, the database will apply rules based on user_mielena, ensuring that the user only downloads or edits their assigned area.