Control de acceso

El control de acceso de Lamassu transforma una identidad autenticada en permisos concretos. El proveedor OIDC o el certificado cliente demuestra quién realiza una petición; el servicio authz decide qué puede hacer esa identidad y sobre qué recursos.

Lamassu no asigna permisos directamente a usuarios. La cadena completa es:

credencial → principal coincidente → políticas concedidas → reglas → decisión

Este modelo permite representar personas, grupos del proveedor de identidad, cuentas de servicio y dispositivos sin acoplar la autorización a un proveedor concreto.

Conceptos esenciales

Un principal conecta una credencial con Lamassu. Define cómo reconocer una identidad OIDC o X.509 y puede estar activo o desactivado.

Una política agrupa permisos reutilizables. Puede concederse a varios principales y puede contener reglas sobre entidades de Lamassu, reglas sobre rutas HTTP o ambas.

Una regla de entidad concede acciones sobre recursos como autoridades certificadoras, certificados, perfiles de emisión, dispositivos, DMS, claves o suscripciones de alertas. Puede abarcar todos los recursos de un tipo o limitarse por identificador, relación o atributo.

Una regla HTTP concede acciones asociadas a rutas de una API. Es el mecanismo que utiliza el Gateway para decidir si una petición puede atravesar el perímetro.

Un grant es la asociación entre un principal y una política. Quitar el grant elimina todos los permisos aportados por esa política, sin modificarla para los demás principales.

Dos sistemas de decisión

Lamassu utiliza dos caminos de autorización según quién implementa el servicio protegido. Comparten principales, políticas y grants, pero no interpretan las reglas de la misma manera.

Servicios HTTP integrados o externos → Gateway → reglas HTTP
Servicios desarrollados por Lamassu  → middleware del servicio → reglas de entidad

Servicios HTTP integrados o externos

Este camino protege APIs que se incorporan a la plataforma a través del Gateway pero que no implementan de forma nativa el SDK de autorización de Lamassu. Job Manager es el ejemplo actual. El mismo patrón permite integrar otros servicios HTTP siempre que sus rutas estén descritas en un esquema HTTP de authz.

La decisión se toma antes de reenviar la petición al servicio:

1. Envoy Gateway autentica la petición, normalmente validando un JWT contra el JWKS del proveedor OIDC.
2. Para una ruta protegida, Envoy envía el método, la URL, las cabeceras y los datos necesarios a /v1/ext_authz/check.
3. authz extrae la credencial y resuelve todos los principales activos que coinciden con ella.
4. Carga por separado las políticas concedidas a cada principal.
5. El esquema HTTP traduce la combinación de método y ruta a una acción lógica, como nbi-job-read o nbi-workflow-create.
6. authz busca una regla HTTP que conceda esa acción.
7. Si la ruta declara restricciones, compara datos de la petición con los atributos normalizados del mismo principal que aporta la política; los param_constraints de la propia política también fijan la acción concedida a valores literales de la petición.
8. Un resultado satisfactorio permite a Envoy reenviar la petición; cualquier otra respuesta la bloquea en el Gateway.

Cuando permite el acceso, authz devuelve el principal seleccionado en la cabecera de respuesta X-Principal-ID. El Gateway puede propagar esa cabecera al servicio para conservar el contexto de identidad.

Las reglas HTTP responden principalmente a “¿puede esta identidad llamar a esta operación de la API?”. Por sí solas no generan filtros sobre la base de datos del servicio externo. Para limitar una ruta a un dispositivo, tenant o cliente concreto, o bien el esquema declara una restricción que relaciona un valor de la petición con un atributo normalizado del principal, o bien la política fija ese valor de la petición a un literal con param_constraints. Lo primero limita cada identidad a sus propios recursos con un único grant; lo segundo restringe un grant a un valor fijo, sin importar quién lo posea.

Rutas solo de autenticación y rutas no mapeadas

Dos ajustes del propio esquema cubren endpoints que las políticas no mencionan:

• skip_authz: true en una ruta permite alcanzarla a cualquier identidad que coincida con un principal activo, aunque no tenga políticas concedidas. Úsalo para rutas como /openapi.json o /health que todo cliente autenticado debería poder consultar. La petición sigue necesitando una autenticación válida: una credencial que no supera la validación o no coincide con ningún principal activo se rechaza antes de considerar este ajuste. Una ruta con skip_authz no puede declarar restricciones, y prevalece sobre la ruta o la acción por defecto de cualquier otro esquema para la misma petición.
• default_action con base_paths decide qué ocurre cuando una petición cae bajo un prefijo de ruta que el esquema posee pero ninguna ruta explícita coincide. deny — el valor con el que se entrega el esquema del Job Manager — convierte la denegación implícita de las rutas no mapeadas en una declaración explícita y auditable; allow abre los endpoints no mapeados bajo ese prefijo a cualquier identidad que coincida con un principal activo.

