Skip to content

Discovery

Obtenir l'adresse de connexion Keycloak d'une wakapp à partir du nom d'hôte de son front, seul ou avec l'e-mail de l'utilisateur.

ReferenceDeveloper

This page has not been translated yet and is shown in French.

Discovery indique à votre application vers quel realm Keycloak envoyer un utilisateur. Votre application ne connaît jamais son realm : elle envoie à Discovery le nom d'hôte de son propre front, qui désigne à la fois l'application et l'environnement. L'environnement n'est jamais un paramètre : Discovery le déduit de l'hôte IAM qui porte ce nom d'hôte, et ne cherche que dans les fiches utilisateurs de cet environnement. Le service est public et s'appelle sans jeton, puisque l'utilisateur n'est pas encore connecté.

URL de base : https://discovery.wakastart.app

L'instance Keycloak, elle, dépend de l'environnement : elle est lue dans la keycloakUrl renvoyée par Discovery, ou dans la variable KEYCLOAK_URL de votre application, posée par environnement. Le fonctionnement est expliqué dans Discovery.

Choisir le bon endpoint

Votre casEndpointCe que votre application envoie
Un nom d'hôte correspond à un seul client (cas le plus courant)POST /discover/start-loginLe nom d'hôte complet de la page, par exemple mon-app.exemple.fr
Plusieurs clients d'un même réseau partagent le nom d'hôtePOST /discover/start-loginLe nom d'hôte complet et l'e-mail saisi
Un portail commun à plusieurs réseaux, ou un affichage avant connexionGET /discover/emailL'e-mail saisi et le nom d'hôte du front dans domain

L'objet compte découvert

Renvoyé par GET /discover/email, un élément par compte trouvé.

ChampTypeDescription
user_emailchaîneE-mail du compte
customer_wid, customer_namechaîneIdentifiant court et nom du client du compte
customer_subdomainchaîne ou nullSous-domaine du client
network_wid, network_namechaîneIdentifiant court et nom du réseau
network_subdomainchaîne ou nullSous-domaine du réseau
network_realm_idchaîne ou nullNom du realm Keycloak du réseau dans l'environnement de l'hôte IAM désigné par domain, à placer dans l'URL de connexion
partner_wid, partner_namechaîneIdentifiant court et nom du propriétaire de l'application
idp_id, idp_name, idp_typechaîne ou nullFournisseur d'identité SSO du client s'il en a un ; idp_type vaut OIDC ou SAML
keycloak_org_aliaschaîne ou nullAlias de l'organisation Keycloak du client, égal à son WID
app_wid, app_namechaîneIdentifiant court et nom de l'application
app_client_idchaîneIdentifiant du client Keycloak de l'application, à placer dans l'URL de connexion
app_url_frontchaîne ou nullURL du front de l'application
theme_name, theme_css_path, theme_css_vars_light, theme_css_vars_darkchaîne, objet ou nullThème applicable, résolu du client vers le réseau puis l'application
branding_logo_light, branding_logo_dark, branding_bg_lightchaîne ou nullLogo et fond de l'application. Les deux champs de logo portent la même image
branding_favicon, branding_bg_darknullRéservés, toujours null
default_langchaîne ou nullLangue par défaut de l'application

Obtenir l'adresse de connexion par nom d'hôte

POST/discover/start-login

Public. Renvoie l'URL d'autorisation Keycloak complète, prête à suivre : instance, realm, client, adresse de retour et paramètres PKCE compris.

Corps

ChampTypeObligatoireContraintesDescription
hostchaîneouinon vide, 253 caractères au plusNom d'hôte complet du front, sans schéma ni chemin, tel que le navigateur l'a demandé (window.location.host, ou en-tête Host de la requête reçue par votre serveur). Il désigne l'application, le réseau et l'environnement. mon-app.exemple.fr est résolu ; un fragment comme mon-app ne l'est pas
emailchaînenone-mail valide, 254 caractères au plusAdresse saisie par l'utilisateur, pour départager plusieurs clients du réseau désigné par host. Elle ne sert jamais à trouver le réseau
customerWidchaînenon6 caractères au plusClient choisi par l'utilisateur parmi les candidats d'une réponse ambiguë. Inutile au premier appel
redirectUrichaîneoui2 048 caractères au plusAdresse de retour après connexion, recopiée telle quelle dans l'URL. Elle doit être déclarée pour cet hôte, sinon Keycloak la refuse
statechaînenon256 caractères au plusValeur aléatoire contre la falsification de requête, à revérifier au retour
noncechaînenon256 caractères au plusValeur OIDC contre le rejeu
codeChallengechaînenon128 caractères au plusEmpreinte PKCE : base64url(SHA-256(code_verifier))
codeChallengeMethodchaînenonS256 uniquementMéthode PKCE. Vaut S256 si codeChallenge est fourni
Bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "mon-app.exemple.fr",
    "redirectUri": "https://mon-app.exemple.fr/api/auth/callback",
    "state": "q8XGm2Vt0oKc4bQ1",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "codeChallengeMethod": "S256"
  }'

