Concepts

Applications

Une application est une page de connexion avec son propre nom d’hôte, émetteur, identifiant client, clés de signature, image de marque, méthodes de connexion, utilisateurs et forfait. Utilisez une application par produit et par environnement : une application de test et une application en direct sont distinctes, avec des utilisateurs distincts.

Clients confidentiels et publics

Les applications sont confidentielles par défaut : en créer une renvoie un secret client, affiché une seule fois, que votre serveur envoie au point de jeton (client_secret_basic ou client_secret_post). Remplacez-le avec POST /v1/auth-apps/:id/rotate-secret; l’ancien secret cesse de fonctionner immédiatement.

Les applications monopages et mobiles qui ne peuvent pas garder un secret sont des clients publics (confidential: false) : elles n’ont pas de secret et s’appuient sur PKCE seul. Ce choix se fait à la création de l’application.

URI de redirection

Les URI de redirection sont inscrits par application et doivent correspondre exactement : HTTPS, sans caractère générique, fragment ni identifiants. http://localhost n’est permis que sur les applications de test. Une application a au plus 10 URI de redirection et 10 URI de redirection après déconnexion, et un PATCH remplace chaque liste au complet. Un URI qui enfreint ces règles renvoie AUTH_APP_REDIRECT_INVALID.

Points de terminaison

Chaque point de terminaison se trouve sur le nom d’hôte de votre application, et l’émetteur est https:// suivi de ce nom d’hôte. La découverte les énumère :

curl https://login.acme.ca/.well-known/openid-configuration
{
  "issuer": "https://login.acme.ca",
  "authorization_endpoint": "https://login.acme.ca/authorize",
  "token_endpoint": "https://login.acme.ca/token",
  "userinfo_endpoint": "https://login.acme.ca/userinfo",
  "jwks_uri": "https://login.acme.ca/.well-known/jwks.json",
  "end_session_endpoint": "https://login.acme.ca/logout",
  "revocation_endpoint": "https://login.acme.ca/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "ui_locales_supported": ["en", "fr"]
}

Seul le flux de code d’autorisation est pris en charge. PKCE avec S256 est exigé de chaque client, tout comme state et nonce. Il n’y a ni flux implicite ni flux hybride, et les jetons n’apparaissent jamais dans les URL. /authorize accepte aussi prompt (login ou none), max_age, login_hint et ui_locales (en ou fr); sans ce dernier, la page suit la langue du navigateur, et son bouton EN/FR a préséance sur les deux.

Jetons et clés

Les jetons d’identité et d’accès sont des JWT signés en ES256 par les clés propres à l’application, publiées à /.well-known/jwks.json. Leur aud est votre identifiant client. Les jetons d’accès durent 10 minutes; une session HonkIO dure au plus 30 jours, et aucun jeton ne lui survit. Les jetons de renouvellement sont opaques, changent à chaque usage, et réutiliser un ancien jeton révoque toute la session.

Pour accepter un jeton d’accès dans votre propre API, vérifiez sa signature avec le JWKS, son iss, son aud et son expiration. Les clés sont remplacées avec un chevauchement : une ancienne clé reste dans le JWKS jusqu’à l’expiration de tous les jetons qu’elle a signés. Mettre le JWKS en cache, comme le font les bibliothèques JOSE, est donc sûr et permet de vérifier les jetons pendant une panne de HonkIO.

Portées et revendications

Demandez des portées dans la requête d’autorisation. Chacune ajoute des revendications au jeton d’identité et à userinfo :

amr indique comment l’utilisateur s’est connecté : otp pour un code ou un lien par courriel, sms pour un code par texto, hwk et user pour une clé d’accès, plus mfa une fois les deux étapes faites, et acr vaut alors urn:honkio:acr:2fa. Quand l’utilisateur s’est connecté à une organisation, les jetons d’identité et d’accès portent aussi org_id, org_slug et org_role, tels qu’au moment de l’émission.

{
  "iss": "https://login.acme.ca",
  "aud": "hka_xxxxxxxxxxxx",
  "sub": "usr_clxxxuserxxxxxxxxxxxxxx",
  "email": "ada@example.com",
  "email_verified": true,
  "amr": ["hwk", "user"],
  "auth_time": 1793632445,
  "sid": "ses_xxxxxxxxxxxxxxxxxxxxxx",
  "nonce": "…",
  "org_id": "org_clxxxorgxxxxxxxxxxxxxxx",
  "org_slug": "northwind",
  "org_role": "admin",
  "iat": 1793632445,
  "exp": 1793633045
}

Sessions et pannes

Une panne ne doit jamais déconnecter les personnes déjà connectées. HonkIO n’a pas de région de relève : votre application garde donc les sessions de son côté, selon une seule règle :

• Gardez la session quand HonkIO est injoignable : erreur réseau, délai dépassé ou erreur 5xx au renouvellement. Gardez-la seulement jusqu’à 24 heures après l’expiration du jeton d’accès, et réessayez de temps à autre.
• Terminez la session immédiatement quand HonkIO répond et refuse le renouvellement (invalid_grant) : la session a été révoquée ou réutilisée, ou l’utilisateur a été bloqué, supprimé ou retiré de l’organisation.

Chaque guide de démarrage suit cette règle. Les nouvelles connexions exigent que HonkIO fonctionne. Pour apprendre une révocation avant le prochain renouvellement, abonnez-vous à session.revoked et user.blocked (événements webhook).

Déconnexion

Envoyez le navigateur au point de fin de session, /logout, avec id_token_hint (ou client_id) et un post_logout_redirect_uri inscrit; state revient tel quel. Utilisez une navigation de premier niveau (un GET), comme les guides le font par redirection : un POST intersite ne transporte pas le témoin de session de HonkIO et ne peut donc pas mettre fin à la session HonkIO. Pour révoquer un jeton de renouvellement depuis votre serveur, envoyez-le par POST à /revoke.