Aller au contenu

Discovery

Comment votre application trouve sa page de connexion sans connaître ni son realm, ni son instance Keycloak, ni son environnement : tout part du nom d'hôte.

ConceptDéveloppeur
Voir en Markdown

Discovery est le service public qui répond à la première question de toute connexion : vers quelle page envoyer cet utilisateur ? Votre application lui envoie le nom d'hôte de sa propre page ; Discovery en déduit l'application, l'environnement et le realm, et renvoie l'adresse de connexion complète. Votre application ne lui transmet jamais l'environnement : c'est le nom d'hôte qui le désigne.

Définition

Discovery est joignable à https://discovery.wakastart.app, sans jeton : l'utilisateur n'est pas encore connecté. Il propose trois façons de résoudre le realm, toutes fondées sur le nom d'hôte du front.

Chargement du schéma…

Pourquoi ça existe

Chaque réseau a un realm par environnement, et chaque environnement son instance Keycloak. Si votre application codait ces valeurs, il faudrait une version par réseau et par environnement. Avec Discovery, le même code fonctionne partout : c'est le nom d'hôte du front, différent pour chaque environnement et chaque organisation, qui porte l'information.

C'est aussi ce nom d'hôte qui désigne les fiches utilisateurs consultées : chaque environnement a son propre référentiel d'utilisateurs, et Discovery ne cherche que dans celui de l'environnement de l'hôte.

Comment ça marche

Par nom d'hôte : une application mono-organisation par adresse

Votre application envoie le nom d'hôte complet de la page, par exemple app.clinique-du-parc.fr, à POST /discover/start-login, avec son adresse de retour et ses paramètres PKCE :

ChampContenu
hostobligatoire : le nom d'hôte complet du front (window.location.host côté navigateur, en-tête Host côté serveur), sans https:// ni chemin, avec le port pour un hôte local (monapp.localhost:3000)
redirectUril'adresse de retour : https://<nom d'hôte>/api/auth/callback
state, noncefacultatifs, recopiés dans l'URL
codeChallenge, codeChallengeMethodle défi PKCE ; seule la méthode S256 est acceptée

Discovery cherche ce nom d'hôte dans les hôtes IAM. Chaque hôte IAM relie un nom d'hôte à une application, un réseau, un client et un environnement (dev, staging ou prod). Il en déduit l'instance Keycloak, le realm de cet environnement et l'identifiant client, et renvoie :

JSON
{
  "keycloakUrl": "https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/auth?client_id=EXAPP1&response_type=code&scope=openid+profile+email+organization&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256"
}

Une adresse correspond à un seul realm. Sans host, la réponse est 400 (invalid_request) ; si aucun hôte IAM ne correspond, 404 avec le message not_found. Les hôtes IAM se lisent dans l'onglet URLs & IAM de chaque environnement.

Un ancien sous-domaine de réseau ou de client (reseau-exemple) reste accepté dans host, mais il ne désigne aucun environnement. Discovery ne le résout que si tous les hôtes IAM actifs de ce réseau, ou de ce client, appartiennent au même environnement ; sinon la réponse est 404. Envoyez toujours le nom d'hôte complet.

Par nom d'hôte et e-mail : plusieurs clients d'un même réseau

Quand un nom d'hôte sert un réseau dont plusieurs clients ont leurs utilisateurs, la même adresse e-mail peut avoir une fiche chez plusieurs d'entre eux. Envoyez alors email en plus de host à POST /discover/start-login. Le nom d'hôte désigne toujours le réseau, l'application et l'environnement ; l'e-mail sert seulement à départager les clients :

  • un seul client correspond : la réponse est la keycloakUrl habituelle ;
  • plusieurs clients correspondent : la réponse est { "ambiguous": true, "candidates": [ … ] }, avec pour chaque client customer_wid, customer_name et customer_subdomain. Faites choisir l'utilisateur, puis rappelez start-login avec le customerWid retenu.

Par e-mail : plusieurs organisations sur un même portail