Appelez Discovery depuis le serveur de votre application : le service n'accepte pas les appels croisés d'un navigateur. Par exemple, dans la route /login de votre serveur :

TypeScript
// host : en-tête Host de la requête reçue, par exemple "mon-app.exemple.fr"
const response = await fetch("https://discovery.wakastart.app/discover/start-login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    host,
    redirectUri: `https://${host}/api/auth/callback`,
    state,
    codeChallenge,
    codeChallengeMethod: "S256",
  }),
});
if (response.status === 404) throw new Error("Hôte inconnu de Discovery");
const { keycloakUrl } = (await response.json()) as { keycloakUrl: string };
// redirigez ensuite le navigateur vers keycloakUrl (statut 302)

Réponse 200

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=https%3A%2F%2Fmon-app.exemple.fr%2Fapi%2Fauth%2Fcallback&state=q8XGm2Vt0oKc4bQ1&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256"
}

L'origine de l'URL désigne l'instance Keycloak de l'environnement auquel l'hôte est rattaché. Le chemin porte le realm, le paramètre client_id l'identifiant de votre application : conservez-les pour échanger le code contre des jetons à l'adresse <origine>/realms/<realm>/protocol/openid-connect/token.

Le scope demandé est toujours openid profile email organization : le scope organization permet à l'utilisateur de choisir son organisation dans Keycloak s'il en a plusieurs.

Un ancien sous-domaine de réseau ou de client (reseau-exemple) reste accepté dans host, en repli. Comme il ne désigne aucun environnement, Discovery le déduit des hôtes IAM actifs du réseau ou du client, et ne le résout que s'ils appartiennent tous au même environnement. Préférez toujours le nom d'hôte complet.

Erreurs

StatutMessageCause
400invalid_request: host is required (non-empty string, max 253 chars)host absent ou vide. Un appel avec l'e-mail seul n'est plus accepté
400Tableau de messages de validationAutre champ absent, inconnu ou hors contrainte
404not_foundAucun hôte IAM actif ne correspond au nom d'hôte ; sous-domaine de repli dont les hôtes IAM actifs couvrent plusieurs environnements, ou qui n'en a aucun ; realm de l'environnement dev ou staging pas encore créé pour le réseau ; customerWid qui ne fait pas partie des candidats. La réponse prend toujours le même temps
429ThrottlerException: Too Many RequestsLimite de débit atteinte

Départager plusieurs clients par e-mail

Même endpoint, POST /discover/start-login, avec email en plus de host. Utilisez-le quand un même nom d'hôte sert plusieurs clients d'un réseau : une adresse peut alors avoir une fiche chez plusieurs d'entre eux. Le nom d'hôte reste obligatoire et désigne toujours le réseau, l'application et l'environnement.

Bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "rdv.groupe-exemple.fr",
    "email": "alice@clinique-exemple.fr",
    "redirectUri": "https://rdv.groupe-exemple.fr/api/auth/callback",
    "state": "q8XGm2Vt0oKc4bQ1",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "codeChallengeMethod": "S256"
  }'

Si l'adresse correspond à un seul client, ou à aucun, la réponse est la keycloakUrl habituelle. Si elle correspond à plusieurs clients, la réponse 200 liste les candidats :

JSON
{
  "ambiguous": true,
  "candidates": [
    { "customer_wid": "EXCLI1", "customer_name": "Clinique Exemple", "customer_subdomain": null },
    { "customer_wid": "EXCLI2", "customer_name": "Centre Exemple", "customer_subdomain": "centre-exemple" }
  ]
}

