Proveedores de identidad

ZeroClaw permite iniciar sesión a las personas mediante OpenID Connect y es estricto con el token de acceso que emite el proveedor. La mayoría de los proveedores requieren cambiar algunos ajustes, y algunos todavía no funcionan. Esta página indica qué necesita un proveedor, los proveedores probados con las compilaciones preliminares de v0.9.0, los que se sabe que todavía no funcionan y las limitaciones actuales. Solo se sabe que funcionan los proveedores incluidos en Proveedores probados. Para configurar un proveedor, consulta OIDC y Inicio de sesión en el panel.

El daemon verifica cada token de acceso con las mismas reglas, ya llegue mediante el inicio de sesión en el panel o desde un cliente nativo (zerocode, o un token obtenido con zeroclaw oidc login), así que un proveedor cuyo token de acceso es rechazado queda rechazado en todas partes. zeroclaw oidc login y zeroclaw oidc token solo obtienen un token y lo imprimen. Un inicio de sesión exitoso allí no demuestra que el daemon acepte el token.

Lo que necesita un proveedor

• Descubrimiento. <issuer>/.well-known/openid-configuration debe indicar exactamente el issuer configurado, incluida la barra final.
• PKCE con S256 para el inicio de sesión en el navegador. El inicio de sesión en el panel, zeroclaw oidc login --browser y la inscripción en el navegador del gateway requieren que el documento de descubrimiento incluya S256 en code_challenge_methods_supported. Rechazan un emisor que omita este campo, ya que un campo ausente significa que no hay PKCE, y plain nunca se acepta. El flujo de dispositivo y client_credentials no leen este campo.
• La concesión de dispositivo, para zerocode y zeroclaw oidc login. zerocode y zeroclaw oidc login sin --browser inician sesión con la concesión de autorización de dispositivo (RFC 8628), por lo que el proveedor debe ofrecerla y listar device_authorization_endpoint en el documento de descubrimiento. El inicio de sesión en el panel no la utiliza.
• Un token de acceso que ZeroClaw puede verificar, mediante uno de los dos modos de validation:
  • jwks: un token de acceso JWT conforme a RFC 9068, con la cabecera typ at+jwt (o application/at+jwt), firmado con RS256 o ES256. Debe incluir iss, aud, exp, iat y jti, e identificar su cliente en client_id (para el token de una persona, se acepta azp en su lugar). Cada clave del conjunto de claves del emisor necesita su propio kid. Un JWT con typ JWT o sin typ, que es lo que muchos proveedores emiten por defecto, se rechaza, porque no puede distinguirse de un token de ID.
  • introspection: introspección de tokens RFC 7662, cuya respuesta incluye active: true, token_type: Bearer, el audience configurado y un client_id. El documento de descubrimiento debe listar introspection_endpoint. Este modo necesita el client_secret de la entrada.
• Nada que lo marque como otro tipo de token. En ambos modos, el token (o la respuesta de introspección) no debe incluir una claim nonce. Una claim typ o token_use, si está presente, debe identificar un access token: typ Bearer o at+jwt, y token_use exactamente access.
• El público. El aud del token de acceso debe contener el audience configurado.
• Roles o grupos sin un ámbito adicional. ZeroClaw solicita únicamente el ámbito openid, por lo que los valores en claim_path deben estar en el token de acceso (o en la respuesta de introspección) de forma predeterminada. De lo contrario, asigne las personas una por una, por ejemplo con claim_path = "sub".
• Autenticación del cliente según la solicitud. El intercambio del código de autorización (inicio de sesión en el panel, zeroclaw oidc login --browser y la inscripción del gateway desde el navegador) envía el client_secret en el cuerpo del formulario (client_secret_post). La introspección, el flujo de dispositivo y client_credentials lo envían mediante HTTP Basic (client_secret_basic). Un proveedor que solo acepta el método registrado para un cliente puede requerir una entrada [oidc.<alias>] y un cliente independientes para el flujo de dispositivo o client_credentials. El inicio de sesión en el panel con introspection no puede separarse de esa forma: un único cliente realiza tanto el intercambio como la llamada de introspección, por lo que debe aceptar ambos métodos.
• Una vigencia de token de sesión de trabajo, por ejemplo de una a ocho horas. El panel no usa tokens de actualización, así que una sesión termina cuando caduca su token de acceso.