Son decisiones del esquema, no de una política: skip_authz elimina la comprobación del grant para esa ruta, incluso cuando otro esquema asigna la misma petición a una acción que exige un grant, y default_action solo cubre las peticiones que ninguna ruta explícita de ningún esquema cubre. Ten en cuenta tres reglas:

• default_action exige al menos una entrada en base_paths, y las rutas base son rutas absolutas como /api/wfx/nbi/v1.
• Una ruta explícita de cualquier esquema tiene prioridad: la acción por defecto solo decide peticiones que ninguna ruta de ningún esquema cubre. Cuando los prefijos de dos esquemas se solapan, decide el prefijo coincidente más largo.
• Dos esquemas no pueden reclamar la misma ruta base con acciones por defecto distintas; el esquema en conflicto no llega a cargar.

Servicios desarrollados por Lamassu

Los servicios nativos de Lamassu integran autorización en su middleware y conocen las entidades sobre las que operan: certificados, CAs, perfiles de emisión, claves, dispositivos, DMS o suscripciones, entre otras.

La decisión se toma con el contexto de la operación de dominio:

1. El middleware extrae la credencial y resuelve los principales coincidentes.
2. El endpoint identifica la acción, el tipo de entidad y, cuando corresponde, la clave del recurso solicitado.
3. authz reúne las reglas de entidad de las políticas concedidas.
4. El motor evalúa grants directos, filtros por atributos y relaciones con otras entidades.
5. Para una operación individual, comprueba que el recurso concreto satisface el alcance calculado.
6. Para un listado, genera un filtro SQL que el servicio añade a su propia consulta.

Aquí el motor responde a “¿puede esta identidad realizar esta acción sobre este recurso concreto?”.

Las acciones se dividen en dos grupos:

• Las acciones globales no necesitan un identificador de recurso. create, import o el acceso a una sección de la interfaz son ejemplos habituales.
• Las acciones atómicas se evalúan sobre una instancia concreta. En certificados aparecen read, metadata-update, status-update y delete; para una CA también existen sign, reissue y otras operaciones de ciclo de vida.

El filtrado dentro del servicio evita fugas en listados: los recursos no autorizados quedan fuera de la consulta SQL en lugar de recuperarse y ocultarse después en la interfaz.

Cómo se relacionan ambos caminos

No son dos controles equivalentes aplicados dos veces. Las reglas HTTP protegen el perímetro de un servicio integrado; las reglas de entidad expresan permisos sobre el modelo de datos de los servicios nativos.

Una política puede contener ambos tipos de reglas cuando una identidad necesita operar recursos de Lamassu y también llamar a una API integrada. Conceder una regla de entidad no concede automáticamente una acción HTTP, ni una regla HTTP crea acceso sobre una entidad.

Principales OIDC

Un principal OIDC coincide con los claims de un JWT validado. Es apropiado para usuarios humanos, grupos corporativos, roles del IdP y cuentas de servicio que obtienen tokens.

El siguiente principal representa a cualquier identidad que tenga el rol pki-operators en Keycloak:

{
  "id": "oidc:pki-operators",
  "name": "Operadores de PKI",
  "description": "Equipo responsable de la operación diaria",
  "type": "oidc",
  "active": true,
  "auth_config": {
    "claims": [
      {
        "claim": "realm_access.roles",
        "operator": "contains",
        "value": "pki-operators"
      }
    ]
  }
}

Las rutas de claims pueden estar anidadas, como realm_access.roles. Dentro de un mismo principal, todas las condiciones deben cumplirse. Esto permite exigir, por ejemplo, un grupo y una audiencia organizativa a la vez.

Los operadores implementados son:

• equals, para igualdad exacta;
• contains, para comprobar la pertenencia a una lista o la presencia de texto en un valor escalar.

Diseña la coincidencia con atributos estables. Para personas, suele ser mejor enlazar permisos a grupos o roles gestionados centralmente que al correo o al nombre de usuario. Para una cuenta de servicio, un sub estable evita que sus permisos se mezclen con los de un operador humano.

Principales X.509

Un principal X.509 permite reconocer una carga de trabajo o un dispositivo mediante su certificado cliente. Lamassu comprueba la firma del certificado contra la CA configurada y, según el modo, también su número de serie o Common Name.

