Fournisseurs d’identité

ZeroClaw connecte les utilisateurs via OpenID Connect et se montre strict quant au jeton d’accès émis par le fournisseur. La plupart des fournisseurs nécessitent des modifications de configuration, et certains ne fonctionnent pas encore. Cette page répertorie ce dont un fournisseur a besoin, les fournisseurs testés avec les versions préliminaires v0.9.0, ceux dont on sait qu’ils ne fonctionnent pas encore, ainsi que les limitations actuelles. Seuls les fournisseurs listés sous Fournisseurs testés sont connus pour fonctionner. Pour configurer un fournisseur, consultez OIDC et Connexion au tableau de bord.

Le démon vérifie chaque jeton d’accès selon les mêmes règles, qu’il arrive par la connexion au tableau de bord ou depuis un client natif (zerocode, ou un jeton issu de zeroclaw oidc login). Un fournisseur dont le jeton d’accès est refusé l’est donc partout. zeroclaw oidc login et zeroclaw oidc token se contentent de récupérer un jeton et de l’afficher. Une connexion réussie à ce stade ne prouve pas que le démon accepte le jeton.

Ce dont un fournisseur a besoin

• Découverte. <issuer>/.well-known/openid-configuration doit désigner exactement l’issuer configuré, barre oblique finale incluse.
• PKCE avec S256, pour la connexion par navigateur. La connexion au tableau de bord, zeroclaw oidc login --browser et l’enregistrement par navigateur de la passerelle exigent que le document de découverte liste S256 dans code_challenge_methods_supported. Ils refusent un émetteur qui omet ce champ, car un champ absent signifie l’absence de PKCE, et plain n’est jamais accepté. La grant device et client_credentials ne lisent pas ce champ.
• Le grant Device pour zerocode et zeroclaw oidc login. zerocode, ainsi que zeroclaw oidc login sans --browser, se connectent avec le Device Authorization Grant (RFC 8628) ; le fournisseur doit donc le proposer et lister device_authorization_endpoint dans la découverte. La connexion au tableau de bord n’utilise pas ce grant.
• Un jeton d’accès que ZeroClaw peut vérifier, via l’un des deux modes validation :
  • jwks : un jeton d’accès JWT conforme à la RFC 9068, avec l’en-tête typ at+jwt (ou application/at+jwt), signé avec RS256 ou ES256. Il doit contenir iss, aud, exp, iat et jti, et désigner son client dans client_id (pour le jeton d’une personne, azp est accepté à la place). Chaque clé de l’ensemble de clés de l’émetteur doit avoir son propre kid. Un JWT typé JWT ou sans typ, ce que de nombreux fournisseurs émettent par défaut, est refusé, car il ne peut pas être distingué d’un jeton d’identifiant.
  • introspection : introspection de jeton RFC 7662 dont la réponse contient active: true, token_type: Bearer, le audience configuré et un client_id. Le document de découverte doit lister introspection_endpoint. Ce mode nécessite le client_secret de l’entrée.
• Rien qui le désigne comme un autre type de jeton. Dans les deux modes, le jeton (ou la réponse d’introspection) ne doit pas contenir de revendication nonce. Une revendication typ ou token_use, si elle est présente, doit désigner un jeton d’accès : typ Bearer ou at+jwt, et token_use exactement access.
• Le public visé. L’aud du jeton d’accès doit contenir l’audience configurée.
• Rôles ou groupes sans scope supplémentaire. ZeroClaw ne demande que le scope openid, donc les valeurs à claim_path doivent figurer dans le jeton d’accès (ou dans la réponse d’introspection) par défaut. Sinon, associez les personnes une à une, par exemple avec claim_path = "sub".
• Authentification du client selon la requête. L’échange du code d’autorisation (connexion au tableau de bord, zeroclaw oidc login --browser et l’enrôlement par navigateur de la passerelle) envoie le client_secret dans le corps du formulaire (client_secret_post). L’introspection, le flux device et client_credentials l’envoient avec HTTP Basic (client_secret_basic). Un fournisseur qui n’accepte que la méthode enregistrée pour un client peut nécessiter une entrée [oidc.<alias>] distincte et un client distinct pour le flux device ou client_credentials. La connexion au tableau de bord avec introspection ne peut pas être séparée de cette manière : un même client effectue à la fois l’échange et l’appel d’introspection, il doit donc accepter les deux méthodes.
• Une durée de vie de jeton de session de travail, par exemple de une à huit heures. Le tableau de bord n’utilise pas de jetons d’actualisation ; une session prend fin lorsque son jeton d’accès expire.

