Référence de l'authentification
Réponses de Discovery, contenu du jeton Keycloak et du jeton enrichi, réponse de /api/me, valeurs par défaut et opérations de l'authentification.
Cette page décrit les objets que votre application manipule pendant la connexion. Le détail de chaque endpoint (paramètres, codes de retour) est dans la référence API.
URL de base
| Service | URL |
|---|---|
| Discovery | https://discovery.wakastart.app |
| API publique | https://api.wakastart.app/api |
| Keycloak prod | https://auth.wakastart.app |
| Keycloak staging | https://auth-staging.wakastart.app |
| Keycloak dev | https://auth-dev.wakastart.app |
| Adresse de retour d'un hôte IAM web | https://<nom d'hôte>/api/auth/callback |
Corps de start-login
Corps de POST /discover/start-login, pour la connexion par nom d'hôte, seul ou avec l'e-mail de l'utilisateur.
| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
host | string | oui | non vide, 253 caractères au plus | Nom d'hôte exact du front, sans schéma ni chemin ; avec le port pour un hôte local. Il désigne l'application et l'environnement |
email | string | non | e-mail valide | Adresse saisie, pour départager plusieurs clients du réseau de l'hôte |
customerWid | string | non | 6 caractères au plus | Client choisi parmi les candidats d'une réponse ambiguë |
redirectUri | string | oui | 2 048 caractères au plus | Recopiée telle quelle dans l'URL ; Keycloak la compare aux redirect URIs déclarées |
state | string | non | 256 caractères au plus | Valeur anti-falsification, recopiée |
nonce | string | non | 256 caractères au plus | Recopiée dans l'id_token |
codeChallenge | string | non | 128 caractères au plus | Empreinte PKCE |
codeChallengeMethod | string | non | S256 seul | Méthode PKCE |
Un champ inconnu est refusé avec une erreur 400. N'envoyez email que si plusieurs clients partagent le nom d'hôte, et customerWid qu'après une réponse ambiguë (voir Flux de connexion).
Réponse 200 :
{
"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=…&nonce=…&code_challenge=…&code_challenge_method=S256"
}Élément de keycloakUrl | Où le lire |
|---|---|
| Instance | Origine de l'URL |
Émetteur (iss des jetons) | Origine + /realms/<realm> |
| Realm | Segment qui suit /realms/ |
| Identifiant client | Paramètre client_id |
| Scopes | openid profile email organization |
Avec email, si l'adresse a une fiche chez plusieurs clients du réseau, la réponse 200 est à la place { "ambiguous": true, "candidates": [ { "customer_wid", "customer_name", "customer_subdomain" } ] }.
Compte renvoyé par Discovery
Chaque élément du tableau users de GET /discover/email. Les comptes renvoyés sont ceux de l'application et de l'environnement de l'hôte IAM désigné par domain.
| Champ | Description |
|---|---|
user_email | Adresse du compte, en minuscules |
customer_wid, customer_name, customer_subdomain | Client auquel appartient le compte |
network_wid, network_name, network_subdomain | Réseau du client |
network_realm_id | Realm Keycloak du réseau dans l'environnement de l'hôte, à utiliser pour construire l'URL d'autorisation |
partner_wid, partner_name | Propriétaire de l'application |
idp_id, idp_name, idp_type | Fournisseur d'identité actif du client pour le domaine de l'adresse (OIDC ou SAML), sinon null |
keycloak_org_alias | Alias de l'organisation Keycloak du client (son identifiant court), sinon null |
app_wid, app_name, app_client_id, app_url_front | Application ; app_client_id est l'identifiant client Keycloak |
theme_name, theme_css_path, theme_css_vars_light, theme_css_vars_dark | Thème résolu (client, puis réseau, puis application) |
branding_logo_light, branding_logo_dark, branding_bg_light | Visuels pour habiller la page de choix |
default_lang | Langue par défaut |
Jeton Keycloak
Claims utiles du jeton d'accès émis par l'instance de l'environnement (JWT signé RS256, clés sur <émetteur>/protocol/openid-connect/certs).
| Claim | Description |
|---|---|
iss | Émetteur : https://<instance>/realms/<realm> |
azp | Identifiant client de votre application ; l'API publique refuse un jeton émis pour une autre application |
sub | Identifiant du compte sur cette instance |
email, given_name, family_name | Identité de l'utilisateur ; email est obligatoire pour obtenir un contexte Wakastart |
wenv | Environnement de la session : prod, staging ou dev |
organization | Organisation Keycloak de l'utilisateur, qui désigne son client Wakastart |
exp, iat | Expiration et émission, en secondes |
Jeton enrichi
Obtenu par POST /api/auth/enrich avec le jeton Keycloak en Authorization: Bearer. Réponse : { "token": "<JWT>", "payload": { … } }, où payload est le contenu décodé du jeton.
| Claim | Description |
|---|---|
iss | wakastart-token-service |
sub, keycloakId | Identifiant du compte Keycloak |
email, given_name, family_name | Identité |
azp, aud | Repris du jeton Keycloak |
wadl | Niveau d'administration : PARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN, USER ou NONE |
pid, nid, cid, aid, uid | Identifiants courts du propriétaire, du réseau, du client, de l'application et de l'utilisateur |
wthm, wlng | Thème et langue résolus |
woid | Organisation Keycloak courante, ou null |
wenv | Environnement de la session |
jti | Identifiant unique du jeton |
exp | Expiration du jeton Keycloak d'origine ; à défaut, 15 minutes après l'émission |
Le jeton enrichi ne contient ni droits applicatifs, ni équipes, ni rôles HDS. Envoyez-le à l'API publique dans l'en-tête x-enriched-token. Si l'enrichissement échoue (utilisateur inconnu, inactif ou sans accès à l'application), la réponse est 200 sans token ni payload.
Réponse de /api/me
| Champ | Type | Description |
|---|---|---|
wid | string | Identifiant court de l'utilisateur |
email, firstName, lastName | string | Identité |
isActive | boolean | Compte actif |
adminLevel | string | Niveau d'administration |
hdsRoles | string[] | Rôles HDS : HDS_ADMIN, HDS_PATIENT, HDS_HEALTHCARE, HDS_STORAGE, HDS_DELETE, HDS_MEDICAL |
partner, network, customer | { wid, name } | Organisation |
teams | { wid, name, teamLevel }[] | Équipes et niveau dans chacune |
profile | { wid, name, description, rights } | Profil de l'utilisateur dans l'environnement de la session ; { wid: "", name: "Default" } s'il n'en a pas |
profile.rights | { code, name, description, category }[] | Droits applicatifs du profil pour cet environnement |
branding | objet | logoLightUrl, logoDarkUrl, bgLightUrl, bgDarkUrl, faviconUrl, primaryColor, accentColor, background, themeName, themeCssPath, themeCssVarsLight, themeCssVarsDark |
lastLoginAt, createdAt | string ISO 8601 | Dates |
Valeurs par défaut et limites
| Élément | Valeur |
|---|---|
| Méthode PKCE acceptée | S256 |
| Jeton d'accès Keycloak | 5 minutes |
| Code d'autorisation | 5 minutes |
| Session de l'application sans activité / au maximum | 6 heures / 12 heures |
| Session Keycloak sans activité / au maximum | 24 heures / 24 heures |
| Jeton enrichi | même expiration que le jeton Keycloak dont il est issu |
| Prise en compte d'un changement de droits | 60 secondes au plus |
| Cache des résolutions de Discovery, échecs compris | 5 minutes |
| Redirect URIs personnalisées | 50 par application et par environnement |
| Limites de débit de l'API publique, par adresse IP | 10 requêtes/s, 100 requêtes/min, 1 000 requêtes/h |
| Limites de débit de Discovery | Par adresse IP ; réponse 429 au-delà |
Opérations
/discover/start-loginSur https://discovery.wakastart.app. Construit l'URL d'autorisation à partir du nom d'hôte du front, obligatoire. Public. Détail : Référence API : Discovery.
/discover/emailSur https://discovery.wakastart.app, et relayé par l'API publique sur GET /api/discovery/email. Renvoie les comptes d'une adresse e-mail dans l'application et l'environnement désignés par domain. Public. Détail : Référence API : Discovery.
/api/auth/enrichProduit le jeton enrichi à partir d'un jeton Keycloak. Détail : Référence API : Jeton et /me.
/api/meRenvoie le contexte de l'utilisateur connecté. Exige un jeton Keycloak ou un jeton enrichi émis pour votre application. Détail : Référence API : Jeton et /me.
/api/auth/token/refreshVariante de l'API publique du rafraîchissement auprès de Keycloak ; renvoie aussi un jeton enrichi. Détail : Référence API : Authentification.
/api/auth/logoutRévoque la session Keycloak à partir du refresh token. Nettoyez la session locale de votre application quelle que soit la réponse. Détail : Référence API : Authentification.
Les points de terminaison Keycloak utilisés par les guides sont les points standard OpenID Connect de l'émetteur : /protocol/openid-connect/auth, /token, /logout et /certs.
Erreurs
| Statut | Message | Origine | Cause |
|---|---|---|---|
400 | invalid_request: host is required (non-empty string, max 253 chars) | Discovery start-login | host absent ou vide |
400 | Tableau de messages de validation | Discovery | Autre champ manquant, inconnu ou trop long |
404 | not_found | Discovery start-login | Aucun hôte IAM actif ne correspond au nom d'hôte, realm de l'environnement pas encore créé pour le réseau, ou customerWid hors des candidats |
429 | ThrottlerException: Too Many Requests | Discovery, API publique | Limite de débit dépassée |
401 | Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header) | API publique | Jeton absent, expiré, ou utilisateur sans accès à l'application dans l'environnement |
403 | Access denied: token authorized party does not match the target application | API publique | Jeton émis pour une autre application |
404 | Utilisateur non trouvé | GET /api/me | Compte Keycloak non rattaché à un utilisateur Wakastart |
409 | Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide) | GET /api/me | Compte rattaché à plusieurs clients sans indication du client |
Le format des erreurs de l'API publique est décrit dans Codes d'erreur.