Los modos disponibles son:

• serial_and_ca: un certificado exacto, identificado por número de serie y CA;
• cn_and_ca: un Common Name exacto o con comodines y una CA concreta;
• any_from_ca: cualquier certificado emitido directamente por la CA indicada.

Este ejemplo reconoce certificados cuyo CN comienza por factory-a- y que están firmados por la CA configurada:

{
  "id": "x509:factory-a-devices",
  "name": "Dispositivos de la fábrica A",
  "type": "x509",
  "active": true,
  "auth_config": {
    "match_mode": "cn_and_ca",
    "subject_cn": "factory-a-*",
    "ca_trust": {
      "pem": "<certificado-CA-en-PEM-o-base64>",
      "identity_type": "fingerprint",
      "value": "SHA256:<huella-sha256-de-la-ca>"
    }
  }
}

ca_trust.identity_type acepta fingerprint o authority_key_id. En ambos casos debes aportar el certificado de la CA en ca_trust.pem; Lamassu verifica tanto la firma como la identidad esperada de la CA.

Usa any_from_ca únicamente cuando todas las identidades emitidas por esa CA deban compartir los mismos permisos. Si una CA emite certificados para poblaciones distintas, separa el acceso por serie o CN, o utiliza CAs de emisión diferentes.

Cuando coinciden varios principales

Una misma credencial puede coincidir con más de un principal. Es habitual que un usuario coincida con un principal de su equipo y con otro de su función operativa.

Para permisos de entidad, Lamassu combina los permisos con lógica OR: basta con que una de las políticas de uno de los principales permita la acción. Los listados contienen la unión de los recursos visibles para todos ellos.

Las rutas HTTP con restricciones son más estrictas. El mismo principal que aporta la política debe satisfacer también los atributos exigidos por la ruta. Lamassu no combina la política de un principal con un atributo perteneciente a otro.

Por esta razón, añadir un principal coincidente solo puede ampliar el acceso. Antes de crear reglas solapadas, revisa el conjunto completo de políticas que recibirá una identidad real.

Cómo expresan acceso las políticas

Acceso global y acceso directo

Una regla identifica el dominio (namespace), el esquema de datos (schema_name) y el tipo de entidad (entity_type). actions enumera las operaciones permitidas.

direct_grants limita la regla a identificadores concretos. El valor * abarca todas las instancias del tipo. Una política de superadministrador utiliza comodines en esquema, entidad, acciones y grants; una política de mínimo privilegio debe evitarlos siempre que sea posible.

Acceso heredado por relaciones

Las reglas pueden seguir relaciones declaradas entre entidades. Por ejemplo, el esquema conoce la relación de un certificado con su CA emisora y la de un dispositivo con su DMS. Una política puede conceder acceso a un recurso padre y propagar acciones seleccionadas hacia sus recursos relacionados.

Esto permite expresar modelos como “puede operar los dispositivos de este DMS” sin mantener una lista individual de cada dispositivo. Cuando se añade un recurso bajo esa relación, hereda el alcance previsto por la política.

Acceso filtrado por atributos

column_filters aplica condiciones a columnas que el esquema haya declarado como filtrables. Todos los filtros de una misma regla se combinan con AND.

Por ejemplo, esta regla permite leer certificados activos emitidos por una CA concreta:

{
  "namespace": "pki",
  "schema_name": "ca",
  "entity_type": "certificate",
  "actions": ["read"],
  "relations": [],
  "column_filters": [
    {
      "column": "status",
      "type": "string",
      "operator": "eq",
      "value": "ACTIVE"
    },
    {
      "column": "issuer_meta_id",
      "type": "string",
      "operator": "eq",
      "value": "ca-production"
    }
  ]
}

Los operadores disponibles son eq, neq, gt, gte, lt, lte, in y like. Usa comparaciones coherentes con el tipo de columna: like para texto, comparaciones de orden para números o fechas y in cuando haya una colección de valores aceptados.

Reglas HTTP

Las reglas HTTP no apuntan directamente a tablas. Referencian un esquema de rutas y conceden sus acciones lógicas. Las políticas del Job Manager son un ejemplo: distinguen lectura, creación, actualización y eliminación de workflows o jobs.

Algunas rutas también comparan un valor de la petición —extraído de la ruta, query, cabecera o cuerpo JSON— con un atributo normalizado del principal. Así puede verificarse que un dispositivo solo consulte trabajos dirigidos a su propio client_id.