Présentez la liste à l'utilisateur, puis rappelez start-login avec les mêmes champs et le customerWid choisi. Un customerWid qui ne figure pas parmi les candidats de cette adresse répond 404.

TypeScript
const body = { host, email, redirectUri, state, codeChallenge, codeChallengeMethod: "S256" };
let result = await startLogin(body); // POST /discover/start-login
if ("ambiguous" in result) {
  const customerWid = await askUserToChoose(result.candidates); // votre écran de choix
  result = await startLogin({ ...body, customerWid });
}
// redirigez ensuite le navigateur vers result.keycloakUrl

Retrouver les comptes d'un e-mail pour votre front

GET/discover/email

Public. Renvoie les comptes rattachés à une adresse e-mail, limités à l'application dont le front porte le nom d'hôte domain. Votre application assemble ensuite elle-même l'URL de connexion.

Paramètres de requête

ParamètreTypeObligatoireContraintesDescription
emailchaîneouiE-mail valide, 254 caractères au plusAdresse saisie par l'utilisateur
domainchaîneà envoyer toujours253 caractères au plusNom d'hôte du front de votre application (window.location.hostname)

Discovery cherche l'hôte IAM actif qui porte domain, sans tenir compte de la casse, du schéma http(s)://, du port ni du / final. Il en déduit l'application et l'environnement, ne renvoie que les comptes de cette application dans cet environnement, et place dans network_realm_id le realm de cet environnement. Un domain qui ne correspond à aucun hôte IAM de l'application renvoie { "users": [] }, comme une adresse inconnue : Discovery ne se rabat jamais sur la production.

Bash
curl -s "https://discovery.wakastart.app/discover/email?email=alice%40clinique-exemple.fr&domain=mon-app.exemple.fr"

Réponse 200

JSON
{
  "users": [
    {
      "user_email": "alice@clinique-exemple.fr",
      "customer_wid": "EXCLI1",
      "customer_name": "Clinique Exemple",
      "customer_subdomain": null,
      "network_wid": "EXNET1",
      "network_name": "Réseau Exemple",
      "network_subdomain": "reseau-exemple",
      "network_realm_id": "realm-EXNET1",
      "partner_wid": "EXPRT1",
      "partner_name": "Éditeur Exemple",
      "idp_id": null,
      "idp_name": null,
      "idp_type": null,
      "keycloak_org_alias": "EXCLI1",
      "app_wid": "EXAPP1",
      "app_name": "Mon App",
      "app_client_id": "EXAPP1",
      "app_url_front": "https://mon-app.exemple.fr",
      "theme_name": null,
      "theme_css_path": null,
      "theme_css_vars_light": null,
      "theme_css_vars_dark": null,
      "branding_logo_light": null,
      "branding_logo_dark": null,
      "branding_favicon": null,
      "branding_bg_light": null,
      "branding_bg_dark": null,
      "default_lang": "fr"
    }
  ]
}

La forme de la réponse est la même, que l'adresse existe ou non : { "users": [] } signifie qu'aucun compte ne correspond pour ce front. Affichez alors un message neutre, comme « Vérifiez votre adresse et réessayez », jamais « Cette adresse n'existe pas ».

Avec un compte, votre application construit l'URL de connexion à partir de sa variable KEYCLOAK_URL :

TypeScript
const [account] = users; // proposez un choix à l'utilisateur s'il y en a plusieurs
const authUrl = new URL(
  `${process.env.KEYCLOAK_URL}/realms/${account.network_realm_id}/protocol/openid-connect/auth`,
);
authUrl.search = new URLSearchParams({
  client_id: account.app_client_id,
  response_type: "code",
  scope: "openid profile email organization",
  redirect_uri: "https://mon-app.exemple.fr/api/auth/callback",
  state,
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
}).toString();

Important

Envoyez domain dès maintenant. Une recherche sans domain ne porte aujourd'hui que sur les fiches de production : vos builds de dev et de staging n'y trouvent aucun de leurs utilisateurs. À une date qui sera annoncée, elle sera refusée et renverra { "users": [] } quelle que soit l'adresse. Vérifiez aussi que le nom d'hôte de chaque environnement est déclaré comme hôte IAM de l'application.

Erreurs

StatutMessageCause
400email must be an emailAdresse absente ou mal formée
429ThrottlerException: Too Many RequestsLimite de débit atteinte

