Lancement de l'application SMART on FHIR : lancement du DSE par rapport aux applications autonomes, iss, aud et PKCE
Implémentez SMART App Launch 2.2.0 contre Epic et d'autres DSE : lancement de DSE par rapport à autonome, iss et aud, le jeton de lancement, PKCE S256, et pourquoi le bac à sable Epic n'est pas en production.
Ala Ben Aicha
Réponse directe
Le lancement du DSE passe par iss et un jeton de lancement opaque ; autonome ne le fait pas. Autoriser avec aud égal à la base FHIR et PKCE S256. Traitez le bac à sable Epic par rapport à la production comme une matrice de test, et non comme un SLA.
Mappage du mode de lancement
Fixez la version de Lancement de l'application SMART 2.2.0 (STU 2.2, paquet hl7.fhir.uv.smart-app-launch#2.2.0, généré le 30 avril 2024, sur FHIR R4). L'IG prend en charge quatre cas d'utilisation : patient autonome, lancement du portail patient, fournisseur autonome, lancement du portail fournisseur. Cette page est la poignée de main de lancement et de jeton, et non un didacticiel FHIR ressource par ressource - cela reste le Guide d'intégration FHIR. La saveur du fournisseur par rapport à Cerner/Oracle Health est la Comparaison Epic vs Cerner.
| Mode | Comment démarre l'application | Paramètres de lancement | Autoriser les extras | Contexte du jeton |
|---|---|---|---|---|
| Lancement du DSE | L'utilisateur se trouve déjà dans un graphique ou un portail ; DSE ouvre l'URL de lancement enregistrée | iss = URL de base FHIR ; launch = poignée opaque |
Portée launch plus launch={token}; aud est égal que iss |
Fournitures DSE patient / encounter de la session en cours |
| Lancement autonome | L'utilisateur ouvre l'application en dehors du DSE | Aucun | Portée launch/patient (et/ou launch/encounter); aud = la base FHIR que vous comptez appeler |
Le serveur d'autorisation collecte le contexte (souvent un sélecteur de patients) |
La découverte est GET {iss}/.well-known/smart-configuration (Lancement du DSE) ou GET {fhir-base}/.well-known/smart-configuration (autonome). Vous avez besoin authorization_endpoint, token_endpoint, et code_challenge_methods_supported y compris S256.
Autoriser (minimum) :
| Paramètre | Lancement du DSE | Autonome |
|---|---|---|
response_type |
code |
code |
client_id |
enregistré | enregistré |
redirect_uri |
URI enregistré exact | URI enregistré exact |
scope |
launch + scopes cliniques + optionnel openid fhirUser |
launch/patient + périmètres cliniques |
state |
imprévisible, lié à la session | pareil |
aud |
Base de ressources FHIR (pareil que iss) |
Base de ressources FHIR que vous appellerez |
launch |
faire écho au jeton opaque | omettre |
code_challenge / code_challenge_method |
S256 PKCE | S256 PKCE |
Toutes les applications SMART DEVRAIENT prendre en charge PKCE. Les serveurs DEVRAIENT prendre en charge S256 et NE DEVRA PAS prendre en charge plain. POST d'échange de jetons grant_type=authorization_code, le code, pareil redirect_uri, et code_verifier. Les applications publiques ne peuvent pas protéger un secret client ; les applications confidentielles devraient préférer l’authentification client asymétrique lorsque le DSE la propose.
aud existe donc un véritable jeton de porteur n'est pas envoyé à un serveur de ressources contrefait. Le serveur de ressources doit vérifier que le jeton a été émis pour c'est Base FHIR. Si aud ≠ le serveur que vous appelez, attendez-vous à un jeton rejeté même lorsque l'échange de code a réussi.
Pièges d'identification
| Piège | Qu'est-ce qui casse | Corriger |
|---|---|---|
iss hôte ≠ aud hôte |
Le jeton fonctionne en découverte, 401 sur Patient lu | Lancement du DSE : aud c'est le lancement iss. Ne réécrivez pas le nom d’hôte sur un « joli » proxy |
| Jeton de lancement non répercuté | EHR ne peut pas lier la requête OAuth au graphique | Portée launch et requête launch= avec la même valeur opaque |
| ID client Sandbox en production | Problème Epic (et autres) deux identifiants clients | ID de non-production par rapport au bac à sable ; ID de production uniquement après « prêt pour la production » |
| Vérificateur PKCE perdu lors de la redirection | invalid_grant |
Magasin code_verifier dans le stockage spécifique à l'application, saisi par state, pas dans un cookie lisible par tous |
redirect_uri dérive à barre oblique finale |
Autorisation refusée | Correspondance octet par octet avec enregistrement |
Suite à un reference vers un autre hôte FHIR avec le même porteur |
Vol de jetons/mauvais public | Nouvelle autorisation pour cela aud; ne pas transmettre le jeton |
Sujet de test spécifique à Epic, pas une promesse de livraison : Epic sur FHIR documente un bac à sable actuel à https://fhir.epic.com/interconnect-fhir-oauth/ et des bases distinctes de membres de la communauté de production. Backend OAuth est un JWT vers le point de terminaison du jeton (SMART Backend Services, avec des différences Epic). Le bac à sable mappe automatiquement votre client à un utilisateur ; un membre de la communauté Epic en production a besoin d'un ECSA pour mapper l'ID client à un utilisateur d'audit avant un jeton backend est émis. Capacité, étendues et sélection des patients différer entre le bac à sable et ce membre. Mettez ces deltas sur la matrice de test. N'inventez pas un SLA « App Orchard de 8 semaines » – App Orchard est retiré, et aucune durée ici n'est une citation.
Jeux de données de test
Désidentifié. Ces URL et jetons sont des formes et non des informations d'identification.
URL de lancement du DSE que le DSE ouvre :
https://app.example.org/launch?iss=https%3A%2F%2Fehr.example.org%2Ffhir&launch=xyz123
Autoriser (sauts de ligne pour la lecture) :
https://ehr.example.org/authorize?
response_type=code&
client_id=growth-chart-example&
redirect_uri=https%3A%2F%2Fapp.example.org%2Fafter-auth&
launch=xyz123&
scope=launch%20patient%2FPatient.rs%20patient%2FObservation.rs%20openid%20fhirUser&
state=98wrghuwuogerg97&
aud=https%3A%2F%2Fehr.example.org%2Ffhir&
code_challenge=YPXe7B8ghKrj8PsT4L6ltupgI12NQJ5vblB07F4rGaw&
code_challenge_method=S256
Omissions autonomes launch et utilise scope=launch/patient patient/Patient.rs ... avec le même aud discipline.
Tests minimaux :
- Lancement du DSE :
isscapturé,launchfait écho,aud==iss, PKCE aller-retour,patientsur la réponse symbolique. - Autonome : sélecteur de patients,
launch/patientaccordé, pas de restelaunchparamètre. - Faux
aud(jeton demandé pour le serveur A, appelez le serveur B) – doit échouer. - La relecture d'un code d'autorisation doit échouer.
- Epic (ou analogique) : ID client sandbox par rapport au sandbox ; ID client de production par rapport à une base membre FHIR ; documenter la première portée qui existe dans l’un et pas dans l’autre.
Ne commettez jamais de vrais secrets client, JWK ou jetons d’accès. Faites pivoter tout ce qui a été dans une capture d'écran.
Modes de défaillance et restauration
| Échec | Détection | Restauration |
|---|---|---|
| Utilisateur bloqué sur l'autorisation | Manquant state cookies tiers aller-retour ou bloqués dans une iframe DSE |
Sortez de l'iframe si le DSE l'exige ; ne jamais laisser tomber state |
| Jeton pour le mauvais patient | patient sur le jeton ≠ contexte graphique |
Contexte du jeton de confiance, pas un identifiant Patient de l'application mise en cache depuis le dernier lancement |
| Actualiser après la déconnexion | online_access contre offline_access confusion |
Le lancement du DSE nécessite généralement un accès en ligne ; ne faites pas de demande hors ligne, sauf si le produit nécessite réellement un accès sans surveillance |
| Portées Sandbox uniquement dans une version client | Première production 403 | Matrice de portée : bac à sable × un membre non-prod × prod ; expédier l'intersection |
| Secret confidentiel dans un SPA public | Secret client extractible | Public + PKCE, ou un BFF qui détient le secret |
Désactivez une application qui se comporte mal en révoquant le client au niveau du DSE et en tournant les clés. Il n'y a pas d'« annulation de lancement » autre que le rejet du jeton et le renvoi de l'utilisateur au graphique.
Service associé
Si vous avez besoin d'un lancement SMART orienté vers Epic (fournisseur intégré, patient autonome ou matrice de test par rapport au bac à sable par rapport à un membre), c'est-à-dire Intégration Epic. Pour un pic de lancement limité, utilisez formulaire de contact projet.
Cette page n'est pas une liste d'Epic Showroom, ni une adhésion aux services des fournisseurs, ni une évaluation de sécurité, ni une chronologie. Services backend JWT vs patient vs fournisseur SMART est le Epic FHIR pour les startups HealthTech page de décision.