--- { "title": "L'introspection de jetons dans FHIR : un guide complet sur la validation moderne des jetons", "description": "L'introspection de jetons est le pont essentiel entre l'authentification et l'autorisation. Lorsqu'un client présente un jeton pour accéder aux ressources FHIR, le serveur doit vérifier si ce jeton est valide.", "date": "2025-08-19", "author": "Rostislav Antonov", "reading-time": "8 min", "tags": [ "Infrastructure", "Compliance" ] } --- ## 1. Authentification, autorisation et introspection de jetons Dans le monde de la sécurité des API, deux concepts fondamentaux collaborent pour protéger les ressources : l'**authentification** et l'**autorisation**. L'**authentification** répond à la question « Qui êtes-vous ? » C'est le processus de vérification d'identité, qui confirme que les utilisateurs sont bien qui ils prétendent être. Cela se produit généralement auprès de votre fournisseur d'identité (IdP) lorsque les utilisateurs se connectent à l'aide d'identifiants, de données biométriques ou d'autres facteurs. Le résultat est un jeton qui représente l'identité authentifiée. L'**autorisation** répond à la question « Que pouvez-vous faire ? » Une fois l'identité établie, l'autorisation détermine les ressources auxquelles l'utilisateur authentifié peut accéder et les opérations qu'il peut effectuer. Dans les serveurs FHIR, c'est ici qu'interviennent les ressources AccessPolicy. L'**introspection de jetons** est le pont essentiel entre ces deux concepts. Lorsqu'un client présente un jeton pour accéder aux ressources FHIR, le serveur doit vérifier si ce jeton est valide. Ce processus révèle également à qui appartient le jeton et les informations qu'il contient, permettant ainsi au serveur de prendre des décisions d'autorisation. ## 2. Pourquoi l'introspection de jetons ? Les écosystèmes numériques modernes, en particulier dans le domaine de la santé, sont complexes. Ils se composent souvent de nombreuses applications — des portails patients et des DME aux applications mobiles destinées aux cliniciens —, chacune pouvant être connectée à différents systèmes de gestion des identités et des accès (IAM) ou IdP. Lorsqu'un serveur FHIR est intégré à cette architecture, il ne devrait pas forcer une modification de vos flux d'authentification établis. Restructurer votre système IAM pour un nouveau service est coûteux et perturbateur. L'objectif est l'intégration, non le remplacement. [Le serveur FHIR](https://www.health-samurai.io/fhir-server) devrait être en mesure de faire confiance aux jetons émis par ces systèmes d'authentification externes et de les valider. C'est là que l'introspection de jetons devient indispensable. Elle permet à votre serveur FHIR d'agir en tant que **serveur de ressources** sécurisé, en déléguant le processus d'authentification à vos IdP de confiance. Lorsqu'un client présente un jeton, le serveur FHIR utilise l'introspection pour répondre à une question cruciale : « Ce jeton est-il authentique ? » Ce processus permet au serveur FHIR de protéger ses ressources sans devenir lui-même un IdP. ## 3. L'introspection de jetons dans Aidbox Aidbox fournit la ressource *TokenIntrospector* pour valider les jetons émis par des IdP externes. Elle peut gérer deux types de jetons : - **JWT (JSON Web Token) :** Un jeton autonome qui contient des revendications utilisateur et est signé. TokenIntrospector vérifie la signature localement et lit les revendications — aucun aller-retour vers le serveur d'authentification n'est nécessaire. - **Jeton opaque.** Une chaîne d'apparence aléatoire sans revendications intégrées. Pour le vérifier, Aidbox appelle le `introspection_endpoint` de l'émetteur (conformément à la [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)) et demande si le jeton est actif et qui il représente. *TokenIntrospector* valide le jeton en utilisant la méthode appropriée selon son format. Ensuite, Aidbox applique les règles *AccessPolicy* pour déterminer ce à quoi le demandeur peut accéder. ### 3.1 Point de terminaison d'introspection de jeton opaque Techniquement, le point de terminaison d'introspection pourrait être utilisé pour tout type de jeton, mais il est le plus couramment employé pour les jetons opaques, puisque les jetons JWT sont autonomes et disposent d'autres options pour être validés localement. Aidbox implémente la norme OAuth 2.0 Token Introspection (RFC 7662). Lorsqu'un jeton opaque est reçu, le *TokenIntrospector* envoie une requête HTTP POST au *introspection_endpoint* configuré, transmettant le jeton pour validation. ```javascript { "resourceType": "TokenIntrospector", "id": "opaque-example", "type": "opaque", "introspection_endpoint": { "url": "https://auth.example.com/oauth/introspect", "authorization": "Basic Y2xpZW50OnNlY3JldA==" } } ``` Le serveur d'authentification externe répond avec un objet JSON indiquant si le jeton est actif et incluant les revendications pertinentes : ```javascript { "active": true, "sub": "user123", "scope": "read write", "exp": 1684567890, "client_id": "my-client" } ``` Aidbox reçoit cette réponse et rend les revendications disponibles aux ressources *AccessPolicy* dans le contexte du jeton. Cette approche délègue toute la logique de validation des jetons à votre infrastructure d'identité existante, tout en conservant Aidbox comme serveur de ressources pur. ### 3.2 Trois façons de valider un JWT Pour les jetons JWT, Aidbox offre trois méthodes de validation, chacune adaptée à différents scénarios. Choisissez en fonction de vos exigences de sécurité, de vos contraintes d'infrastructure et de vos besoins opérationnels. #### 3.2.1 Validation par secret partagé La validation par secret partagé utilise un secret commun pour les signatures HMAC (HS256). Votre IdP signe les jetons avec ce secret, et Aidbox les vérifie à l'aide de la même clé. ```javascript { "resourceType": "TokenIntrospector", "id": "simple-secret", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "secret": "your-256-bit-secret-here" } } ``` Cette méthode convient bien au développement ou aux déploiements simples. Cependant, elle exige que le même secret soit stocké à la fois dans votre IdP et dans Aidbox, ce qui peut poser un problème de sécurité. #### 3.2.2 Validation par URI JWKS La validation par URI de l'ensemble de clés web JSON (JWKS) récupère les clés publiques à partir du point de terminaison bien connu de votre IdP. Cette approche standard permet la rotation automatique des clés sans mettre à jour la configuration d'Aidbox. ```javascript { "resourceType": "TokenIntrospector", "id": "jwks-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "jwks_uri": "https://myidp.example.com/.well-known/jwks.json" } } ``` Votre IdP publie ses clés publiques au point de terminaison JWKS. Aidbox récupère ces clés et les met en cache, les actualisant automatiquement en cas de modification. Cette approche fonctionne avec les fournisseurs OAuth 2.0/OIDC standards et prend en charge les algorithmes RSA et à courbe elliptique tels que RS256 et ES256. #### 3.2.3 Clés cryptographiques (nouveau dans Aidbox depuis la version 2505) Cette méthode vous permet de spécifier plusieurs clés cryptographiques directement dans la configuration du *TokenIntrospector*. Elle vous permet de gérer les clés explicitement dans Aidbox, en prenant en charge simultanément plusieurs algorithmes et types de clés. ```javascript { "resourceType": "TokenIntrospector", "id": "multi-key-example", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----\n" }, { "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----\n" } ] } } ``` Cette méthode est particulièrement utile dans les environnements où la gestion directe des clés est préférée ou lorsque les points de terminaison JWKS ne sont pas disponibles. ## 4. Approfondissement : configuration des clés cryptographiques ### 4.1 Pourquoi plusieurs clés ? La prise en charge de plusieurs clés dans un seul TokenIntrospector résout plusieurs défis concrets : - **Rotation des clés** : Lors d'une rotation de clés, il est souvent nécessaire de prendre en charge simultanément les anciennes et les nouvelles clés. Certains jetons pourraient être signés avec la clé précédente, tandis que les nouveaux utilisent la clé mise à jour. - **Algorithmes mixtes** : Différentes applications de votre écosystème peuvent utiliser différents algorithmes cryptographiques. Les applications mobiles pourraient préférer ES256 pour la performance, tandis que les applications Web utilisent RS256 pour la compatibilité. - **IdP parallèles** : Les grandes organisations ont souvent plusieurs IdP ou environnements. Un seul *TokenIntrospector* peut valider des jetons provenant de différentes sources, chacune avec ses propres clés. - **Migration progressive** : Lors de la transition entre des types de clés ou des fournisseurs, vous pouvez ajouter de nouvelles clés sans supprimer immédiatement les anciennes, assurant ainsi des mises à jour sans interruption de service. ### 4.2 Types de clés et formats pris en charge Aidbox prend en charge les clés cryptographiques et algorithmes suivants : | Type de clé ([kty](https://datatracker.ietf.org/doc/html/rfc7518#section-6.1)) | Algorithmes (alg) | Format | Champ de clé | Cas d'utilisation | | --- | --- | --- | --- | --- | | RSA | RS256, RS384 | PEM | pub | Large compatibilité, norme établie | | EC | ES256 | PEM | pub | Clés plus petites, meilleures performances | | OCT | HS256 | plain | [k](https://datatracker.ietf.org/doc/html/rfc7518#section-6.4.1) | Secrets partagés, signature symétrique | **Règles de configuration des clés :** - **Clés asymétriques** (RSA, EC) : Utiliser le champ *pub* avec le format *PEM* - **Clés symétriques** (OCT) : Utiliser le champ *k* avec le format *plain* - **Exigences de format** : *PEM* est obligatoire pour les algorithmes asymétriques, *plain* pour les algorithmes symétriques ### 4.3 Exemple JSON complet Voici un exemple complet illustrant quatre clés différentes dans un seul TokenIntrospector : ```javascript { "resourceType": "TokenIntrospector", "id": "comprehensive-keys", "type": "jwt", "jwt": { "iss": "https://myidp.example.com", "keys": [ { "kty": "RSA", "alg": "RS256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ6cOq5m4eUzjbRpLo8Oez7UyO8vRrGI7w2E1+BZrFf6rZ0KS8yDJ8nKnEWP+a5CKJmLkZqzZ8oVMODbqPG6fOj8+qr5VZ6jJ7XzB9W8qR2s7LQ+5t9W8vq2XZ4gPw5Vp9X7+Wz6B+o8C3k7Q3g+t8D7h9+4e7u7Bp9E+P0Q0q4g8OO7L8qO5x5D7aF3R9g+O2OP3O+D3q+t5/yb1nRO8UuE3WO0u1xZ4qP1HJE3K+Tl+vE/Pt6Cw2EPz1EOpJu6F/JO9H8XQIDAQAB\n-----END PUBLIC KEY-----\n" }, { "kty": "RSA", "alg": "RS384", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7Z8...\n-----END PUBLIC KEY-----\n" }, { "kty": "EC", "alg": "ES256", "format": "PEM", "pub": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4f5wg5l2hKsTeNem/V41fGnJm6gOdrj8ym3rFkEjWT2btf0hEkNKsP8d9xwnSsWLXY0vhU7LWNBTSwJjJGrQ==\n-----END PUBLIC KEY-----\n" }, { "kty": "OCT", "alg": "HS256", "format": "plain", "k": "your-256-bit-secret-key-here-must-be-long-enough" } ] } } ``` ### 4.4 Comment Aidbox choisit la bonne clé Lors de la validation d'un JWT, Aidbox suit un algorithme précis pour sélectionner la clé appropriée : - **Correspondance d'algorithme** : Aidbox extrait la revendication *alg* de l'en-tête JWT et recherche les clés avec des algorithmes correspondants. - **Test séquentiel** : Aidbox teste chaque clé dont l'algorithme correspond, tout en vérifiant le format de la clé et le kty (type de clé), jusqu'à ce qu'une clé valide la signature avec succès. Cette approche garantit que les jetons sont validés correctement, même lorsqu'une rotation de clés est en cours ou que plusieurs algorithmes sont utilisés. ### 4.5 Erreurs courantes à éviter **Format incorrect** : L'erreur la plus courante est l'incompatibilité entre le champ format et l'encodage réel de la clé. Les clés PEM doivent inclure des en-têtes et des sauts de ligne appropriés, tandis que le format plain attend le matériel brut de la clé. **Émetteur manquant** : Oublier de définir le champ jwt.iss signifie que les jetons ne correspondront pas à ce TokenIntrospector, entraînant des échecs de validation. **Incompatibilité d'algorithme** : Utiliser alg: "RS256" avec une clé à courbe elliptique, ou spécifier ES256 avec une clé RSA causera des erreurs cryptographiques. **Encodage de clé incorrect** : Les problèmes d'encodage Base64 sont fréquents avec les clés au format plain. Assurez-vous que le matériel de votre clé est correctement encodé. ## 5. Exemple d'AccessPolicy La validation du jeton confirme uniquement qu'un JWT est légitime ; elle ne détermine pas ce à quoi l'utilisateur peut accéder. C'est là qu'interviennent les ressources AccessPolicy. Après une validation réussie du jeton, Aidbox extrait les revendications du JWT et les rend disponibles pour les décisions d'autorisation. Une AccessPolicy simple pourrait ressembler à ceci : ```javascript { "id": "external-auth-server", "engine": "json-schema", "schema": { "required": [ "jwt" ], "properties": { "jwt": { "required": [ "iss" ], "properties": { "iss": { "constant": "https://auth.example.com" } } } } } } ``` Cette politique garantit que seuls les jetons ayant le bon émetteur peuvent accéder aux ressources. Vous pouvez créer des politiques plus sophistiquées basées sur les rôles des utilisateurs, les portées ou d'autres revendications JWT. N'oubliez pas : **validation ≠ autorisation**. Un jeton valide n'accorde pas automatiquement l'accès ; vos AccessPolicies déterminent ce que chaque utilisateur peut faire. ## 6. Bonnes pratiques et conseils pour l'introspection de jetons **Effectuer une rotation régulière des clés** : Mettez en place un calendrier de rotation des clés, particulièrement pour les environnements de production. Utilisez la fonctionnalité de clés multiples pour permettre une rotation transparente. **Privilégier les algorithmes asymétriques** : Dans la mesure du possible, utilisez RS256 ou ES256 plutôt que HS256. Les clés asymétriques éliminent la nécessité de partager des secrets entre les systèmes. **Maintenir des revendications d'émetteur cohérentes** : Assurez-vous que votre IdP utilise toujours la même valeur iss dans tous les jetons. Un changement d'émetteur nécessite la mise à jour des configurations TokenIntrospector. **Utiliser des introspecteurs propres à chaque environnement** : [Créez des ressources](https://www.health-samurai.io/docs/aidbox/configuration/init-bundle) TokenIntrospector distinctes pour les environnements de développement, de préproduction et de production. Cela empêche l'acceptation de jetons entre environnements. **Surveiller l'expiration des clés** : Suivez la date d'expiration de vos clés cryptographiques et planifiez la rotation en conséquence. Des clés expirées entraîneront des échecs de validation. ## 7. Prochaines étapes pour la sécurité de votre FHIR Aidbox TokenIntrospector offre des options complètes de validation de jetons pour votre infrastructure FHIR. Que vous choisissiez l'introspection de jetons opaques, la validation par secret partagé, l'URI JWKS ou la configuration directe de clés cryptographiques, chaque méthode présente des avantages distincts pour différents cas d'utilisation et exigences architecturales. En prenant en charge simultanément plusieurs approches de validation et types de clés, Aidbox vous permet de mettre en œuvre des pratiques de sécurité robustes qui s'harmonisent avec votre infrastructure d'identité existante et vos besoins opérationnels. Vous cherchez un serveur FHIR compatible avec votre configuration d'authentification actuelle ? Aidbox intègre l'introspection de jetons nativement. [Essayez-le dès aujourd'hui](https://www.health-samurai.io/fhir-server) et voyez comment il peut s'intégrer à votre système. Voir aussi : [RBAC avec Keycloak et SMART on FHIR V2](/blog/implementing-role-based-access-control-for-fhir-resources-with-keycloak-and-smart-on-fhir-v2) et [Utilisation d'une passerelle API avec FHIR](/blog/using-api-gateway-with-fhir-api).