Resposta curta: SMART App Launch (SMART on FHIR) é a especificação da HL7 para como uma aplicação obtém acesso autorizado a um servidor FHIR em nome de um utilizador. É OAuth 2.0 e OpenID Connect com convenções específicas para FHIR: um documento de descoberta em .well-known/smart-configuration; dois modos de lançamento (lançamento EHR, onde o EHR abre a aplicação no contexto do paciente atual, e lançamento autónomo, onde o utilizador abre a aplicação e escolhe um paciente); escopos numa sintaxe que compreende FHIR (patient/Observation.rs significa ler e pesquisar Observações do paciente em contexto); contexto de lançamento devolvido com o token (qual paciente, qual encontro); e serviços de backend para acesso de sistema a sistema com autenticação de cliente JWT assinada. SMART v2 (a partir de 2021) tornou o PKCE obrigatório, adicionou escopos granulares e autenticação de cliente assimétrica, e é a versão que os programas nacionais exigem.
Passo 1: descoberta
A descoberta do SMART App Launch começa com a aplicação a obter o documento .well-known/smart-configuration do servidor FHIR, que lista os endpoints de autorização e token, as capacidades suportadas (lançamento EHR, lançamento autónomo, clientes públicos e confidenciais, OpenID Connect, permissões de paciente e utilizador), os escopos suportados, os métodos de desafio de código PKCE e os tipos de concessão, para que a aplicação saiba para onde enviar o utilizador.
GET https://fhir.example-hospital.org/.well-known/smart-configuration
{
"issuer": "https://auth.example-hospital.org",
"authorization_endpoint": "https://auth.example-hospital.org/authorize",
"token_endpoint": "https://auth.example-hospital.org/token",
"introspection_endpoint": "https://auth.example-hospital.org/introspect",
"capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
"scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
"code_challenge_methods_supported": ["S256"],
"grant_types_supported": ["authorization_code", "client_credentials"]
}
A aplicação descobre onde enviar o utilizador e o que o servidor suporta.
Passo 2: lançamento
O SMART App Launch tem dois modos de lançamento. Num lançamento EHR, o médico abre a aplicação dentro do EHR, que passa um parâmetro iss (o servidor FHIR) e um token de lançamento opaco que codifica o paciente e o encontro atuais. Num lançamento autónomo, o utilizador abre a aplicação diretamente e o servidor de autorização pede-lhe para escolher ou confirmar um paciente.
Lançamento EHR. O clínico clica na aplicação dentro do EHR; o EHR abre o URL de lançamento da aplicação com dois parâmetros: iss (o servidor FHIR) e launch (um token opaco que codifica o paciente e o encontro atuais). A aplicação deve ecoar launch no seu pedido de autorização com o escopo launch.
Lançamento autónomo. O utilizador abre a aplicação diretamente; a aplicação conhece o servidor FHIR (escolhido ou configurado) e pede contexto com launch/patient; o servidor de autorização pede ao utilizador para escolher ou confirmar um paciente.
Passo 3: código de autorização com PKCE
O passo de autorização SMART é o fluxo de código de autorização OAuth 2.0 com PKCE: a aplicação envia o utilizador para o endpoint de autorização com os seus escopos, o aud do servidor FHIR e um desafio de código; o utilizador autentica-se e aprova; a aplicação troca o código devolvido e o verificador de código por um token de acesso que chega juntamente com o contexto de lançamento.
GET https://auth.example-hospital.org/authorize?
response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
&scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
&state=af0ifjsldkj&aud=https://fhir.example-hospital.org
&launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
O utilizador autentica-se (com o fornecedor de identidade do hospital) e aprova os escopos; o servidor redireciona de volta com um code; a aplicação troca-o:
POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
"refresh_token": "a8c3...",
"id_token": "eyJhbGciOi...",
"patient": "Patient/123",
"encounter": "Encounter/456",
"fhirUser": "Practitioner/42",
"need_patient_banner": true,
"smart_style_url": "https://ehr.example.org/styles/smart.json"
}
O contexto de lançamento (patient, encounter, fhirUser) chega juntamente com o token. Clientes públicos (aplicações móveis e de navegador) usam PKCE e nenhum segredo de cliente; clientes confidenciais autenticam-se com um segredo ou, preferencialmente, com um JWT assinado (private_key_jwt) sob o método assimétrico.
Escopos
Os escopos do SMART on FHIR v2 utilizam a sintaxe contexto/recurso.permissões, onde o contexto é patient, user ou system e as permissões combinam c, r, u, d e s para criar, ler, atualizar, eliminar e pesquisar, como em patient/Observation.rs. Escopos granulares adicionam um filtro, openid e fhirUser fornecem a identidade do utilizador, os escopos de lançamento solicitam contexto e offline_access solicita um token de atualização.
Sintaxe SMART v2: <contexto>/<recurso>.<permissões> onde o contexto é patient (o paciente em contexto), user (o que o utilizador pode ver) ou system (backend), e as permissões são qualquer uma de c criar, r ler, u atualizar, d apagar, s pesquisar, nesta ordem: patient/Observation.rs, user/Patient.rs, system/*.cruds. Escopos granulares adicionam um filtro: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser fornecem um ID token e a identidade FHIR do utilizador; launch, launch/patient, launch/encounter pedem contexto; offline_access um token de atualização para uso quando o utilizador está ausente, online_access um válido apenas durante a sessão. A sintaxe v1 (patient/Observation.read) ainda é aceite por muitos servidores.
Serviços de backend
Para um sistema que atua sem um utilizador (uma exportação noturna, um motor de integração), os Serviços de Backend SMART usam client_credentials com uma asserção JWT assinada (as chaves públicas do cliente publicadas num URL JWKS) e escopos system/. Sem utilizador, sem contexto de lançamento, registo rigoroso.
Executar em segurança
Executar o SMART App Launch de forma segura significa registar URIs de redirecionamento exatas, nunca usar o fluxo implícito, armazenar e rodar tokens de atualização de forma segura, validar o estado e o aud dos tokens de ID, verificar tokens em cada chamada de API, impor tanto os escopos como o contexto do paciente na camada de dados para que um token para um paciente nunca leia outro, e registar cada acesso.
Registe URIs de redirecionamento exatos; nunca use o fluxo implícito; armazene tokens de atualização de forma segura e roteie-os; valide state; verifique o aud dos ID tokens; verifique tokens em cada chamada de API (introspeção ou validação JWT) e aplique escopos e o contexto do paciente na camada de dados, porque um token para Patient/123 nunca deve ler Patient/124; registe cada acesso (Segurança e identidade: o mapa). SMART também define Marcas de Acesso do Paciente, uma forma para as aplicações mostrarem aos utilizadores com que organizações podem conectar-se, e interopera com SMART Health Links para partilha iniciada pelo paciente.
Onde é exigido
As regras de acesso do paciente nos EUA exigem que os EHRs certificados suportem SMART App Launch e Backend Services; os programas nacionais na Europa adotam-no para acesso a aplicações (o MedMij dos Países Baixos usa OAuth 2.0 com convenções equivalentes); o IPS e muitos guias de implementação assumem-no. Veja TEFCA e Registos de saúde eletrónicos nacionais.
Em Anpheros
A Plataforma Anpheros usa OAuth 2.0 com PKCE para aplicações e autenticação de cliente JWT assinada para backends, com escopos derivados do consentimento da pessoa e o contexto do paciente aplicado em cada pedido. O site do programador documenta autenticação e o padrão de backend SMART on FHIR para construir sobre ele.
Páginas relacionadas
- Segurança e identidade em aplicações de saúde: o mapa
- Plataforma de consentimento do paciente
- SMART Health Links explicados
- CDS Hooks explicados
- Pesquisa FHIR explicada
- SMART on FHIR backend (site do programador)
- Autenticação (site do programador)
Fontes
- HL7 SMART App Launch (STU 2.2)
- HL7 SMART App Launch: scopes and launch context
- HL7 SMART App Launch: Backend Services
- IETF RFC 7636: PKCE
- IETF RFC 6749: OAuth 2.0
- OpenID Connect Core 1.0
Perguntas frequentes
SMART on FHIR é o mesmo que OAuth 2.0?
É OAuth 2.0 e OpenID Connect com adições específicas para FHIR: descoberta, contexto de lançamento, a sintaxe de escopo e serviços de backend. Qualquer biblioteca OAuth funciona; as convenções SMART são o que tornam uma aplicação portátil entre servidores FHIR.
Preciso de PKCE para uma aplicação do lado do servidor?
Em SMART v2, sim, para todos os clientes que usam o fluxo de código de autorização. Clientes confidenciais adicionam autenticação de cliente (um segredo ou um JWT assinado) por cima.
Qual é a diferença entre os escopos patient/ e user/?
patient/ limita o acesso ao único paciente no contexto de lançamento; user/ concede o que o utilizador autenticado tem permissão para ver, em todos os pacientes. Aplicações voltadas para o paciente usam patient/; aplicações de clínicos frequentemente usam user/ com contexto.
Uma aplicação SMART pode escrever no registo?
Se lhe forem concedidas permissões de criação ou atualização (c, u) nos seus escopos e o servidor o permitir. Muitas implementações concedem às aplicações de pacientes apenas leitura e pesquisa, e encaminham as escritas através de recursos específicos como QuestionnaireResponse.
Experimente grátis no sandbox
Sua primeira chamada FHIR em 5 minutos. Uma API HL7 FHIR R4 com o consentimento do paciente integrado: experimente na sandbox e depois conecte a sua própria app ou sistema clínico.
Grátis · 30 pacientes sintéticos · sem cartão
A Anpheros desenvolve um registo médico que o doente controla e pode partilhar com qualquer clínica, numa plataforma HL7 FHIR R4, sediada na UE. Estes guias ajudam-no a compreender e organizar a sua saúde; não substituem o seu médico.
Sobre a Anpheros →