As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# SMART no suporte FHIR para AWS HealthLake
Um armazenamento de HealthLake dados habilitado para aplicações médicas substituíveis e tecnologias reutilizáveis (SMART) permite o acesso ao SMART em aplicativos compatíveis com FHIR. HealthLake os dados são acessados por meio da autenticação e autorização de solicitações usando um servidor de autorização terceirizado. Portanto, em vez de gerenciar as credenciais do usuário via AWS Identity and Access Management, você está fazendo isso usando um SMART no servidor de autorização compatível com FHIR.
**nota**
HealthLake suporta SMART nas versões 1.0 e 2.0 do FHIR. Para saber mais sobre essas estruturas, consulte [SMART App Launch na documentação](https://www.hl7.org/fhir/smart-app-launch/) do *FHIR R4*.
HealthLake os armazenamentos de dados oferecem suporte às seguintes estruturas de autenticação e autorização para SMART em solicitações FHIR:
**OpenID (AuthN)**: para autenticar a pessoa ou o aplicativo do cliente é quem (ou o que) ela afirma ser.
**OAuth 2.0 (AuthZ)**: para autorizar em quais recursos FHIR em seu armazenamento de HealthLake dados uma solicitação autenticada pode ler ou gravar. Isso é definido pelos escopos configurados em seu servidor de autorização.
Você pode criar um SMART no armazenamento de dados habilitado para FHIR usando o AWS CLI ou. AWS SDKs Para obter mais informações, consulte [Criando um armazenamento HealthLake de dados](managing-data-stores-create.md).
**Topics**
+ [Começando a usar o SMART no FHIR](reference-smart-on-fhir-getting-started.md)
+ [HealthLake requisitos de autenticação para SMART no FHIR](reference-smart-on-fhir-authentication.md)
+ [SMART em escopos FHIR OAuth 2.0 suportados por HealthLake](reference-smart-on-fhir-oauth-scopes.md)
+ [Validação de token usando AWS Lambda](reference-smart-on-fhir-token-validation.md)
+ [Usando autorização refinada com um SMART no armazenamento de dados habilitado para FHIR HealthLake](reference-smart-on-fhir-fine-grained-authorization.md)
+ [Buscando o SMART no documento FHIR Discovery](reference-smart-on-fhir-discovery-document.md)
+ [Fazendo uma solicitação da API FHIR REST em um armazenamento de dados habilitado para Smart HealthLake](reference-smart-on-fhir-request-example.md)
# Começando a usar o SMART no FHIR
Os tópicos a seguir descrevem como começar a usar o SMART na autorização FHIR para. AWS HealthLake Eles incluem os recursos que você deve provisionar em sua AWS conta, a criação de um armazenamento de HealthLake dados habilitado para SMART on FHIR e um exemplo de como um aplicativo cliente SMART on FHIR interage com um servidor de autorização e um armazenamento de dados. HealthLake
**Topics**
+ [Configurando recursos para SMART no FHIR](#smart-on-fhir-resources)
+ [Fluxo de trabalho do aplicativo cliente para SMART no FHIR](#smart-on-fhir-client-app-workflow)
## Configurando recursos para SMART no FHIR
As etapas a seguir definem como as solicitações SMART on FHIR são tratadas HealthLake e os recursos necessários para que elas tenham sucesso. Os elementos a seguir funcionam juntos em um fluxo de trabalho para criar uma solicitação SMART na FHIR:
+ **O usuário final**: geralmente, um paciente ou médico que usa um aplicativo SMART on FHIR de terceiros para acessar dados em um armazenamento de dados. HealthLake
+ **O aplicativo SMART on FHIR (conhecido como aplicativo cliente)**: um aplicativo que deseja acessar dados encontrados no armazenamento de HealthLake dados.
+ **O servidor de autorização**: um servidor compatível com o OpenID Connect que é capaz de autenticar usuários e emitir tokens de acesso.
+ **O armazenamento de HealthLake dados**: um armazenamento de HealthLake dados habilitado para SMART on FHIR que usa uma função Lambda para responder às solicitações REST do FHIR que fornecem um token portador.
Para que esses elementos funcionem juntos, você deve criar os seguintes recursos.
**nota**
[Recomendamos criar seu SMART no armazenamento de HealthLake dados habilitado para FHIR depois de configurar o servidor de autorização, definir os [escopos](reference-smart-on-fhir-oauth-scopes.md) necessários nele e criar uma AWS Lambda função para lidar com a introspecção de tokens.](reference-smart-on-fhir-token-validation.md)
**1. Configurar um endpoint do servidor de autorização**
Para usar o SMART na estrutura FHIR, você precisa configurar um servidor de autorização terceirizado que possa validar as solicitações REST do FHIR feitas em um armazenamento de dados. Para obter mais informações, consulte [HealthLake requisitos de autenticação para SMART no FHIR](reference-smart-on-fhir-authentication.md).
**2. Defina escopos em seu servidor de autorização para controlar os níveis de acesso ao armazenamento de HealthLake dados**
A estrutura SMART on FHIR usa OAuth escopos para determinar a quais recursos FHIR uma solicitação autenticada tem acesso e em que medida. Definir escopos é uma forma de projetar com o mínimo de privilégios. Para obter mais informações, consulte [SMART em escopos FHIR OAuth 2.0 suportados por HealthLake](reference-smart-on-fhir-oauth-scopes.md).
**3. Configure uma AWS Lambda função capaz de realizar a introspecção de tokens**
Uma solicitação FHIR REST enviada pelo aplicativo cliente em um SMART no armazenamento de dados habilitado para FHIR contém um JSON Web Token (JWT). Para obter mais informações, consulte [Decodificando um JWT](reference-smart-on-fhir-token-validation.md).
**4. Crie um SMART no armazenamento de dados habilitado HealthLake para FHIR**
Para criar um SMART no armazenamento de HealthLake dados FHIR, você precisa fornecer um. `IdentityProviderConfiguration` Para obter mais informações, consulte [Criando um armazenamento HealthLake de dados](managing-data-stores-create.md).
## Fluxo de trabalho do aplicativo cliente para SMART no FHIR
A seção a seguir explica como iniciar um aplicativo cliente e fazer uma solicitação FHIR REST bem-sucedida em um armazenamento de HealthLake dados dentro do contexto do SMART no FHIR.
**1. Faça uma `GET` solicitação ao Known Uniform Resource Identifier usando o aplicativo cliente**
Um aplicativo cliente habilitado para SMART deve fazer uma `GET` solicitação para encontrar os endpoints de autorização do seu armazenamento de HealthLake dados. Isso é feito por meio de uma solicitação de Identificador Uniforme de Recursos (URI) conhecido. Para obter mais informações, consulte [Buscando o SMART no documento FHIR Discovery](reference-smart-on-fhir-discovery-document.md).
**2. Solicitar acesso e escopos**
O aplicativo cliente usa o ponto final de autorização do servidor de autorização, para que o usuário possa fazer login. Esse processo autentica o usuário. Os escopos são usados para definir quais recursos FHIR em seu armazenamento de HealthLake dados um aplicativo cliente pode acessar. Para obter mais informações, consulte [SMART em escopos FHIR OAuth 2.0 suportados por HealthLake](reference-smart-on-fhir-oauth-scopes.md).
**3. Tokens de acesso**
Agora que o usuário foi autenticado, um aplicativo cliente recebe um token de acesso JWT do servidor de autorização. Esse token é fornecido quando o aplicativo cliente envia uma solicitação FHIR REST para o. HealthLake Para obter mais informações, consulte [Validação de token](reference-smart-on-fhir-token-validation.md).
**4. Faça uma solicitação da API REST FHIR no SMART no armazenamento de dados habilitado para FHIR HealthLake**
Agora, o aplicativo cliente pode enviar uma solicitação da API FHIR REST para um endpoint de armazenamento de HealthLake dados usando o token de acesso fornecido pelo servidor de autorização. Para obter mais informações, consulte [Fazendo uma solicitação da API FHIR REST em um armazenamento de dados habilitado para Smart HealthLake](reference-smart-on-fhir-request-example.md).
**5. Valide o token de acesso JWT**
Para validar o token de acesso enviado na solicitação FHIR REST, use uma função Lambda. Para obter mais informações, consulte [Validação de token usando AWS Lambda](reference-smart-on-fhir-token-validation.md).
# HealthLake requisitos de autenticação para SMART no FHIR
Para acessar recursos do FHIR em um SMART no armazenamento de HealthLake dados habilitado para FHIR, um aplicativo cliente deve ser autorizado por um servidor de autorização OAuth compatível com 2.0 e apresentar um token de OAuth portador como parte de uma solicitação da API FHIR REST. Para encontrar o endpoint do servidor de autorização, use o documento de descoberta HealthLake SMART on FHIR por meio de um identificador `Well-Known` uniforme de recursos. Para saber mais sobre esse processo, consulte [Buscando o SMART no documento FHIR Discovery](reference-smart-on-fhir-discovery-document.md).
Ao criar um SMART no armazenamento de HealthLake dados FHIR, você deve definir o ponto final do servidor de autorização e o ponto final do token no `metadata` elemento da solicitação. `CreateFHIRDatastore` Para saber mais sobre como definir o `metadata` elemento, consulte[Criando um armazenamento HealthLake de dados](managing-data-stores-create.md).
Usando os endpoints do servidor de autorização, o aplicativo cliente autenticará um usuário com o serviço de autorização. Depois de autorizado e autenticado, um JSON Web Token (JWT) é gerado pelo serviço de autorização e passado para o aplicativo cliente. Esse token contém escopos de recursos FHIR que o aplicativo cliente pode usar, o que, por sua vez, restringe quais dados o usuário pode acessar. Opcionalmente, se o escopo de lançamento foi fornecido, a resposta conterá esses detalhes. Para saber mais sobre o SMART em escopos FHIR suportados por HealthLake, consulte. [SMART em escopos FHIR OAuth 2.0 suportados por HealthLake](reference-smart-on-fhir-oauth-scopes.md)
Usando o JWT concedido pelo servidor de autorização, um aplicativo cliente faz chamadas da API FHIR REST para um SMART no armazenamento de dados habilitado para FHIR. HealthLake Para validar e decodificar o JWT, você precisa criar uma função Lambda. HealthLake invoca essa função Lambda em seu nome quando uma solicitação da API FHIR REST é recebida. Para ver um exemplo de função Lambda inicial, consulte. [Validação de token usando AWS Lambda](reference-smart-on-fhir-token-validation.md)
## Elementos do servidor de autorização necessários para criar um SMART no armazenamento de dados habilitado HealthLake para FHIR
Na `CreateFHIRDatastore` solicitação, você precisa fornecer o endpoint de autorização e o endpoint do token como parte do `metadata` elemento no `IdentityProviderConfiguration` objeto. Tanto o endpoint de autorização quanto o endpoint do token são obrigatórios. Para ver um exemplo de como isso é especificado na `CreateFHIRDatastore` solicitação, consulte[Criando um armazenamento HealthLake de dados](managing-data-stores-create.md).
## Declarações necessárias para concluir uma solicitação da API REST FHIR em um SMART no armazenamento de dados habilitado para FHIR HealthLake
Sua AWS Lambda função deve conter as seguintes declarações para que seja uma solicitação válida da API FHIR REST em um armazenamento de dados SMART no FHIR ativado. HealthLake
+ `nbf`: Reivindicação [(não anterior) — A reclamação](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) “nbf” (não antes) identifica o momento antes do qual o JWT NÃO DEVE ser aceito para processamento. O processamento da reclamação “nbf” exige que a atual date/time DEVE ser posterior ou igual à não date/time listada antes na reivindicação “nbf”. O exemplo da função Lambda que fornecemos é convertido `iat` da resposta do servidor em. `nbf`
+ `exp`: [(Tempo de expiração) — A reivindicação](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) “exp” (prazo de expiração) identifica o prazo de expiração a partir do qual o JWT não deve ser aceito para processamento.
+ `isAuthorized`: Um booleano definido como. `True` Indica que a solicitação foi autorizada no servidor de autorização.
+ `aud`: Reivindicação [(Audiência) — A afirmação](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) “aud” (audiência) identifica os destinatários aos quais o JWT se destina. Deve ser um terminal de armazenamento de HealthLake dados SMART no FHIR habilitado.
+ `scope`: deve ser pelo menos um escopo relacionado a um recurso do FHIR. Esse escopo é definido em seu servidor de autorização. Para saber mais sobre os escopos relacionados a recursos do FHIR aceitos por HealthLake, consulte. [SMART nos escopos de recursos do FHIR para HealthLake](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest)
# SMART em escopos FHIR OAuth 2.0 suportados por HealthLake
HealthLake usa OAuth 2.0 como protocolo de autorização. O uso desse protocolo em seu servidor de autorização permite definir permissões de armazenamento de HealthLake dados (criar, ler, atualizar, excluir e pesquisar) para recursos FHIR aos quais um aplicativo cliente tem acesso.
A estrutura SMART on FHIR define um conjunto de escopos que podem ser solicitados do servidor de autorização. Por exemplo, um aplicativo cliente projetado apenas para permitir que os pacientes visualizem seus resultados laboratoriais ou visualizem seus detalhes de contato só deve ser *autorizado* a solicitar `read` escopos.
**nota**
HealthLake fornece suporte para SMART no FHIR V1 e V2, conforme descrito abaixo. O SMART no FHIR [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)é definido para um dos três valores a seguir quando seu armazenamento de dados é criado:
`SMART_ON_FHIR_V1`— Support somente para SMART no FHIR V1, que inclui permissões `read` (leitura/pesquisa) e (). `write` create/update/delete
`SMART_ON_FHIR`— Support para SMART no FHIR V1 e V2, que inclui,`create`, `read``update`, `delete` e permissões. `search`
`AWS_AUTH`— A estratégia de AWS HealthLake autorização padrão; não afiliada à SMART no FHIR.
## Escopo de lançamento independente
HealthLake suporta o escopo `launch/patient` do modo de inicialização autônomo.
No modo de inicialização autônomo, um aplicativo cliente solicita acesso aos dados clínicos do paciente porque o usuário e o paciente não são conhecidos pelo aplicativo cliente. Assim, a solicitação de autorização do aplicativo do cliente solicita explicitamente que o escopo do paciente seja devolvido. Após a autenticação bem-sucedida, o servidor de autorização emite um token de acesso contendo o escopo do paciente de lançamento solicitado. O contexto necessário do paciente é fornecido junto com o token de acesso na resposta do servidor de autorização.
**Escopos do modo de lançamento suportados**
| Escopo | Description |
| --- | --- |
| `launch/patient` | Um parâmetro em uma solicitação de autorização OAuth 2.0 solicitando que os dados do paciente sejam retornados na resposta de autorização. |
## SMART nos escopos de recursos do FHIR para HealthLake
HealthLake define três níveis de SMART nos escopos de recursos do FHIR.
+ `patient`os escopos concedem acesso a dados específicos sobre um único paciente.
+ `user`os escopos concedem acesso a dados específicos que um usuário pode acessar.
+ `system`os escopos concedem acesso a todos os recursos do FHIR encontrados no armazenamento de dados. HealthLake
As seções a seguir listam a sintaxe para construir escopos de recursos FHIR usando SMART no FHIR V1 ou SMART no FHIR V2.
**nota**
A estratégia de autorização SMART on FHIR é definida quando seu armazenamento de dados é criado. Para obter mais informações, consulte [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy) na *Referência de APIs do AWS HealthLake *.
### SMART em escopos FHIR V1 suportados por HealthLake
Ao usar o SMART no FHIR V1, a sintaxe geral para construir escopos de recursos do FHIR é a seguinte. HealthLake Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
```
**SMART em escopos de autorização compatíveis com FHIR v1**
| Sintaxe do escopo | Exemplo de escopo | Resultado |
| --- | --- | --- |
| `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\$1 | O aplicativo cliente do paciente tem acesso de leitura/gravação em nível de instância a todas as alergias registradas. |
| `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | O aplicativo cliente do usuário tem read/write acesso em nível de instância a todas as observações registradas. |
| system/('read' \$1 'write' \$1 \$1) | system/\$1.\$1 | O aplicativo cliente do sistema tem read/write acesso a todos os dados de recursos do FHIR. |
### SMART em escopos FHIR V2 suportados por HealthLake
Ao usar o SMART no FHIR V2, a sintaxe geral para construir escopos de recursos do FHIR é a seguinte. HealthLake Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
```
**nota**
Para usar o SMART no FHIR V2, você deve passar o valor [https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)para a `capabilities` string de metadados, que é um membro do tipo de dados. [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)
HealthLake suporta escopos granulares. Para obter mais informações, consulte os [escopos granulares compatíveis](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported) no *FHIR US* Core Implementation Guide.
**SMART em escopos de autorização compatíveis com FHIR V2**
| Sintaxe do escopo | Exemplo de escopo V1 | Resultado |
| --- | --- | --- |
| `patient/Observation.rs` | user/Observation.read | Permissão para ler e pesquisar Observation recursos para o paciente atual. |
| `system/*.cruds` | system/\$1.\$1 | O aplicativo cliente do sistema tem create/read/update/delete/search acesso total a todos os dados de recursos do FHIR. |
# Validação de token usando AWS Lambda
Ao criar um HealthLake SMART no armazenamento de dados habilitado para FHIR, você deve fornecer o ARN da AWS Lambda função na solicitação. `CreateFHIRDatastore` O ARN da função Lambda é especificado no `IdentityProviderConfiguration` objeto usando o parâmetro. `IdpLambdaArn`
Você deve criar a função Lambda antes de criar seu SMART no armazenamento de dados habilitado para FHIR. Depois de criar o armazenamento de dados, o ARN do Lambda não pode ser alterado. Para ver o ARN do Lambda que você especificou quando o armazenamento de dados foi criado, use a ação da API. `DescribeFHIRDatastore`
**Para que uma solicitação FHIR REST seja bem-sucedida em um armazenamento de dados SMART no FHIR ativado, sua função Lambda deve fazer o seguinte:**
+ Retorne uma resposta em menos de 1 segundo para o endpoint do armazenamento de HealthLake dados.
+ Decodifique o token de acesso fornecido no cabeçalho de autorização da solicitação da API REST enviada pelo aplicativo cliente.
+ Atribua uma função de serviço do IAM que tenha permissões suficientes para realizar a solicitação da API FHIR REST.
+ As declarações a seguir são necessárias para concluir uma solicitação da API FHIR REST. Para saber mais, consulte [Declarações necessárias](reference-smart-on-fhir-authentication.md#server-response).
+ `nbf`
+ `exp`
+ `isAuthorized`
+ `aud`
+ `scope`
Ao trabalhar com o Lambda, você precisa criar uma função de execução e uma política baseada em recursos, além da sua função Lambda. A função de execução de uma função do Lambda é uma função do IAM que concede à função permissão para acessar os serviços e recursos da AWS necessários em tempo de execução. A política baseada em recursos que você fornece deve permitir HealthLake invocar sua função em seu nome.
As seções deste tópico descrevem um exemplo de solicitação de um aplicativo cliente e uma resposta decodificada, as etapas necessárias para criar uma função AWS Lambda e como criar uma política baseada em recursos que possa assumir. HealthLake
+ [Parte 1: Criando uma função Lambda](#smart-on-fhir-lambda-create)
+ [Parte 2: Criando uma função HealthLake de serviço usada pela função AWS Lambda](#smart-on-fhir-lambda-service-role)
+ [Parte 3: Atualizando a função de execução da função Lambda](#smart-on-fhir-lambda-service-role-execution-role)
+ [Parte 4: Adicionando uma política de recursos à sua função Lambda](#smart-on-fhir-lambda-invoke-healthlake)
+ [Parte 5: Provisionando a simultaneidade para sua função Lambda](#smart-on-fhir-lambda-function-scaling)
## Criação de uma função AWS Lambda
A função Lambda criada neste tópico é acionada quando HealthLake recebe uma solicitação para um SMART no armazenamento de dados habilitado para FHIR. A solicitação do aplicativo cliente contém uma chamada à API REST e um cabeçalho de autorização contendo um token de acesso.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Authorization: Bearer i8hweunweunweofiwweoijewiwe
```
O exemplo da função Lambda neste tópico é usado AWS Secrets Manager para obscurecer as credenciais relacionadas ao servidor de autorização. É altamente recomendável não fornecer detalhes de login do servidor de autorização diretamente em uma função Lambda.
**Example validando uma solicitação FHIR REST contendo um token do portador da autorização**
O exemplo da função Lambda mostra como validar uma solicitação FHIR REST enviada para um SMART no armazenamento de dados habilitado para FHIR. Para ver step-by-steps instruções sobre como implementar essa função Lambda, consulte. [Criando uma função Lambda usando o Console de gerenciamento da AWS](#create-lambda-console)
Se a solicitação da API FHIR REST não contiver um endpoint de armazenamento de dados, token de acesso e operação REST válidos, a função Lambda falhará. Para saber mais sobre os elementos necessários do servidor de autorização, consulte[Declarações necessárias](reference-smart-on-fhir-authentication.md#server-response).
```
import base64
import boto3
import logging
import json
import os
from urllib import request, parse
logger = logging.getLogger()
logger.setLevel(logging.INFO)
## Uses Secrets manager to gain access to the access key ID and secret access key for the authorization server
client = boto3.client('secretsmanager', region_name="region-of-datastore")
response = client.get_secret_value(SecretId='name-specified-by-customer-in-secretsmanager')
secret = json.loads(response['SecretString'])
client_id = secret['client_id']
client_secret = secret['client_secret']
unencoded_auth = f'{client_id}:{client_secret}'
headers = {
'Authorization': f'Basic {base64.b64encode(unencoded_auth.encode()).decode()}',
'Content-Type': 'application/x-www-form-urlencoded'
}
auth_endpoint = os.environ['auth-server-base-url'] # Base URL of the Authorization server
user_role_arn = os.environ['iam-role-arn'] # The IAM role client application will use to complete the HTTP request on the datastore
def lambda_handler(event, context):
if 'datastoreEndpoint' not in event or 'operationName' not in event or 'bearerToken' not in event:
return {}
datastore_endpoint = event['datastoreEndpoint']
operation_name = event['operationName']
bearer_token = event['bearerToken']
logger.info('Datastore Endpoint [{}], Operation Name: [{}]'.format(datastore_endpoint, operation_name))
## To validate the token
auth_response = auth_with_provider(bearer_token)
logger.info('Auth response: [{}]'.format(auth_response))
auth_payload = json.loads(auth_response)
## Required parameters needed to be sent to the datastore endpoint for the HTTP request to go through
auth_payload["isAuthorized"] = bool(auth_payload["active"])
auth_payload["nbf"] = auth_payload["iat"]
return {"authPayload": auth_payload, "iamRoleARN": user_role_arn}
## access the server
def auth_with_provider(token):
data = {'token': token, 'token_type_hint': 'access_token'}
req = request.Request(url=auth_endpoint + '/v1/introspect', data=parse.urlencode(data).encode(), headers=headers)
with request.urlopen(req) as resp:
return resp.read().decode()
```
### Criando uma função Lambda usando o Console de gerenciamento da AWS
O procedimento a seguir pressupõe que você já tenha criado a função de serviço que deseja assumir HealthLake ao lidar com uma solicitação da API REST FHIR em um armazenamento de dados SMART no FHIR habilitado. Se você não criou a função de serviço, ainda pode criar a função Lambda. Você deve adicionar o ARN da função de serviço antes que a função Lambda funcione. Para saber mais sobre como criar uma função de serviço e especificá-la na função Lambda, consulte [Criação de uma função HealthLake de serviço para uso na função AWS Lambda usada para decodificar um JWT](#smart-on-fhir-lambda-service-role)
**Para criar uma função Lambda ()Console de gerenciamento da AWS**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home/functions) do console do Lambda.
1. Escolha a opção **Criar função**.
1. Selecione **Criar do zero**.
1. Em **Informações básicas**, insira um **nome de função**. Em **Tempo de execução**, escolha um tempo de execução baseado em python.
1. Em **Execution role** (Perfil de execução), escolha **Create a new role with basic Lambda permissions** (Criar um novo perfil com as permissões básicas do Lambda).
O Lambda cria uma [função de execução](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) que concede à função permissão para fazer upload de registros para a Amazon. CloudWatch A função Lambda assume a função de execução quando você invoca sua função e usa a função de execução para criar credenciais para o SDK. AWS
1. Escolha a guia **Código** e adicione o exemplo da função Lambda.
Se você ainda não criou a função de serviço para usar a função Lambda, precisará criá-la antes que a função de amostra do Lambda funcione. Para saber mais sobre a criação de uma função de serviço para a função Lambda, consulte. [Criação de uma função HealthLake de serviço para uso na função AWS Lambda usada para decodificar um JWT](#smart-on-fhir-lambda-service-role)
```
import base64
import boto3
import logging
import json
import os
from urllib import request, parse
logger = logging.getLogger()
logger.setLevel(logging.INFO)
## Uses Secrets manager to gain access to the access key ID and secret access key for the authorization server
client = boto3.client('secretsmanager', region_name="region-of-datastore")
response = client.get_secret_value(SecretId='name-specified-by-customer-in-secretsmanager')
secret = json.loads(response['SecretString'])
client_id = secret['client_id']
client_secret = secret['client_secret']
unencoded_auth = f'{client_id}:{client_secret}'
headers = {
'Authorization': f'Basic {base64.b64encode(unencoded_auth.encode()).decode()}',
'Content-Type': 'application/x-www-form-urlencoded'
}
auth_endpoint = os.environ['auth-server-base-url'] # Base URL of the Authorization server
user_role_arn = os.environ['iam-role-arn'] # The IAM role client application will use to complete the HTTP request on the datastore
def lambda_handler(event, context):
if 'datastoreEndpoint' not in event or 'operationName' not in event or 'bearerToken' not in event:
return {}
datastore_endpoint = event['datastoreEndpoint']
operation_name = event['operationName']
bearer_token = event['bearerToken']
logger.info('Datastore Endpoint [{}], Operation Name: [{}]'.format(datastore_endpoint, operation_name))
## To validate the token
auth_response = auth_with_provider(bearer_token)
logger.info('Auth response: [{}]'.format(auth_response))
auth_payload = json.loads(auth_response)
## Required parameters needed to be sent to the datastore endpoint for the HTTP request to go through
auth_payload["isAuthorized"] = bool(auth_payload["active"])
auth_payload["nbf"] = auth_payload["iat"]
return {"authPayload": auth_payload, "iamRoleARN": user_role_arn}
## Access the server
def auth_with_provider(token):
data = {'token': token, 'token_type_hint': 'access_token'}
req = request.Request(url=auth_endpoint + '/v1/introspect', data=parse.urlencode(data).encode(), headers=headers)
with request.urlopen(req) as resp:
return resp.read().decode()
```
### Modificando a função de execução de uma função Lambda
Depois de criar a função Lambda, você precisa atualizar a função de execução para incluir as permissões necessárias para chamar o Secrets Manager. No Secrets Manager, cada segredo que você cria tem um ARN. Para aplicar o menor privilégio, a função de execução só deve ter acesso aos recursos necessários para a execução da função Lambda.
Você pode modificar a função de execução de uma função Lambda pesquisando-a no console do IAM ou escolhendo **Configuração** no console Lambda. Para saber mais sobre como gerenciar sua função de execução de funções Lambda, consulte. [Função de execução do Lambda](#smart-on-fhir-lambda-service-role-execution-role)
**Example Função de execução da função Lambda que concede acesso a `GetSecretValue`**
Adicionar a ação do IAM `GetSecretValue` à função de execução concede a permissão necessária para que a função de amostra do Lambda funcione.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:secret-name-DKodTA"
}
]
}
```
Neste ponto, você criou uma função Lambda que pode ser usada para validar o token de acesso fornecido como parte da solicitação FHIR REST enviada ao seu SMART no armazenamento de dados habilitado para FHIR.
## Criação de uma função HealthLake de serviço para uso na função AWS Lambda usada para decodificar um JWT
**Persona: administrador do IAM**
Um usuário que pode adicionar ou remover políticas do IAM e criar novas identidades do IAM.
**Perfil de serviço**
O perfil de serviço é um [perfil do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) que um serviço assume para executar ações em seu nome. Um administrador do IAM pode criar, modificar e excluir um perfil de serviço do IAM. Para saber mais, consulte [Criar um perfil para delegar permissões a um AWS service (Serviço da AWS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) no *Guia do Usuário do IAM*.
Depois que o JSON Web Token (JWT) é decodificado, a autorização Lambda também precisa retornar um ARN de função do IAM. Essa função deve ter as permissões necessárias para realizar a solicitação da API REST ou falhará devido a permissões insuficientes.
Ao configurar uma política personalizada usando o IAM, é melhor conceder as permissões mínimas necessárias. *Para saber mais, consulte [Aplicar permissões de privilégios mínimos](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) no Guia do usuário do IAM.*
A criação HealthLake de uma função de serviço para designar na função Lambda de autorização requer duas etapas.
+ Primeiro, você precisa criar uma política do IAM. A política deve especificar o acesso aos recursos do FHIR para os quais você forneceu escopos no servidor de autorização.
+ Em segundo lugar, você precisa criar a função de serviço. Ao criar a função, você designa uma relação de confiança e anexa a política criada na etapa um. A relação de confiança é designada HealthLake como principal do serviço. Você precisa especificar um ARN do armazenamento de HealthLake dados e uma ID de AWS conta nesta etapa.
### Criação de uma nova política do IAM
Os escopos que você define em seu servidor de autorização determinam a quais recursos FHIR um usuário autenticado tem acesso em um armazenamento de dados. HealthLake
A política do IAM que você cria pode ser personalizada para corresponder aos escopos que você definiu.
As ações a seguir no `Action` elemento de uma declaração de política do IAM podem ser definidas. Para cada um `Action` na tabela, você pode definir um`Resource types`. Em HealthLake um armazenamento de dados, é o único tipo de recurso compatível que pode ser definido no `Resource` elemento de uma declaração de política de permissão do IAM.
Recursos individuais do FHIR não são um recurso que você possa definir como um elemento em uma política de permissão do IAM.
**Ações definidas por HealthLake**
| Ações | Descrição | Nível de acesso | Tipo de recurso (obrigatório) |
| --- | --- | --- | --- |
| CreateResource | Concede permissão a um recurso de criação | Gravar | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| DeleteResource | Concede permissão para excluir um recurso | Gravar | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| ReadResource | Concede permissão para ler um recurso | Ler | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| SearchWithGet | Concede permissão para pesquisar recursos com o método GET | Ler | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| SearchWithPost | Concede permissão para pesquisar recursos com o método POST | Ler | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| Iniciar FHIRExport JobWithPost | Concede permissão para iniciar um trabalho de exportação FHIR com GET | Gravar | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
| UpdateResource | Concede permissão para atualizar um recurso | Gravar | ARN do armazenamento de dados: arn:aws:healthlake: ::datastore/fhir/ your-region 111122223333 your-datastore-id |
Para começar, você pode usar`AmazonHealthLakeFullAccess`. Essa política permitiria leitura, gravação, pesquisa e exportação em todos os recursos do FHIR encontrados em um armazenamento de dados. Para conceder permissões somente de leitura em um armazenamento de dados, use. `AmazonHealthLakeReadOnlyAccess`
Para saber mais sobre como criar uma política personalizada usando o Console de gerenciamento da AWS, AWS CLI, ou IAM SDKs, consulte [Como criar políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) no *Guia do usuário do IAM*.
### Criação de uma função de serviço para HealthLake (console do IAM)
Use esse procedimento para criar uma função de serviço. Ao criar um serviço, você também precisará designar uma política do IAM.
**Para criar a função de serviço para HealthLake (console do IAM)**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. No painel de navegação do console do IAM, escolha **Perfis**.
1. Depois, escolha **Create role** (Criar perfil).
1. Na página **Selecionar entidade confiável**, escolha **Política de confiança personalizada**.
1. Em seguida, em **Política de confiança personalizada**, atualize a política de amostra da seguinte forma. **your-account-id**Substitua pelo número da sua conta e adicione o ARN do armazenamento de dados que você deseja usar em seus trabalhos de importação ou exportação.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"Service": "healthlake.amazonaws.com"
},
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:healthlake:us-east-1:123456789012:datastore/fhir/your-datastore-id"
}
}
}
]
}
```
------
1. Em seguida, escolha **Próximo**.
1. Na página **Adicionar permissões**, escolha a política que você deseja que o HealthLake serviço assuma. Para encontrar sua política, procure-a em **Políticas de permissões**.
1. Em seguida, escolha **Anexar política**.
1. Em seguida, na página **Nome, revise e crie**, em **Nome da função**, insira um nome.
1. (Opcional) Em seguida, em **Descrição**, adicione uma breve descrição para sua função.
1. Se possível, insira um nome de função ou sufixo de nome de função para ajudar a identificar o propósito desta função. Os nomes de função devem ser exclusivos em sua Conta da AWS. Eles não são diferenciados por maiúsculas e minúsculas. Por exemplo, não é possível criar perfis denominados **PRODROLE** e **prodrole**. Como várias entidades podem fazer referência à função, não é possível editar o nome da função depois que ela é criada.
1. Revise os detalhes da função e escolha **Criar função**.
Para saber como especificar o ARN da função no exemplo da função Lambda, consulte. [Criação de uma função AWS Lambda](#smart-on-fhir-lambda-create)
## Função de execução do Lambda
A função de execução de uma função Lambda é uma função do IAM que concede à função permissão para acessar AWS serviços e recursos. Esta página fornece informações sobre como criar, visualizar e gerenciar o perfil de execução de uma função do Lambda.
Por padrão, o Lambda cria uma função de execução com permissões mínimas quando você cria uma nova função do Lambda usando o. Console de gerenciamento da AWS Para gerenciar as permissões concedidas na função de execução, consulte [Criação de uma função de execução no console do IAM](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html#permissions-executionrole-console) no *Lambda Developer* Guide.
O exemplo da função Lambda fornecido neste tópico usa o Secrets Manager para ocultar as credenciais do servidor de autorização.
Como acontece com qualquer função do IAM que você criar, é importante seguir as melhores práticas de privilégios mínimos. Durante a frase de desenvolvimento, às vezes você pode conceder permissões além do necessário. Antes de publicar sua função no ambiente de produção, como prática recomendada, ajuste a política para incluir somente as permissões necessárias. *Para obter mais informações, consulte [Aplicar o menor privilégio](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) no Guia do usuário do IAM.*
## Permitir HealthLake acionar sua função Lambda
Para que HealthLake possa invocar a função Lambda em seu nome, você deve fazer o seguinte:
+ Você precisa definir `IdpLambdaArn` igual ao ARN da função Lambda que você deseja HealthLake invocar na solicitação. `CreateFHIRDatastore`
+ Você precisa de uma política baseada em recursos que permita HealthLake invocar a função Lambda em seu nome.
Quando HealthLake recebe uma solicitação da API REST FHIR em um armazenamento de dados SMART no FHIR ativado, ele precisa de permissões para invocar a função Lambda especificada na criação do armazenamento de dados em seu nome. Para conceder HealthLake acesso, você usará uma política baseada em recursos. *Para saber mais sobre como criar uma política baseada em recursos para uma função do Lambda, consulte [Permitir que um AWS serviço chame uma função do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke) no Guia do desenvolvedor.AWS Lambda *
## Provisionando a simultaneidade para sua função Lambda
**Importante**
HealthLake exige que o tempo máximo de execução da função Lambda seja inferior a um segundo (1000 milissegundos).
Se sua função Lambda exceder o limite de tempo de execução, você receberá uma TimeOutexceção.
Para evitar essa exceção, recomendamos configurar a simultaneidade provisionada. Ao alocar simultaneidade provisionada antes de um aumento nas invocações, é possível garantir que todas as solicitações sejam atendidas por instâncias inicializadas com latência baixa. *Para saber mais sobre como configurar a simultaneidade provisionada, consulte Como configurar a simultaneidade provisionada no [Lambda Developer Guide](https://docs.aws.amazon.com/ambda/latest/dg/provisioned-concurrency.html)*
Para ver o tempo médio de execução de sua função Lambda atualmente, use a página de **monitoramento** de sua função Lambda no console Lambda. Por padrão, o console Lambda fornece um gráfico de **duração** que mostra a quantidade média, mínima e máxima de tempo que seu código de função gasta processando um evento. *Para saber mais sobre o monitoramento das funções do Lambda, consulte Funções de [monitoramento no console do Lambda no Guia do desenvolvedor do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions-access-metrics.html#monitoring-console-graph-types).*
*Se você já provisionou a simultaneidade para sua função do Lambda e deseja monitorá-la, consulte Monitoramento da [simultaneidade no](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-concurrency.html) Guia do desenvolvedor do Lambda.*
# Usando autorização refinada com um SMART no armazenamento de dados habilitado para FHIR HealthLake
[Os escopos](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest) por si só não fornecem a especificidade necessária sobre quais dados um solicitante está autorizado a acessar em um armazenamento de dados. O uso de autorização refinada permite um nível mais alto de especificidade ao conceder acesso a um SMART no armazenamento de dados habilitado para FHIR. HealthLake Para usar uma autorização refinada, defina `FineGrainedAuthorizationEnabled` igual a `True` no `IdentityProviderConfiguration` parâmetro da sua solicitação. `CreateFHIRDatastore`
Se você habilitou a autorização refinada, seu servidor de autorização retornará um `fhirUser` escopo `id_token` junto com o token de acesso. Isso permite que as informações sobre o usuário sejam recuperadas pelo aplicativo do cliente. O aplicativo cliente deve tratar a `fhirUser` declaração como o URI de um recurso FHIR representando o usuário atual. Pode ser `Patient`, `Practitioner` ou `RelatedPerson`. A resposta do servidor de autorização também inclui um `user/` escopo que define quais dados o usuário pode acessar. Isso usa a sintaxe definida para escopos relacionados aos escopos específicos de recursos do FHIR:
```
user/(fhir-resource | '*').('read' | 'write' | '*')
```
A seguir estão exemplos de como a autorização refinada pode ser usada para especificar ainda mais os tipos de recursos FHIR relacionados ao acesso a dados.
+ Quando `fhirUser` é uma `Practitioner` autorização refinada determina a coleção de pacientes que o usuário pode acessar. `fhirUser`O acesso é permitido apenas para os pacientes em que o paciente se refere ao `fhirUser` como clínico geral.
```
Patient.generalPractitioner : [{Reference(Practitioner)}]
```
+ Quando `fhirUser` é um `Patient` ou `RelatedPerson` e o paciente referenciado na solicitação é diferente do`fhirUser`, uma autorização refinada determina o acesso `fhirUser` do paciente solicitado. O acesso é permitido quando há um relacionamento especificado no `Patient` recurso solicitado.
```
Patient.link.other : {Reference(Patient|RelatedPerson)}
```
# Buscando o SMART no documento FHIR Discovery
O SMART define um documento de descoberta que permite que os clientes conheçam o endpoint de autorização URLs e os recursos que um armazenamento HealthLake de dados suporta. Essas informações ajudam os clientes a direcionar as solicitações de autorização para o endpoint correto e a criar solicitações de autorização suportadas pelo armazenamento de HealthLake dados.
Para que um aplicativo cliente faça uma solicitação FHIR REST bem-sucedida HealthLake, ele deve reunir os requisitos de autorização definidos pelo armazenamento de HealthLake dados. *Não* é necessário um token de portador (autorização) para que essa solicitação seja bem-sucedida.
**Para solicitar o Documento de Descoberta para um armazenamento HealthLake de dados**
1. Colecione HealthLake `region` e `datastoreId` valorize. Para obter mais informações, consulte [Obter propriedades do datastore](managing-data-stores-describe.md).
1. Crie uma URL para a solicitação usando os valores coletados para HealthLake `region` `datastoreId` e. Anexe `/.well-known/smart-configuration` ao endpoint do URL. Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**.
```
https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/.well-known/smart-configuration
```
1. Envie a solicitação usando o protocolo `GET` de [AWS assinatura Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Para ver o exemplo inteiro, role até o botão **Copiar**.
------
#### [ curl ]
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/.well-known/smart-configuration \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
O documento de descoberta do armazenamento de HealthLake dados retorna como um blob JSON, onde você pode encontrar o `authorization_endpoint` e o`token_endpoint`, junto com as especificações e os recursos definidos para o armazenamento de dados.
```
{
"authorization_endpoint": "https://oidc.example.com/authorize",
"token_endpoint": "https://oidc.example.com/oauth/token",
"capabilities": [
"launch-ehr",
"client-public"
]
}
```
Tanto o `authorization_endpoint` quanto o `token_endpoint` são necessários para iniciar um aplicativo cliente.
+ **Ponto final de autorização** — O URL necessário para autorizar um aplicativo ou usuário cliente.
+ **Ponto final do token** — O ponto final do servidor de autorização com o qual o aplicativo cliente usa para se comunicar.
# Fazendo uma solicitação da API FHIR REST em um armazenamento de dados habilitado para Smart HealthLake
Você pode fazer solicitações da API REST FHIR em um SMART no armazenamento de dados habilitado para HealthLake FHIR. O exemplo a seguir mostra uma solicitação do aplicativo cliente contendo um JWT no cabeçalho de autorização e como o Lambda deve decodificar a resposta. Depois que a solicitação do aplicativo cliente for autorizada e autenticada, ela deverá receber um token portador do servidor de autorização. Use o token do portador no cabeçalho de autorização ao enviar uma solicitação da API REST FHIR em um SMART no armazenamento de dados habilitado para HealthLake FHIR.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/[ID]
Authorization: Bearer auth-server-provided-bearer-token
```
Como um token portador foi encontrado no cabeçalho de autorização e nenhuma identidade AWS do IAM foi detectada, HealthLake invoca a função Lambda especificada quando o SMART no armazenamento de dados habilitado para FHIR foi criado. HealthLake Quando o token é decodificado com sucesso pela sua função Lambda, o exemplo de resposta a seguir é enviado para. HealthLake
```
{
"authPayload": {
"iss": "https://authorization-server-endpoint/oauth2/token", # The issuer identifier of the authorization server
"aud": "https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/", # Required, data store endpoint
"iat": 1677115637, # Identifies the time at which the token was issued
"nbf": 1677115637, # Required, the earliest time the JWT would be valid
"exp": 1997877061, # Required, the time at which the JWT is no longer valid
"isAuthorized": "true", # Required, boolean indicating the request has been authorized
"uid": "100101", # Unique identifier returned by the auth server
"scope": "system/*.*" # Required, the scope of the request
},
"iamRoleARN": "iam-role-arn" #Required, IAM role to complete the request
}
```