# 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](/v1.0/reference-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](/v1.0/authentification/flux-de-connexion#trois-façons-de-résoudre-le-realm)).

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 `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

::endpoint{method="POST" path="/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](/v1.0/reference-api/discovery).

::endpoint{method="GET" path="/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](/v1.0/reference-api/discovery).

::endpoint{method="POST" path="/api/auth/enrich"}

Produit le jeton enrichi à partir d'un jeton Keycloak. Détail : [Référence API : Jeton et /me](/v1.0/reference-api/jeton-et-me).

::endpoint{method="GET" path="/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](/v1.0/reference-api/jeton-et-me).

::endpoint{method="POST" path="/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](/v1.0/reference-api/authentification-api).

::endpoint{method="POST" path="/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](/v1.0/reference-api/authentification-api).

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](/v1.0/codes-d-erreur).
