---
description: Step-by-step guide to implement SMART App Launch with Aidbox, Keycloak, and Growth Chart app using Docker.
---

# Example: SMART app launch using Aidbox and Keycloak

This example showcases the Smart App EHR and Patient [launch flows](https://hl7.org/fhir/smart-app-launch/app-launch.html).

## Components

1. Aidbox FHIR server with SMART-on-FHIR support.
2. [Keycloak](https://www.keycloak.org/)\
   Identity and Access Management solution that integrates with Aidbox through the [IdentityProvider](../../authentication/sso-with-external-identity-provider.md) resource.
3. [Growth Chart Smart App](https://github.com/smart-on-fhir/growth-chart-app)\
   A SMART pediatric web application that displays patient growth charts based on their observations.
4. **Demo Launcher Page**\
   A web page that emulates EHR patient context selection.

## Prerequisites

* [Docker](https://www.docker.com/)
* Cloned repository: [Github: Aidbox/examples](https://github.com/Aidbox/examples/tree/main)
* Working directory: `smart-app-launch`

To clone the repository and navigate to the `smart-app-launch` directory, run:

```sh
git clone git@github.com:Aidbox/examples.git && cd examples/smart-app-launch 
```

## Step 1: Run Demo Components

Start all the demo components by running:

```sh
docker compose up
```

Wait until all components are pulled and started. The components are accessible at:

* Aidbox - [http://localhost:8080](http://localhost:8080)
* Keycloak - [http://localhost:8888](http://localhost:8888)
* Growth Chart - [http://localhost:9000](http://localhost:9000)
* Demo Launcher Page - [http://localhost:7070/launcher.html](http://localhost:7070/launcher.html)

## Step 2: Open launcher Page

Open the [Demo Launcher Page](http://localhost:7070/launcher.html).

* **Left Side:** A list of patients retrieved from Aidbox, simulating EHR patient context selection.
* **Right Side:** A Patient Standalone Launch with a pre-selected patient context, simulating a launch directly from the SMART App.

## Step 3: Perform EHR Launch

**3.1** Select a patient from the list on the left side and click the `Launch Growth Chart App` button to start the launch process.\
**3.2** On the Aidbox login screen, click the `Sign in with Keycloak` button.\
**3.3** Log in to Keycloak with username `patient` and password `password`\
**3.4** On the consent screen, allow all requested scopes.\
**3.5** View the patient's data in the Growth Chart app.

## Step 4: Perform Patient Standalone Launch

**4.1** Go back to the [Demo Launcher](http://localhost:7070/launcher.html)\
**4.2** On the right side of the screen, click the **Launch Growth Chart App** button under Patient Standalone Launch.\
**4.2** On the consent screen, allow all requested scopes.\
**4.3** View the patient's data in the Growth Chart app.

## EHR Launch Interaction Diagram

```
┌──────┐        ┌──────────────────┐  ┌────────┐                            ┌──────────┐                                 
│ User │        │       EHR        │  │ Aidbox │                            │ Keycloak │                                 
└──────┘        │  (Demo Launcher) │  └────────┘                            └──────────┘                                 
    ┬           └─────────┬────────┘       ┬                                      ┬                                      
    │                     │                │                                      │                                      
    │  Launch Smart App   │                │                                      │                                      
    │─────────────────────▶                │                                      │                                      
    │                     │                │                                      │                                      
    │                     │                │   Redirect to Keycloak Login page    │                                      
    │                     │                │──────────────────────────────────────▶                                      
    │                     │                │                                      │                                      
    │                     │                │                                      │ ┌─────────────────────────────────┐  
    │                     │                │                                      │ │ Login with Keycloak credentials │  
    │                     │                │                                      │ └─────────────────────────────────┘  
    │                     │                │                                      │                                      
    │                     │                │         Response with code           │                                      
    │                     │                ◀──────────────────────────────────────│                                      
    │                     │                │                                      │                                      
    │                     │                │  Request to exchange code to token   │                                      
    │                     │                │──────────────────────────────────────▶                                      
    │                     │                │                                      │                                      
    │                     │                │            Return token              │                                      
    │                     │                ◀──────────────────────────────────────│                                      
    │                     │                │                                      │                                      
    │                     │                │          Request user info           │                                      
    │                     │                │──────────────────────────────────────▶                                      
    │                     │                │                                      │                                      
    │                     │                │          Return user info            │                                      
    │                     │                ◀──────────────────────────────────────│                                      
    │                     │                │                                      │                                      
    │                     │                ├───┐                                  │                                      
    │                     │                │   │ Create User resource in Aidbox   │                                      
    │                     │                ◀───┘                                  │                                      
    │                     │                │                                      │                                      
    │        Show the Grant screen         │                                      │                                      
    ◀──────────────────────────────────────│                                      │                                      
    │                     │                │                                      │                                      
    │       Allow requested scopes         │                                      │                                      
    │──────────────────────────────────────▶                                      │                                      
    │                     │                │                                      │                                      
    │                     │                ├───┐                                  │                                      
    │                     │                │   │ Check granted permissions        │                                      
    │                     │                ◀───┘                                  │                                      
    │                     │                │                                      │                                      
    │                     │                ├───┐                                  │                                      
    │                     │                │   │ Validate scopes from token       │                                      
    │                     │                ◀───┘                                  │                                      
    │                     │                │                                      │                                      
┌───┴──┐        ┌─────────┴────────┐  ┌────┴───┐                            ┌─────┴────┐                                 
│ User │        │       EHR        │  │ Aidbox │                            │ Keycloak │                                 
└──────┘        │  (Demo Launcher) │  └────────┘                            └──────────┘                                 
                └──────────────────┘                                                                                     
```