Proveedores probados

Cada proveedor que aparece a continuación inició sesión con una cuenta de administrador y otra de miembro mediante el inicio de sesión del panel, con los perfiles a los que se asignan sus claims. En la ruta de bearer, el ID token del mismo proveedor, el refresh token y un access token emitido para otro de sus clientes fueron rechazados en cada caso. Las pruebas se ejecutaron contra compilaciones de prelanzamiento de v0.9.0 en octubre y noviembre de 2026. Keycloak se probó con la puerta de enlace sobre HTTP sin cifrar y sobre su propio listener TLS, y con zerocode y zeroclaw oidc login. Zitadel y Authelia se probaron únicamente con el inicio de sesión del panel.

Keycloak

• Activa el encabezado de token de acceso RFC 9068 del cliente (access.token.header.type.rfc9068 = true), exige PKCE S256 y define un tiempo de vida del token de acceso de una a ocho horas. El valor predeterminado de Keycloak es de cinco minutos.
• Añade un mapeador de audiencia que coloque el audience configurado en el token de acceso.
• Añade un mapper de pertenencia a grupos con el nombre de claim de token groups, sin rutas completas, para claim_path = "groups".
• El cliente probado también tenía un mapeador de claim client_id codificado de forma fija. Sin uno, consulte Atribución del cliente en el token de acceso de Keycloak.
• Para introspection, añade también un mapeador de audiencia con el ID del propio cliente. Desde la versión 26.6.2, Keycloak indica en la respuesta de introspección que un token está inactivo si no identifica al cliente que realiza la consulta.

Zitadel

• Crea una aplicación web cuyo método de autenticación sea Code (HTTP Basic) o Post. Ambos se probaron. No elijas el método PKCE: crea un cliente sin secreto, y introspection necesita uno. ZeroClaw envía un desafío PKCE con cualquiera de los dos.
• Asigna un rol a cada persona del proyecto. El proyecto probado también tenía activada la inclusión de afirmaciones de roles.
• Establece audience en el ID del proyecto y claim_path = "urn:zitadel:iam:org:project:roles".
• jwks no funciona: los tokens de acceso de Zitadel son opacos o son JWT con tipo JWT.

Authelia

• Registra el cliente con token_endpoint_auth_method: client_secret_post, access_token_signed_response_alg: RS256 y PKCE S256. El valor predeterminado client_secret_basic falla el intercambio de código.
• Establezca el audience del cliente en el audience configurado, con requested_audience_mode: implicit. El valor predeterminado de Authelia, explicit, agrega un audience solo cuando el cliente lo solicita, y ZeroClaw no lo hace.
• Asigna las personas una por una (claim_path = "sub"). La claim de grupos de Authelia necesita un scope groups, que ZeroClaw no solicita.
• introspection no funciona: la respuesta de introspección de Authelia no incluye token_type.
• Authelia sirve su emisor solo por HTTPS, por lo que su certificado debe encadenarse a una autoridad de certificación en la que el demonio confíe (consulta Limitaciones).

Se sabe que aún no funciona

Estas se probaron y ninguna configuración funciona en v0.9.0:

• Dex (v2.46.1). Sus tokens de acceso JWT no tienen typ en el encabezado y contienen el nonce de inicio de sesión, y su introspección marca los tokens con token_use: access_token mientras responde de la misma forma para sus tokens de ID. Aceptarlo permitiría usar un token de ID como token de acceso, por lo que sigue rechazado.
• Authentik (2026.8.5). Su token de acceso es de tipo JWT y lleva el nonce del inicio de sesión, y su respuesta de introspección no tiene token_type.
• Logto (1.45.0, probado con zeroclaw oidc login y no con el panel de control). Sus tokens de acceso para personas son opacos a menos que la solicitud de token indique un resource de RFC 8707, que ZeroClaw todavía no envía. Por eso las personas no pueden iniciar sesión. Un cliente de servicio de Logto que usa client_credentials solo funciona con un recurso de API predeterminado configurado y con la clave de firma de Logto rotada a RSA: su clave predeterminada firma con ES384, que ZeroClaw no verifica.