Depuis l'API publique

GET/api/discovery/email

L'API publique (https://api.wakastart.app/api) relaie la même recherche, sans jeton, avec les mêmes paramètres email et domain et la même réponse. domain peut y être un nom d'hôte ou une URL complète : l'API le ramène au nom d'hôte avant de le transmettre. Une valeur impossible à analyser répond 400 domain must be a valid host name. Cette route est limitée à 10 requêtes par minute.

Bash
curl -s "https://api.wakastart.app/api/discovery/email?email=alice%40clinique-exemple.fr&domain=https%3A%2F%2Fmon-app.exemple.fr"

Lire la personnalisation d'un sous-domaine

GET/discover/subdomain

Public. Renvoie le réseau ou le client qui porte un sous-domaine, avec son thème et ses visuels, pour habiller une page de connexion avant toute authentification.

ParamètreTypeObligatoireContraintes
subdomainchaîneoui63 caractères au plus, lettres, chiffres et tirets, sans tiret en début ni en fin
Bash
curl -s "https://discovery.wakastart.app/discover/subdomain?subdomain=reseau-exemple"

Réponse 200

JSON
{
  "subdomain": "reseau-exemple",
  "result": {
    "type": "network",
    "network_wid": "EXNET1",
    "network_name": "Réseau Exemple",
    "network_subdomain": "reseau-exemple",
    "network_realm_id": "realm-EXNET1",
    "partner_wid": "EXPRT1",
    "partner_name": "Éditeur Exemple",
    "customer_wid": null,
    "customer_name": null,
    "customer_subdomain": null,
    "app_wid": "EXAPP1",
    "app_name": "Mon App",
    "app_client_id": "EXAPP1",
    "app_url_front": "https://mon-app.exemple.fr",
    "theme_name": null,
    "theme_css_path": null,
    "theme_css_vars_light": null,
    "theme_css_vars_dark": null,
    "branding_logo_light": null,
    "branding_logo_dark": null,
    "branding_favicon": null,
    "branding_bg_light": null,
    "branding_bg_dark": null,
    "default_lang": "fr"
  }
}

type vaut network ou customer. Un sous-domaine ne porte pas d'environnement : Discovery le déduit des hôtes IAM actifs du réseau ou du client, et network_realm_id est le realm de cet environnement.

La réponse est { "subdomain": "…", "result": null }, avec le statut 200, dans chacun de ces cas :

  • le sous-domaine est inconnu ;
  • le réseau ou le client n'a aucun hôte IAM actif ;
  • ses hôtes IAM actifs couvrent plusieurs environnements, par exemple dev et prod ;
  • l'environnement déduit est dev ou staging, et le realm de cet environnement n'existe pas encore pour le réseau.

Discovery ne se rabat jamais sur le realm de production. Traitez result: null comme « contexte indisponible » : affichez la page de connexion générique et passez par start-login avec le nom d'hôte complet.

Erreurs : 400 subdomain must contain only alphanumeric characters and hyphens.

Ce qu'il ne faut pas faire

  • N'envoyez jamais d'identifiant d'application pour orienter la résolution : c'est l'URL de votre front qui désigne l'application. Votre application n'a pas à connaître son propre identifiant de client.
  • N'appelez jamais POST /discover/start-login sans host, même avec un e-mail : la réponse est 400. L'e-mail ne sert qu'à départager les clients du réseau désigné par le nom d'hôte.
  • N'envoyez 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. Lisez-le dans window.location, sans le coder en dur.
  • N'envoyez pas un sous-domaine extrait quand vous avez le nom d'hôte complet : c'est le nom d'hôte qui désigne l'environnement.
  • Ne codez pas d'URL Keycloak en dur : lisez-la dans la réponse de Discovery ou dans KEYCLOAK_URL.
  • Ne réessayez pas automatiquement sur 404 : la réponse ne changera pas tant que l'hôte n'est pas déclaré.

Limites de débit

Discovery limite les requêtes par adresse IP, sur l'ensemble de ses endpoints :

FenêtreLimite
1 minute5 requêtes
10 minutes20 requêtes
1 heure100 requêtes

Appelez start-login une seule fois par tentative de connexion. Ne journalisez pas les e-mails envoyés à Discovery : ce sont des données personnelles.