Cómo configurar OpenID Connect en Authelia paso a paso

Si utilizas varias aplicaciones en tu servidor, gestionar una cuenta diferente para cada una puede convertirse rápidamente en un problema. Configurar un sistema de inicio de sesión único o SSO permite centralizar la autenticación y acceder a diferentes servicios utilizando una sola identidad.

Authelia puede actuar como proveedor de OpenID Connect, verificando la identidad del usuario y entregando a cada aplicación la información necesaria mediante tokens firmados. Las aplicaciones compatibles, como Portainer, Nextcloud, Grafana o Jellyfin, confían en esta validación y dejan de gestionar directamente las credenciales principales.

En esta guía veremos cómo configurar OpenID Connect en Authelia, generar las claves necesarias, registrar un cliente y solucionar los errores más habituales.

Qué papel cumple Authelia en OpenID Connect

En una integración OpenID Connect intervienen principalmente dos partes. Authelia funciona como OpenID Provider o proveedor de identidad, mientras que la aplicación protegida actúa como Relying Party o cliente OIDC.

Cuando el usuario intenta entrar en una aplicación, esta lo redirige hacia Authelia. Después de validar sus credenciales y, cuando corresponda, el segundo factor, Authelia devuelve un código de autorización. La aplicación intercambia ese código por los tokens necesarios para identificar al usuario.

Authelia puede desempeñar el papel de proveedor, pero no funciona como cliente OIDC. Por tanto, sirve para iniciar sesión en otras aplicaciones mediante Authelia, pero no para acceder a Authelia utilizando una cuenta de Google, GitHub u otro proveedor externo.

Aunque esta implementación continúa identificada como una beta abierta, Authelia está certificado para cumplir el estándar OpenID Connect. Conviene mantener el servicio actualizado y revisar los cambios de configuración antes de saltar entre versiones importantes.

Qué necesitas antes de configurar OIDC

Antes de registrar un cliente, asegúrate de que Authelia funciona correctamente mediante una dirección pública estable, preferiblemente protegida mediante HTTPS. También necesitas una aplicación compatible con OpenID Connect y acceso a su panel de autenticación.

Anota los siguientes datos antes de modificar el archivo configuration.yml:

• URL pública de Authelia: por ejemplo, https://auth.ejemplo.com.
• URL pública de la aplicación: por ejemplo, https://app.ejemplo.com.
• URI de redirección: debe ser la indicada exactamente por la aplicación.
• Client ID: identificador único que permita reconocer al cliente.
• Client Secret: secreto compartido entre Authelia y la aplicación.
• Scopes necesarios: determinan qué información recibirá la aplicación.

La URI de redirección es especialmente importante porque distingue entre mayúsculas y minúsculas. El protocolo, el dominio, el puerto, la ruta y cualquier barra final deben coincidir con el valor utilizado por la aplicación.

Si todavía debes asegurar el acceso exterior, puedes consultar cómo proteger una aplicación con Authelia antes de continuar con la integración OIDC.

Cómo generar el secreto HMAC y la clave JWKS

El proveedor OIDC necesita dos elementos criptográficos diferentes. El primero es el secreto HMAC, que debe ser una cadena aleatoria de al menos 64 caracteres. Puedes generarlo con OpenSSL:

openssl rand -hex 64

El segundo elemento es una clave privada incluida en el conjunto JWKS. Authelia requiere al menos una clave privada RSA compatible con RS256 y de 2048 bits como mínimo. Puedes crearla con este comando:

openssl genpkey -algorithm RSA -out oidc-private.pem -pkeyopt rsa_keygen_bits:2048
chmod 600 oidc-private.pem

El bloque básico del proveedor tendrá una estructura similar a esta:

identity_providers:
  oidc:
    hmac_secret: 'REEMPLAZA_ESTO_POR_UN_SECRETO_ALEATORIO'

    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN PRIVATE KEY-----
          CONTENIDO_DE_LA_CLAVE_PRIVADA
          -----END PRIVATE KEY-----

La clave debe ser privada y estar codificada en formato PEM. No pegues únicamente la clave pública, porque Authelia necesita firmar los tokens emitidos. Tampoco es necesario configurar una cadena de certificados salvo que la aplicación cliente la exija expresamente.

Para un entorno de producción, guarda estos valores mediante archivos de secretos o variables protegidas. Evita subir el secreto HMAC o la clave privada a Git, incluso cuando el repositorio sea privado.

Cómo generar el identificador y el secreto del cliente

Cada aplicación necesita su propio client_id y client_secret. No reutilices el mismo secreto entre varios servicios, ya que una filtración permitiría suplantar a todos los clientes que lo compartan.

Si Authelia está ejecutándose en un contenedor llamado authelia, puedes generar un secreto aleatorio y su hash PBKDF2 con:

docker exec -it authelia authelia crypto hash generate pbkdf2 --random --random.length 72

El comando mostrará dos valores que cumplen funciones distintas:

• Secreto original: debe introducirse en la configuración de la aplicación.
• Hash PBKDF2: debe guardarse como client_secret en Authelia.

No introduzcas el hash en la aplicación. Esta necesita el secreto original sin transformar para demostrar su identidad cuando contacte con el endpoint de tokens.

Cómo registrar una aplicación como cliente OIDC

Los clientes se añaden dentro de identity_providers.oidc.clients. Esta configuración genérica utiliza el flujo Authorization Code y exige autenticación de dos factores:

identity_providers:
  oidc:
    hmac_secret: 'SECRETO_HMAC'

    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        key: |
          -----BEGIN PRIVATE KEY-----
          CONTENIDO_DE_LA_CLAVE_PRIVADA
          -----END PRIVATE KEY-----

    clients:
      - client_id: 'mi-aplicacion'
        client_name: 'Mi aplicación'
        client_secret: '$pbkdf2-sha512$...'
        public: false
        authorization_policy: 'two_factor'
        redirect_uris:
          - 'https://app.ejemplo.com/oauth/callback'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
          - 'groups'
        grant_types:
          - 'authorization_code'
        response_types:
          - 'code'
        consent_mode: 'explicit'

Sustituye la URI del ejemplo por la facilitada por la aplicación. Algunas utilizan una ruta de callback, mientras que otras esperan únicamente la URL raíz. No inventes ni adaptes esta dirección: copia exactamente la indicada en la documentación o el panel del cliente.

El valor public: false corresponde a aplicaciones capaces de mantener un secreto de forma confidencial. Las aplicaciones de una sola página, algunas herramientas de consola y otros clientes que no pueden proteger credenciales deben configurarse como públicos y utilizar PKCE.

Cómo introducir los datos de Authelia en la aplicación

Muchas aplicaciones permiten configurar OIDC introduciendo únicamente la URL del emisor o el documento de descubrimiento:

• Issuer: https://auth.ejemplo.com.
• Discovery URL: https://auth.ejemplo.com/.well-known/openid-configuration.
• Client ID: el identificador registrado en Authelia.
• Client Secret: el secreto original, nunca su hash.
• Redirect URI: la misma dirección registrada en Authelia.
• Scopes: normalmente openid profile email groups.

Si la aplicación no admite descubrimiento automático, puede solicitar los endpoints por separado. Las direcciones habituales de Authelia son:

• Authorization URL: https://auth.ejemplo.com/api/oidc/authorization.
• Token URL: https://auth.ejemplo.com/api/oidc/token.
• UserInfo URL: https://auth.ejemplo.com/api/oidc/userinfo.

Ejemplo de configuración con Portainer

En Portainer debes entrar en Settings > Authentication, seleccionar OAuth y elegir un proveedor personalizado. La configuración oficial utiliza la URL raíz de Portainer como dirección de redirección:

• Authorization URL: https://auth.ejemplo.com/api/oidc/authorization.
• Access Token URL: https://auth.ejemplo.com/api/oidc/token.
• Resource URL: https://auth.ejemplo.com/api/oidc/userinfo.
• Redirect URL: https://portainer.ejemplo.com.
• User Identifier: preferred_username.
• Scopes: openid profile groups email.
• Auth Style: In Params.

Si activas la creación automática de usuarios, Portainer podrá generar una cuenta local cuando alguien acceda por primera vez mediante Authelia. Revisa después qué permisos recibe esa cuenta, porque autenticar a un usuario no implica convertirlo en administrador.

Qué scopes y claims debes permitir

Los scopes determinan qué información puede solicitar una aplicación. Conviene conceder únicamente los necesarios:

• openid: activa el funcionamiento de OpenID Connect y resulta obligatorio.
• profile: entrega atributos básicos como el nombre y el nombre de usuario.
• email: permite que el cliente reciba la dirección de correo.
• groups: entrega los grupos y facilita aplicar permisos dentro de la aplicación.

Los datos concretos entregados se denominan claims. Por ejemplo, Portainer puede utilizar preferred_username para identificar al usuario y el claim groups para asignarle permisos.

No añadas información personal directamente al ID Token salvo que el cliente lo necesite realmente. Estos tokens normalmente están firmados, pero no necesariamente cifrados, por lo que su contenido puede ser decodificado por quien tenga acceso a ellos.

Cómo limitar quién puede utilizar el cliente OIDC

El parámetro authorization_policy permite exigir uno o dos factores. También puedes crear una política personalizada para restringir el cliente a determinados usuarios o grupos:

identity_providers:
  oidc:
    authorization_policies:
      administradores:
        default_policy: 'deny'
        rules:
          - policy: 'two_factor'
            subject: 'group:admins'

    clients:
      - client_id: 'portainer'
        authorization_policy: 'administradores'

Con esta configuración, solamente los integrantes del grupo admins podrán completar la autorización y deberán superar el segundo factor.

Estas políticas OIDC son diferentes de las reglas generales de access_control. Solo se aplican a las solicitudes de autorización OpenID Connect. Para controlar dominios, rutas y redes mediante Forward Auth, consulta cómo configurar reglas de acceso en Authelia.