Quand toutes les organisations partagent une adresse, la page demande d'abord l'e-mail. Votre application appelle :

Texte
GET https://discovery.wakastart.app/discover/email?email=<adresse>&domain=<nom d'hôte du front>

domain est le nom d'hôte du front de votre application (window.location.hostname). Discovery ne renvoie que les comptes de l'application qui a un hôte IAM actif pour ce nom d'hôte, en déduit l'environnement et ne cherche que les fiches de cet environnement. network_realm_id est le realm de cet environnement. La réponse a toujours la forme { "users": [ … ] }, vide si rien ne correspond. Chaque compte donne notamment network_realm_id, app_client_id, customer_name et keycloak_org_alias.

Envoyez domain dès maintenant, sur chaque appel. Sans lui, Discovery ne cherche que dans les fiches de production ; une fois le refus activé, à une date qui sera annoncée, une recherche sans domain ne renverra plus aucun compte.

Votre application construit alors l'URL elle-même, avec l'instance lue dans sa variable KEYCLOAK_URL et les mêmes scopes que Discovery :

Texte
${KEYCLOAK_URL}/realms/${network_realm_id}/protocol/openid-connect/auth?client_id=${app_client_id}&response_type=code&scope=openid+profile+email+organization&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256

Si l'adresse e-mail correspond à plusieurs organisations, présentez la liste (customer_name) et laissez l'utilisateur choisir.

Ce qu'il ne faut pas faire

Attention

  • N'envoyez pas d'appId pour borner la résolution : c'est le nom d'hôte, ou domain, qui désigne l'application. Votre application n'a pas à connaître son propre identifiant client.
  • N'appelez jamais POST /discover/start-login sans host : un appel avec l'e-mail seul n'est plus accepté et répond 400.
  • N'utilisez pas le nom d'hôte d'un autre environnement : un build de dev qui envoie le nom d'hôte de production connecte ses utilisateurs sur les fiches de production. Chaque build lit son nom d'hôte dans window.location, sans le coder en dur.

Bonnes pratiques

  • Appelez Discovery depuis le serveur de votre application.
  • Affichez un message neutre en cas de 404 ou de liste vide, sans dire si l'adresse existe.
  • Ne journalisez pas les adresses e-mail transmises : ce sont des données personnelles.
  • En cas de 429, attendez avant de réessayer.

Exemples

Une application par organisation. Chaque clinique a son adresse : rdv.clinique-du-parc.fr, rdv.saint-louis.fr. Le serveur de l'application envoie à Discovery le nom d'hôte de la requête reçue ; chaque clinique arrive sur sa propre page de connexion, aux couleurs de son réseau.

Un réseau, plusieurs clients. Un groupement de cliniques partage rdv.groupe-sante.fr. Le serveur envoie le nom d'hôte et l'e-mail saisi ; un praticien qui exerce dans deux cliniques du groupement choisit la sienne dans la liste des candidats.

Un portail commun. Un logiciel RH est servi à app.rh-exemple.fr pour tous ses clients. L'écran d'accueil demande l'e-mail, appelle GET /discover/email avec domain=app.rh-exemple.fr, puis envoie l'utilisateur sur le realm de son organisation.

Par nom d'hôte ou par e-mail ?

CritèrePar nom d'hôtePar nom d'hôte et e-mailPar e-mail (/discover/email)
Une adresse par organisation✔ recommandéinutileinutile
Une adresse pour les clients d'un réseaune départage pas les clients✔possible
Une adresse pour plusieurs réseauxne convient pasne convient pas✔
Qui construit l'URL KeycloakDiscoveryDiscoveryvotre application, avec KEYCLOAK_URL
Environnement déduit del'hôte IAM de hostl'hôte IAM de hostl'hôte IAM de domain
Prérequisun hôte IAM actif pour le nom d'hôteun hôte IAM actif pour le nom d'hôteun hôte IAM actif pour le nom d'hôte envoyé dans domain

Pour aller plus loin