No probado. Según su documentación, sus documentos de descubrimiento publicados y su código fuente, no se espera que estos funcionen todavía:

• Amazon Cognito. Su documento de descubrimiento no incluye S256, sus tokens de acceso no tienen typ en su encabezado y no tiene endpoint de introspección.
• Ory Hydra (v26.2.0). Sus tokens de acceso JWT están tipados como JWT, y su introspección se sirve solo en su puerto de administración y no aparece en la discovery.

Cualquier otro proveedor, alojado o autoalojado, no ha sido probado. Compruébalo con Qué necesita un proveedor. Los bloqueos habituales son los tokens de acceso que no están tipados como at+jwt, los tokens opacos sin introspección y el documento de descubrimiento que no anuncia S256.

Limitaciones en v0.9.0

• Sin el parámetro resource de RFC 8707. Los proveedores que emiten un token de acceso verificable solo para un recurso con nombre, como Logto, todavía no permiten iniciar sesión a las personas.
• Sin ámbitos configurables. Cada solicitud pide únicamente openid, por lo que las declaraciones de identidad que un proveedor solo entrega para otro ámbito (a menudo groups) nunca llegan.
• Ninguna autoridad de certificación privada por proveedor. El certificado TLS del emisor debe encadenarse a una autoridad de certificación que el daemon ya confíe. No existe ninguna opción para añadir una para un proveedor concreto.
• Los comandos de administración de la puerta de enlace de la CLI no funcionan cuando la puerta de enlace sirve TLS por sí misma (#12091).
  • Los comandos afectados son zeroclaw gateway get-paircode en todas sus formas, zeroclaw sop pending, logs, approve y deny, y zeroclaw gateway restart.
  • Siempre se conectan mediante http:// sin cifrar, por lo que, con [gateway.tls] habilitado, fallan con “Failed to connect to gateway”.
  • zeroclaw gateway restart interpreta ese fallo como «ningún gateway en ejecución» e intenta iniciar un segundo gateway en la misma dirección.
• Una interrupción del proveedor al verificar nuevamente una sesión cierra la sesión de los usuarios del panel (#12096).
  • El gateway vuelve a verificar el token de la sesión iniciada:
    • en cada plazo de revalidación de introspección (revalidation_secs);
    • después de recargar la configuración, en cualquiera de los modos validation;
    • cuando su comprobación de grants falla porque la política cambió (un cambio en [oidc], [users], [permission_profiles] o security.trust_daemon_uid).
  • Si el proveedor no puede ser alcanzado en ese momento, o responde con un error, la sesión termina. Falla de forma segura: no se admite nada que no debería admitirse.
  • El panel informa de que la sesión ha caducado. El gateway registra la causa real como dashboard session ended: verifying its token again failed.
  • Los usuarios vuelven a iniciar sesión una vez que el proveedor esté disponible de nuevo.
  • Sin recargar ni cambiar la política, una sesión jwks no se vuelve a verificar. Mantiene su identidad verificada hasta que expire su token o la sesión, por mucho que el proveedor esté caído.
  • La caché de claves de cinco minutos solo importa para un token que se presenta por primera vez, como una nueva conexión de zerocode. Ese token se verifica con claves en caché durante un máximo de cinco minutos después de la última obtención de claves, y se rechaza después de ese tiempo hasta que el proveedor responda. Una recarga o un cambio de política comienza sin claves en caché.
• Un chat del panel de una cuenta con ámbito dura solo mientras dure su conexión. Recargar la página, salir del chat o una conexión interrumpida finaliza la conversación, y un chat nuevo inicia otra. La transcripción se conserva, pero el panel no puede volver a abrirla. Consulta Inicio de sesión en el panel.