🔥 L'introspection de jetons dans FHIR : guide de validation moderne

1. Authentification, autorisation et introspection de jetons

Dans le domaine de la sécurité des API, deux concepts fondamentaux s'associent pour protéger les ressources : l'authentification et l'autorisation.

L'authentification répond à la question « Qui êtes-vous ? » Il s'agit du processus de vérification de l'identité, qui confirme que les utilisateurs sont bien ceux qu'ils prétendent être. Cela se produit généralement au niveau de votre fournisseur d'identité (IdP) lorsque les utilisateurs s'authentifient avec des identifiants, des données biométriques ou d'autres facteurs. Le résultat est un jeton représentant l'identité authentifiée.

L'autorisation répond à « 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 là 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 quelles informations il contient, afin que le serveur puisse prendre des décisions d'autorisation.

2. Pourquoi l'introspection de jetons ?

Les écosystèmes numériques modernes, en particulier dans le secteur de la santé, sont complexes. Ils se composent souvent de nombreuses applications — des portails patients et des DSE aux applications mobiles pour les cliniciens — potentiellement connectées à différents systèmes de gestion des identités et des accès (IAM) ou IdPs.

Lorsqu'un serveur FHIR est intégré à cette architecture, il ne devrait pas imposer une modification de vos flux d'authentification établis. Reconfigurer 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 doit pouvoir faire confiance aux jetons émis par ces systèmes d'authentification externes et 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 IdPs 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 un IdP externe. Elle peut traiter deux types de jetons différents :

JWT (JSON Web Token) : Un jeton autonome qui contient les revendications de l'utilisateur et est signé. Le 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 de caractères aléatoire sans revendications intégrées. Pour le vérifier, Aidbox appelle le introspection_endpoint de l'émetteur (conformément à la RFC 7662) et demande si le jeton est actif et qui il représente.

Le TokenIntrospector valide le jeton en utilisant la méthode appropriée à son format. Ensuite, Aidbox applique les règles AccessPolicy pour décider de ce à quoi le demandeur peut accéder.

3.1 Point de terminaison d'introspection pour les jetons opaques

Techniquement, le point de terminaison d'introspection peut être utilisé pour n'importe quel type de jeton, mais il est le plus souvent utilisé pour les jetons opaques, car les jetons JWT sont autonomes et disposent de différentes options de validation locale.

Aidbox implémente la norme d'introspection de jetons OAuth 2.0 (RFC 7662). Lorsqu'un jeton opaque arrive, le TokenIntrospector effectue une requête HTTP POST vers le introspection_endpoint configuré, en envoyant le jeton pour validation.

{
  "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 :

{
  "active": true,
  "sub": "user123",
  "scope": "read write",
  "exp": 1684567890,
  "client_id": "my-client"
}

Aidbox reçoit cette réponse et met les revendications à la disposition des 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 maintenant Aidbox comme serveur de ressources pur.

3.2 Trois façons de valider un JWT

Pour les jetons JWT, Aidbox propose trois méthodes de validation, chacune adaptée à des scénarios différents. Faites votre choix 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 en utilisant la même clé.

{
  "resourceType": "TokenIntrospector",
  "id": "simple-secret",
  "type": "jwt",
  "jwt": {
    "iss": "https://myidp.example.com",
    "secret": "your-256-bit-secret-here"
  }
}

Cette méthode fonctionne bien pour le développement ou les déploiements simples. Cependant, elle nécessite que le même secret soit stocké à la fois dans votre IdP et dans Aidbox, ce qui peut poser des problèmes 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 depuis le point de terminaison bien connu de votre IdP. Cette approche standard permet la rotation automatique des clés sans mise à jour de la configuration d'Aidbox.

{
  "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, en les actualisant automatiquement lorsqu'elles changent. Cette approche fonctionne avec les fournisseurs OAuth 2.0/OIDC standard et prend en charge les algorithmes RSA et à courbes elliptiques comme 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 au sein d'Aidbox, en prenant en charge plusieurs algorithmes et types de clés simultanément.

{
  "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, vous devez souvent prendre en charge simultanément les anciennes et les nouvelles clés. Certains jetons peuvent ê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 peuvent préférer ES256 pour des raisons de performance, tandis que les applications Web utilisent RS256 pour la compatibilité.
IdPs parallèles : Les grandes organisations ont souvent plusieurs IdPs 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 types de clés ou fournisseurs, vous pouvez ajouter de nouvelles clés sans supprimer immédiatement les anciennes, garantissant des mises à jour sans interruption de service.

4.2 Types et formats de clés pris en charge

Aidbox prend en charge les clés cryptographiques et algorithmes suivants :

Type de clé (kty)	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	Secrets partagés, signature symétrique

Règles de configuration des clés :

Clés asymétriques (RSA, EC) : Utilisez le champ pub avec le format PEM
Clés symétriques (OCT) : Utilisez 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 montrant quatre clés différentes dans un seul TokenIntrospector :

{
  "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 sélectionne la bonne clé

Lors de la validation d'un JWT, Aidbox suit un algorithme spécifique pour sélectionner la clé appropriée :

Correspondance d'algorithme : Aidbox extrait la revendication alg de l'en-tête du JWT et recherche les clés dont les algorithmes correspondent.
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

Mauvais format : L'erreur la plus fréquente est la discordance 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 de clé brut.

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

Discordance d'algorithme : Utiliser alg: "RS256" avec une clé à courbe elliptique, ou spécifier ES256 avec une clé RSA, provoquera des erreurs cryptographiques.

Encodage de clé incorrect : Les problèmes d'encodage en base64 sont fréquents avec les clés au format plain. Assurez-vous que votre matériel de clé est correctement encodé.

5. Exemple d'AccessPolicy

La validation d'un 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 met à disposition pour les décisions d'autorisation. Une AccessPolicy simple pourrait ressembler à ceci :

{
  "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 possédant le bon émetteur peuvent accéder aux ressources. Vous pouvez créer des politiques plus élaborées basées sur les rôles des utilisateurs, les portées ou d'autres revendications JWT.

Rappel : 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

Faites tourner vos clés régulièrement : Mettez en place un calendrier de rotation des clés, en particulier pour les environnements de production. Utilisez la fonctionnalité de clés multiples pour permettre une rotation transparente.

Privilégiez 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.

Maintenez la cohérence des revendications d'émetteur : Assurez-vous que votre IdP utilise toujours la même valeur iss pour tous les jetons. Un changement d'émetteur nécessite la mise à jour des configurations TokenIntrospector.

Utilisez des introspecteurs spécifiques à chaque environnement : Créez des ressources TokenIntrospector distinctes pour les environnements de développement, de préproduction et de production. Cela évite l'acceptation croisée de jetons entre environnements.

Surveillez 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

Le TokenIntrospector d'Aidbox offre des options complètes de validation des 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 plusieurs approches de validation et types de clés simultanément, Aidbox vous permet de mettre en œuvre des pratiques de sécurité robustes qui s'alignent sur votre infrastructure d'identité existante et vos besoins opérationnels.

Vous cherchez un serveur FHIR qui fonctionne avec votre configuration d'authentification actuelle ? Aidbox intègre l'introspection de jetons nativement. Essayez-le dès aujourd'hui et découvrez comment il peut s'intégrer à votre système.

Voir aussi : Contrôle d'accès basé sur les rôles avec Keycloak et SMART on FHIR V2 et Utilisation d'une passerelle API avec FHIR.