Fournisseurs testés

Chaque fournisseur ci-dessous a connecté un compte administrateur et un compte membre via la connexion au tableau de bord, avec les profils auxquels leurs revendications sont associées. Sur le chemin bearer, le jeton d’identité, le jeton de rafraîchissement et un jeton d’accès émis pour un autre de ses clients, tous issus du même fournisseur, ont chacun été refusés. Les tests ont été exécutés sur des versions préliminaires v0.9.0 en octobre et novembre 2026. Keycloak a été testé avec la passerelle en HTTP simple et sur son propre écouteur TLS, ainsi qu’avec zerocode et zeroclaw oidc login. Zitadel et Authelia n’ont été testés qu’avec la connexion au tableau de bord.

Keycloak

• Activez l’en-tête de jeton d’accès RFC 9068 du client (access.token.header.type.rfc9068 = true), exigez PKCE S256 et définissez une durée de vie du jeton d’accès comprise entre une et huit heures. La valeur par défaut de Keycloak est de cinq minutes.
• Ajoutez un mappeur d’audience qui place le audience configuré dans le jeton d’accès.
• Ajoutez un mappeur d’appartenance à un groupe avec le nom de revendication de jeton groups, sans chemins complets, pour claim_path = "groups".
• Le client testé avait également un mappeur de claim client_id codé en dur. Sans celui-ci, voir Attribution du client dans le jeton d’accès Keycloak.
• Pour introspection, ajoutez aussi un mappage d’audience contenant l’ID du client lui-même. À partir de la version 26.6.2, Keycloak indique dans la réponse d’introspection qu’un jeton est inactif s’il ne désigne pas le client qui effectue la demande.

Zitadel

• Créez une application Web dont la méthode d’authentification est Code (HTTP Basic) ou Post. Les deux ont été testés. Ne choisissez pas la méthode PKCE : elle crée un client sans secret, or introspection en nécessite un. ZeroClaw envoie un défi PKCE avec l’une ou l’autre.
• Attribuez un rôle à chaque personne du projet. Le projet testé avait également l’assertion de rôle activée.
• Définissez audience sur l’ID du projet et claim_path = "urn:zitadel:iam:org:project:roles".
• jwks ne fonctionne pas : les jetons d’accès de Zitadel sont opaques, ou sont des JWT de type JWT.

Authelia

• Enregistrez le client avec token_endpoint_auth_method: client_secret_post, access_token_signed_response_alg: RS256 et PKCE S256. La valeur par défaut client_secret_basic fait échouer l’échange de code.
• Définissez l’audience du client sur la valeur configurée audience, avec requested_audience_mode: implicit. Le mode par défaut d’Authelia, explicit, n’ajoute une audience que lorsque le client en demande une, ce que ZeroClaw ne fait pas.
• Associer les personnes une à une (claim_path = "sub"). La revendication de groupe d’Authelia nécessite un scope groups, que ZeroClaw ne demande pas.
• introspection ne fonctionne pas : la réponse d’introspection d’Authelia ne contient pas de token_type.
• Authelia sert son émetteur uniquement via HTTPS, son certificat doit donc remonter jusqu’à une autorité de certification que le démon considère comme fiable (voir Limitations).

Connu pour ne pas encore fonctionner

Ceux-ci ont été testés et aucune configuration ne fonctionne dans la v0.9.0 :

• Dex (v2.46.1). Ses jetons d’accès JWT n’ont pas de typ dans leur en-tête et portent le nonce de connexion, et son introspection marque les jetons token_use: access_token tout en répondant de la même façon pour ses jetons ID. L’accepter permettrait d’utiliser un jeton ID comme jeton d’accès, donc il reste refusé.
• Authentik (2026.8.5). Son jeton d’accès est de type JWT et contient le nonce de connexion, et sa réponse d’introspection ne contient pas de token_type.
• Logto (1.45.0, testé avec zeroclaw oidc login et non avec le tableau de bord). Ses jetons d’accès pour les utilisateurs sont opaques, sauf si la requête de jeton indique une ressource RFC 8707 resource, que ZeroClaw n’envoie pas encore. Les utilisateurs ne peuvent donc pas se connecter. Un client de service Logto utilisant client_credentials ne fonctionne qu’avec une ressource API par défaut configurée et une clé de signature Logto migrée vers RSA : sa clé par défaut signe en ES384, que ZeroClaw ne vérifie pas.