Siempre que sea posible, utiliza también los controles de permisos de la aplicación. Authelia puede decidir quién obtiene autorización, pero el cliente debe determinar qué operaciones puede realizar cada usuario una vez dentro.

Cómo configurar el consentimiento y PKCE

El parámetro consent_mode controla si Authelia muestra al usuario los permisos solicitados por la aplicación. El valor predeterminado es auto, que aplica el comportamiento apropiado según el resto de la configuración.

Las opciones más importantes son:

• explicit: solicita consentimiento al usuario durante la autorización.
• pre-configured: permite recordar durante un periodo el consentimiento concedido.
• auto: selecciona automáticamente entre los comportamientos compatibles.
• implicit: concede el consentimiento sin preguntarlo, pero está desaconsejado.

No utilices implicit solo para eliminar una pantalla adicional. Si quieres evitar preguntas repetidas, resulta más seguro usar pre-configured junto con una duración limitada.

PKCE añade protección al flujo de autorización e impide aprovechar un código interceptado. Cuando el cliente lo admita, puedes activarlo de esta manera:

require_pkce: true
pkce_challenge_method: 'S256'

El método S256 es preferible a plain. No obstante, algunas aplicaciones todavía no soportan PKCE. Por ejemplo, la configuración documentada actualmente para Portainer lo mantiene desactivado.

Cuándo modificar la duración de los tokens

Authelia permite configurar la duración del código de autorización, el token de acceso, el ID Token y el Refresh Token. En la mayoría de instalaciones es recomendable mantener los valores predeterminados y modificarlos solamente cuando exista una necesidad concreta.

Si una aplicación sensible necesita sesiones más cortas, crea una configuración de duración personalizada en la sección global lifespans.custom y referencia su nombre desde el cliente mediante lifespan. No confundas la duración de los tokens OIDC con la cookie general de sesión de Authelia, porque son controles diferentes.

Cómo validar la configuración antes de reiniciar

Un error de indentación en YAML puede impedir que Authelia arranque. Antes de reiniciar el servicio, valida el archivo con:

authelia config validate --config /config/configuration.yml

Si el contenedor ya está funcionando y se llama authelia, puedes ejecutar:

docker exec authelia authelia config validate --config /config/configuration.yml

Después de aplicar los cambios, revisa los registros mientras intentas iniciar sesión:

docker compose logs -f authelia

Los logs permiten comprobar el client_id, la URI recibida, la política aplicada y el motivo exacto por el que se ha rechazado una solicitud.

Errores frecuentes al configurar OpenID Connect en Authelia

La aplicación muestra redirect_uri_mismatch

La URI enviada por la aplicación no coincide exactamente con ninguna entrada de redirect_uris. Comprueba el protocolo, el dominio, el puerto, la ruta, las mayúsculas y la barra final.

Authelia devuelve invalid_client o un error 401

Revisa que la aplicación tenga el secreto original y que Authelia almacene su hash. También debes comprobar el método de autenticación del endpoint de tokens, porque algunos clientes utilizan client_secret_basic y otros client_secret_post.

La configuración indica que falta una clave RS256

Authelia necesita al menos una clave privada RSA configurada para RS256. Confirma que has pegado el bloque privado completo y que la clave tiene un mínimo de 2048 bits.

El usuario se autentica, pero recibe un error access_denied

La política de autorización no coincide con el usuario, el grupo o la red de origen. Recuerda que las reglas se evalúan en orden y que una política predeterminada deny bloqueará cualquier caso no permitido expresamente.

La aplicación no recibe el correo o los grupos

Comprueba que el cliente tenga habilitados los scopes email y groups, que la aplicación los solicite y que el usuario tenga esos atributos definidos en el backend de identidad.

Los tokens aparecen caducados o todavía no son válidos

Revisa la hora del servidor de Authelia y del equipo donde funciona la aplicación. Una desincronización temporal puede provocar que los campos de validez del token sean rechazados.

Se produce un bucle de redirección

Comprueba que la URL pública de Authelia use HTTPS y que el proxy entregue correctamente las cabeceras de protocolo y host. Si el problema está en esta capa, revisa cómo conectar Authelia con Nginx Proxy Manager.

El cliente público no puede completar la autorización

Los clientes públicos deben utilizar public: true, dejar vacío el secreto y, normalmente, usar PKCE con el método S256. No configures como confidencial una aplicación incapaz de proteger sus credenciales.

Configurar OpenID Connect en Authelia permite centralizar el inicio de sesión sin entregar las credenciales principales a cada aplicación. La clave está en generar correctamente el secreto HMAC y la clave privada JWKS, registrar una URI de redirección exacta y entregar a cada cliente únicamente los scopes que necesita.

Una vez validada la configuración, podrás añadir nuevas aplicaciones repitiendo únicamente el registro del cliente, manteniendo un único sistema de identidad, políticas coherentes y la posibilidad de exigir autenticación multifactor en los servicios más sensibles.