Aller au contenu

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.

RéférenceDéveloppeur
Voir en Markdown

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

ServiceURL
Discoveryhttps://discovery.wakastart.app
API publiquehttps://api.wakastart.app/api
Keycloak prodhttps://auth.wakastart.app
Keycloak staginghttps://auth-staging.wakastart.app
Keycloak devhttps://auth-dev.wakastart.app
Adresse de retour d'un hôte IAM webhttps://<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.

ChampTypeObligatoireContraintesDescription
hoststringouinon vide, 253 caractères au plusNom 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
emailstringnone-mail valideAdresse saisie, pour départager plusieurs clients du réseau de l'hôte
customerWidstringnon6 caractères au plusClient choisi parmi les candidats d'une réponse ambiguë
redirectUristringoui2 048 caractères au plusRecopiée telle quelle dans l'URL ; Keycloak la compare aux redirect URIs déclarées
statestringnon256 caractères au plusValeur anti-falsification, recopiée
noncestringnon256 caractères au plusRecopiée dans l'id_token
codeChallengestringnon128 caractères au plusEmpreinte PKCE
codeChallengeMethodstringnonS256 seulMé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 :

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=…&nonce=…&code_challenge=…&code_challenge_method=S256"
}
Élément de keycloakUrlOù le lire
InstanceOrigine de l'URL
Émetteur (iss des jetons)Origine + /realms/<realm>
RealmSegment qui suit /realms/
Identifiant clientParamètre client_id
Scopesopenid 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.

ChampDescription
user_emailAdresse du compte, en minuscules
customer_wid, customer_name, customer_subdomainClient auquel appartient le compte
network_wid, network_name, network_subdomainRéseau du client
network_realm_idRealm Keycloak du réseau dans l'environnement de l'hôte, à utiliser pour construire l'URL d'autorisation
partner_wid, partner_namePropriétaire de l'application
idp_id, idp_name, idp_typeFournisseur d'identité actif du client pour le domaine de l'adresse (OIDC ou SAML), sinon null
keycloak_org_aliasAlias de l'organisation Keycloak du client (son identifiant court), sinon null
app_wid, app_name, app_client_id, app_url_frontApplication ; app_client_id est l'identifiant client Keycloak
theme_name, theme_css_path, theme_css_vars_light, theme_css_vars_darkThème résolu (client, puis réseau, puis application)
branding_logo_light, branding_logo_dark, branding_bg_lightVisuels pour habiller la page de choix
default_langLangue 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).

ClaimDescription
issÉmetteur : https://<instance>/realms/<realm>
azpIdentifiant client de votre application ; l'API publique refuse un jeton émis pour une autre application
subIdentifiant du compte sur cette instance
email, given_name, family_nameIdentité de l'utilisateur ; email est obligatoire pour obtenir un contexte Wakastart
wenvEnvironnement de la session : prod, staging ou dev
organizationOrganisation Keycloak de l'utilisateur, qui désigne son client Wakastart
exp, iatExpiration 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.

ClaimDescription
isswakastart-token-service
sub, keycloakIdIdentifiant du compte Keycloak
email, given_name, family_nameIdentité
azp, audRepris du jeton Keycloak
wadlNiveau d'administration : PARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN, USER ou NONE
pid, nid, cid, aid, uidIdentifiants courts du propriétaire, du réseau, du client, de l'application et de l'utilisateur
wthm, wlngThème et langue résolus
woidOrganisation Keycloak courante, ou null
wenvEnvironnement de la session
jtiIdentifiant unique du jeton
expExpiration 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

ChampTypeDescription
widstringIdentifiant court de l'utilisateur
email, firstName, lastNamestringIdentité
isActivebooleanCompte actif
adminLevelstringNiveau d'administration
hdsRolesstring[]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
brandingobjetlogoLightUrl, logoDarkUrl, bgLightUrl, bgDarkUrl, faviconUrl, primaryColor, accentColor, background, themeName, themeCssPath, themeCssVarsLight, themeCssVarsDark
lastLoginAt, createdAtstring ISO 8601Dates

Valeurs par défaut et limites

ÉlémentValeur
Méthode PKCE acceptéeS256
Jeton d'accès Keycloak5 minutes
Code d'autorisation5 minutes
Session de l'application sans activité / au maximum6 heures / 12 heures
Session Keycloak sans activité / au maximum24 heures / 24 heures
Jeton enrichimême expiration que le jeton Keycloak dont il est issu
Prise en compte d'un changement de droits60 secondes au plus
Cache des résolutions de Discovery, échecs compris5 minutes
Redirect URIs personnalisées50 par application et par environnement
Limites de débit de l'API publique, par adresse IP10 requêtes/s, 100 requêtes/min, 1 000 requêtes/h
Limites de débit de DiscoveryPar adresse IP ; réponse 429 au-delà

Opérations

POST/discover/start-login

Sur 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.

GET/discover/email

Sur 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.

POST/api/auth/enrich

Produit le jeton enrichi à partir d'un jeton Keycloak. Détail : Référence API : Jeton et /me.

GET/api/me

Renvoie 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.

POST/api/auth/token/refresh

Variante de l'API publique du rafraîchissement auprès de Keycloak ; renvoie aussi un jeton enrichi. Détail : Référence API : Authentification.

POST/api/auth/logout

Ré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

StatutMessageOrigineCause
400invalid_request: host is required (non-empty string, max 253 chars)Discovery start-loginhost absent ou vide
400Tableau de messages de validationDiscoveryAutre champ manquant, inconnu ou trop long
404not_foundDiscovery start-loginAucun 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
429ThrottlerException: Too Many RequestsDiscovery, API publiqueLimite de débit dépassée
401Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)API publiqueJeton absent, expiré, ou utilisateur sans accès à l'application dans l'environnement
403Access denied: token authorized party does not match the target applicationAPI publiqueJeton émis pour une autre application
404Utilisateur non trouvéGET /api/meCompte Keycloak non rattaché à un utilisateur Wakastart
409Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide)GET /api/meCompte rattaché à plusieurs clients sans indication du client

Le format des erreurs de l'API publique est décrit dans Codes d'erreur.