Non testé. D’après leur documentation, leurs documents de découverte publiés et leur code source, ceux-ci ne devraient pas encore fonctionner :

• Amazon Cognito. Son document de découverte ne mentionne pas S256, ses jetons d’accès n’ont pas de typ dans leur en-tête, et il ne dispose d’aucun point de terminaison d’introspection.
• Ory Hydra (v26.2.0). Ses jetons d’accès JWT sont de type JWT, et son service d’introspection n’est disponible que sur son port d’administration et ne figure pas dans le document de découverte.

Tout autre fournisseur, hébergé ou auto-hébergé, n’a pas été testé. Vérifiez-le par rapport à Ce dont un fournisseur a besoin. Les principaux points bloquants sont les jetons d’accès dont le type n’est pas at+jwt, les jetons opaques sans introspection, et une découverte qui n’annonce pas S256.

Limites dans la v0.9.0

• Aucun paramètre resource de la RFC 8707. Les fournisseurs qui n’émettent un jeton d’accès vérifiable que pour une ressource nommée, comme Logto, ne peuvent pas encore authentifier les utilisateurs.
• Aucune portée configurable. Chaque requête demande uniquement openid, donc les revendications qu’un fournisseur ne transmet que pour une autre portée (souvent groups) n’arrivent jamais.
• Aucune autorité de certification privée par fournisseur. Le certificat TLS de l’émetteur doit remonter jusqu’à une autorité de certification que le démon approuve déjà. Il n’existe aucun paramètre permettant d’en ajouter une pour un fournisseur donné.
• Les commandes d’administration de la passerelle de la CLI ne fonctionnent pas lorsque la passerelle sert elle-même le TLS (#12091).
  • Les commandes concernées sont zeroclaw gateway get-paircode sous toutes ses formes, zeroclaw sop pending, logs, approve et deny, ainsi que zeroclaw gateway restart.
  • Ils se connectent toujours via http:// en clair, donc avec [gateway.tls] activé, la connexion échoue avec « Failed to connect to gateway ».
  • zeroclaw gateway restart interprète cet échec comme « aucune passerelle en cours d’exécution » et tente de démarrer une deuxième passerelle à la même adresse.
• Une panne du fournisseur lors de la nouvelle vérification d’une session déconnecte les utilisateurs du tableau de bord (#12096).
  • La passerelle vérifie à nouveau le jeton de la session ouverte :
    • à chaque échéance de revalidation d’introspection (revalidation_secs);
    • après un rechargement de la configuration, dans l’un ou l’autre des modes validation ;
    • lorsque sa vérification des autorisations échoue parce que la politique a changé (une modification de [oidc], [users], [permission_profiles] ou security.trust_daemon_uid).
  • Si le fournisseur est injoignable à ce moment-là, ou répond par une erreur, la session se termine. Elle échoue en mode sécurisé : rien n’est admis qui ne devrait pas l’être.
  • Le tableau de bord signale la session comme expirée. La passerelle consigne la cause réelle comme dashboard session ended: verifying its token again failed.
  • Les utilisateurs se reconnectent une fois que le fournisseur est de nouveau disponible.
  • Sans rechargement ni modification de politique, une session jwks n’est pas revérifiée. Elle conserve son identité vérifiée jusqu’à l’expiration de son jeton ou de la session, quelle que soit la durée d’indisponibilité du fournisseur.
  • Le cache de clés de cinq minutes ne concerne que les jetons présentés pour la première fois, comme une nouvelle connexion zerocode. Ce jeton est vérifié à partir des clés en cache pendant cinq minutes au maximum après la dernière récupération des clés, puis refusé jusqu’à ce que le fournisseur réponde. Un rechargement ou un changement de politique repart sans aucune clé en cache.
• Le chat du tableau de bord d’un compte à portée limitée ne dure que le temps de sa connexion. Recharger la page, quitter le chat ou une connexion interrompue met fin à la conversation, et un nouveau chat en démarre une autre. La transcription est conservée, mais le tableau de bord ne peut pas la rouvrir. Voir Connexion au tableau de bord.