Los atributos normalizados desacoplan la política del mecanismo de autenticación. subject_attribute_mappings puede derivar, por ejemplo, device_id desde oidc.claim.device_id o desde x509.subject.cn. La regla consume device_id en ambos casos.

Una regla HTTP también puede fijar una acción concedida a un valor literal que la propia petición transporte, mediante param_constraints. Extrae el valor con las mismas fuentes que las restricciones de ruta —path_regex_group, query, header o json_body— pero lo compara con un literal equals escrito en la política, no con un atributo del principal. El grant depende entonces solo de la petición, no de quién posea la política:

{
  "http_rules": [
    {
      "http_schema_name": "mysvc",
      "actions": ["system-info-read"],
      "param_constraints": [
        {
          "action": "system-info-read",
          "request": { "source": "path_regex_group", "index": 1 },
          "equals": "1"
        }
      ]
    }
  ]
}

Combinada con una ruta del esquema como ^/api/mysvc/system/([^/]+)/info$, concede GET /api/mysvc/system/1/info y deniega la misma llamada para el sistema 2, con independencia de los atributos del principal. El mismo mecanismo fija parámetros de query, cabeceras o campos del cuerpo JSON, por ejemplo { "source": "query", "name": "tenant_id" } con "equals": "1" para aceptar solo peticiones que lleven ?tenant_id=1.

Ten en cuenta que:

• action debe estar entre las acciones concedidas por la regla; equals es obligatorio; path_regex_group necesita un index mayor que cero, query y header un name, y json_body un path como $.tenant_id.
• param_constraints no se coteja con el esquema al cargar la política. Una referencia que la ruta no puede satisfacer —por ejemplo, un path_regex_group sobre una ruta sin grupos de captura— simplemente nunca coincide y la petición se deniega.
• Varios param_constraints para la misma acción se combinan con AND. Una regla sin ellos conserva el comportamiento habitual: la acción se concede donde la ruta coincida y las restricciones del principal se cumplan.

Políticas incluidas

La precarga de authz instala políticas reutilizables para los dominios principales. Entre ellas se encuentran:

• acceso completo y de solo lectura a certificados y autoridades;
• acceso completo y de solo lectura a KMS;
• acceso completo y de solo lectura a Device Manager, DMS Manager, Validation Authority y alertas;
• una política Auditor de lectura de PKI y visibilidad de autorización;
• acceso a la interfaz;
• políticas de administración y observación para las APIs NBI y SBI del Job Manager;
• SUPER ADMIN, que concede todas las acciones sobre los dominios authz y pki.

Empieza por estas políticas antes de crear otras. Si ninguna refleja el límite que necesitas, crea una política específica y pequeña en lugar de copiar SUPER ADMIN y retirar permisos de forma informal.

Provisiona el primer administrador

El chart incluye un principal de bootstrap que busca el rol OIDC pki-admin en realm_access.roles. Le concede SUPER ADMIN y, cuando Job Manager está habilitado, la política administrativa de su API NBI.

auth:
  externalAuthorization:
    enabled: true
    failOpen: false

services:
  authz:
    jwkUrl: https://idp.example.com/realms/iot/protocol/openid-connect/certs
    bootstrap:
      - principal_id: "oidc:pki-admin"
        principal_name: "PKI Admin"
        principal_type: "oidc"
        policy_ids:
          # SUPER ADMIN
          - "lamassu.a6811b60-5f89-4ce7-badb-78ea234794d3"
          # Job Manager - Mgmt NBI Admin
          - "lamassu.7df018c1-3140-4a35-9067-2e7d6cec3ed2"
        auth_config:
          claims:
            - claim: "realm_access.roles"
              operator: "contains"
              value: "pki-admin"

El Job Helm de preinstalación y preactualización ejecuta las migraciones de authz, precarga las políticas y crea los principales de bootstrap antes de iniciar los servicios. Si el principal ya existe, no lo reemplaza: añade únicamente los grants configurados que todavía falten. Puedes conservar la entrada en values.yaml durante las actualizaciones.

Bootstrap de Fastlane

Fastlane instala un realm de Keycloak para laboratorio y crea el usuario lamassu con contraseña temporal lamassu, rol pki-admin y cambio de contraseña obligatorio. Su principal de bootstrap coincide mediante preferred_username=lamassu.

Diseña roles de mínimo privilegio

Evita reproducir la estructura interna de tu empresa con decenas de políticas casi idénticas. Empieza por las responsabilidades que realmente necesitan acceso:

• Administración de autorización: gestiona principales, políticas y grants. Debe pertenecer a un grupo pequeño y separado.
• Operación de PKI: administra CAs, perfiles y certificados, pero no necesariamente puede modificar quién obtiene acceso.
• Registro de dispositivos: opera dispositivos y DMS sin recibir permisos sobre claves o configuración de autorización.
• Auditoría: consulta configuración y actividad sin crear, modificar, firmar, revocar ni eliminar.
• Automatización: utiliza una cuenta técnica o certificado independiente, con permisos limitados al flujo y recursos que controla.

Para cada rol, separa “ver” de “cambiar”, limita los recursos mediante grants, relaciones o atributos y evita * salvo que el rol deba abarcar futuras acciones automáticamente.

Cambios y revocación de acceso

Para retirar acceso de inmediato, desactiva el principal o revoca sus grants. Desactivar un principal conserva su configuración y asociaciones para investigación o restauración, pero deja de participar en la coincidencia.

Eliminar un rol o grupo en el IdP evita que nuevos tokens contengan el claim, pero un token ya emitido puede seguir siendo válido hasta expirar. Si la retirada es urgente, combina el cambio en el IdP con la desactivación del principal en Lamassu y la revocación de sesiones o tokens en el proveedor.

Cuando edites una política compartida, recuerda que el cambio afecta a todos sus principales. Para probar un nuevo alcance, crea una política separada, concédela a una identidad de prueba y valida operaciones permitidas y denegadas antes de sustituir la anterior.

Lista de comprobación operativa

• Mantén failOpen: false salvo que una evaluación de riesgo documentada justifique lo contrario.
• Usa grupos o roles estables para personas e identidades independientes para automatizaciones.
• Conserva al menos dos administradores de recuperación y prueba su acceso periódicamente.
• Revisa los principales activos, sus coincidencias y sus grants después de cambios en el IdP.
• Busca comodines en políticas antes de actualizar Lamassu.
• Revisa las rutas skip_authz y los ajustes de default_action de los esquemas HTTP al integrar o actualizar un servicio.
• Prueba siempre una operación permitida y otra denegada para cada rol.
• Correlaciona los cambios de principales, políticas y grants con los registros de auditoría.

Diagnóstico

La respuesta es 401

La autenticación falló antes de evaluar permisos. Comprueba la firma y expiración del JWT, el emisor, la audiencia y la disponibilidad del JWKS configurado en el Gateway. Para X.509, revisa que el certificado cliente llegue hasta el punto que extrae la credencial.

La respuesta es 403

La credencial pudo procesarse, pero no produjo una autorización positiva. Revisa en este orden:

1. que exista un principal activo del tipo correcto;
2. que las rutas de claims y sus valores coincidan exactamente con el token real;
3. que todas las condiciones del principal se cumplan;
4. que el principal tenga concedida la política esperada;
5. que la política incluya la acción y el tipo de recurso o ruta solicitados;
6. que el identificador, relación, filtro de columna o restricción HTTP incluya el recurso real.

En los logs de authz, una decisión del endpoint externo incluye allowed, reason, matched_principals, evaluated_policy_ids, matched_policy_id y el código de estado. Estos campos permiten separar un fallo de coincidencia de un fallo de permisos. Con la instrumentación OpenTelemetry habilitada, cada decisión genera además un span —engine.CheckHTTP en el camino del Gateway— cuyos atributos registran authz.allowed, la política coincidente y el principal coincidente, de forma que puedas correlacionar la denegación con la traza del Gateway.

Todo devuelve 403

Comprueba que el principal de bootstrap fue creado y que las políticas fueron precargadas por el Job de migración. Verifica también que services.authz.jwkUrl sea alcanzable desde el pod de authz; no asumas que una URL pública accesible desde el navegador también funciona dentro del clúster.

Aparece acceso sin política concedida

La ruta puede estar cubierta por una decisión del esquema y no por una política: las rutas marcadas con skip_authz permiten el paso a cualquier identidad que coincida con un principal activo, y una petición bajo un prefijo de base_paths cuyo esquema fija default_action: allow también se concede sin consultar políticas. Comprueba cuál de las dos situaciones aplica antes de buscar grants ausentes o mal asignados.

Todo falla cuando authz no está disponible

Es el comportamiento esperado con failOpen: false. Restaura el servicio, su conexión con PostgreSQL y su conectividad con el JWKS. No cambies temporalmente a failOpen: true sin aceptar que las rutas protegidas podrían quedar accesibles sin decisión de autorización.

Continúa con Registros de auditoría para investigar cambios de configuración o con Resolución de problemas para diagnosticar el despliegue.